Thursday, December 5, 2013

WhirlyGlobe 2.2

I'm pleased to announce the release of WhirlyGlobe 2.2.

WhirlyGlobe is a 3D globe rendering toolkit for iPad and iPhone based on OpenGL ES 2.0.  It lets you put labels, markers, vectors, and shapes on top of a 3D interactive globe with one or more base layers of pageable image data.

Check out the video for a quick tour.



WhirlyGlobe presents a nice, simple Objective-C interface and uses standard MVC constructs such as view controllers and delegates.  It's very easy to integrate into your own app.

Where To Get It

The github repository is the best place.  The master branch is on 2.2.  You'll want to check out the readme, but basically it goes like this.

  • git clone https://github.com/mousebird/WhirlyGlobe.git WhirlyGlobe-Maply
  • cd WhirlyGlobe-Maply
  • git submodule init
  • git submodule update
  • Open the WhirlyGlobeComponentTester in Xcode
All the example data is in one of the submodules, so it takes a while.

There's also a binary distribution.  Download it and open the WhirlyGlobeComponentTester example.


Using The Framework - GitHub

It's pretty easy to use WhirlyGlobe in your own project.  If you're using WhirlyGlobe as a submodule, it's like so:

  • Set up a brand new project for your app with git enabled.
  • cd to the root directory of the project
  • mkdir libs
  • git submodule add https://github.com/mousebird/WhirlyGlobe.git libs/WhirlyGlobe-Maply
  • git submodule init
  • git submodule update
  • cd libs/WhirlyGlobe-Maply
  • git submodule init
  • git submodule update
One of WhirlyGlobe's submodules contains all the source data, so that'll take a while.  You only have to do it once.

Then in your Xcode project, do the following:
  • Go to Build Phases and open "Link Binary With Libraries".
  • Hit +
  • Select "Add Other"
  • Navigate to libs/WhirlyGlobeSrc/WhirlyGlobe-MaplyComponent/
  • Select WhirlyGlobe-MaplyComponent.xcodeproj
  • Hit + again
  • Select libWhirlyGlobe-MaplyComponent.a
  • Add a few other libraries you'll need
    • libc++
    • CoreLocation
    • libz
    • libxml2
    • libsqlite3
  • In Build Settings find "Header Search Paths"
  • Add the path "$(SRCROOT)/libs/WhirlyGlobe-Maply/WhirlyGlobeSrc/WhirlyGlobe-MaplyComponent/include/"
You should now be able to pull in WhirlyGlobeComponent.h and compile.

Using The Framework - Binary Distribution


If you're using the binary distribution instead of github, there are even fewer steps.
  • Set up a brand new project for your app.
  • Go to Build Phases and open "Link Binary With Libraries".
  • Hit +
  • Select Add Other
  • Navigate to WhirlyGlobeMaplyComponent.framework in the binary distribution and select it.
  • Hit + again
  • Select libWhirlyGlobe-MaplyComponent.a
  • Add a few other libraries you'll need
    • libc++
    • CoreLocation
    • libz
    • libxml2
    • libsqlite3
  • In Build Settings find "Header Search Paths"
  • Add the path to "$(binary dist path)/WhirlyGlobeMaplyComponent.framework/Headers".  You fill in the binary dist path.
You should now be able to pull in WhirlyGlobeComponent.h and compile.

Documentation

The full set of reference documentation is now available.  That's documentation for each of the Objective-C classes.  The crazy C++ internals are not documented there, so think twice before using them.

To see what's possible, consult the WhirlyGlobeComponentTester app which is included both in git and the binary distribution.  TestViewController.m is the best place to start.  Getting a simple globe up and running is surprisingly easy.