WhirlyGlobe Component: Vectors

I'm running a bit behind on new describing new functionality.    A few weeks ago I added vector support to the WhirlyGlobe Component.

The toolkit itself has had vector support since 1.0.  That's kinda my thing.  Images are everyone else's thing, though so that's what went in to the Component first.

Some Vectors, no doubt.

So great, how do they work?

WGVectorObject

The WGVectorObject is a wrapper around the more complex classes in the WhirlyGlobe API.  If you want better control, go use those.  If you want to do a few simple operations, WGVectorObject will do.

A WGVectorObject can represent one or more features.  It's a little goofy, but makes sense once you start slinging them around.  Just treat them as somewhat opaque.

First thing you'll want to do is load them.  There are a variety of ways.

Vectors From GeoJSON

As the heading implies, you can load GeoJSON.  Here's a quick example that looks for a named file in the bundle, loads that into a WGVectorObject and then adds it to the globe.

                    
NSString *fileName = [[NSBundle mainBundle] pathForResource:name ofType:@"geojson"];
if (fileName)
{
  NSData *jsonData = [NSData dataWithContentsOfFile:fileName];
  if (jsonData)
  {
    WGVectorObject *wgVecObj = [WGVectorObject VectorObjectFromGeoJSON:jsonData];
    WGComponentObject *compObj = [globeViewC addVectors:[NSArray arrayWithObject:wgVecObj]];
  }
}

If you're generating the files yourself or reading from a remote service, it's nice, but it's slow.  Who would think parsing geometry out of a text file would be slow?  I'm shocked.

Vectors From Scratch

You can also create vector data from scratch.  You can make points, linears, and areals.  The following methods are part of WGVectorObject.

                    
/// Construct with a single point
- (id)initWithPoint:(WGCoordinate *)coord attributes:(NSDictionary *)attr;

/// Construct with a linear feature (e.g. line string)
- (id)initWithLineString:(WGCoordinate *)coords numCoords:(int)numCoords attributes:(NSDictionary *)attr;

/// Construct as an areal with an exterior
- (id)initWithAreal:(WGCoordinate *)coords numCoords:(int)numCoords attributes:(NSDictionary *)attr;

/// Add a hole to an existing areal feature
- (void)addHole:(WGCoordinate *)coords numCoords:(int)numCoords;

Just gather your WGCoordinate structures into an array and pass them in for linear or areal.  For points, just pass in the one and if you need to create holes (in an areal), call that method after you've created the areal.

Vectors From Shapefiles

Lastly, you can read vector data out of Shapefiles.  I wrap these things in a database-like object so I can do (somewhat) fast lookups.  The object you want is called a MaplyVectorDatabase, but it's only in the source tree at the moment.  I haven't updated the pre-compiled Component.

I'm exposing functionality as I need it, so the MaplyVectorDatabase object just does the following for now.

                    
/// Construct from a shapefile in the bundle
+ (MaplyVectorDatabase *) vectorDatabaseWithShape:(NSString *)shapeName;

/// Return vectors that match the given SQL query
- (MaplyVectorObject *)fetchMatchingVectors:(NSString *)sqlQuery;

/// Search for all the areals that surround the given point (in geographic)
- (MaplyVectorObject *)fetchArealsForPoint:(MaplyCoordinate)coord;

Maply?  Yes, Maply.  All new functionality is Maply, with WhirlyGlobe reserved for things that are globe specific.  Surprisingly, that's very little.

Anyway, the basic idea with a MaplyVectorDatabase is that you create it with that shapefile name and then run simple queries against it.  I've exposed the fetch matching vectors and fetch areals for point (e.g. point in poly search).  That's enough to reimplement the WhirlyGlobeApp, but I'm sure I'll expose more in the future.

As with the WhirlyGlobe API, the Component is going to build cache files next to your shapefiles.  There will be one name.mbr and one name.sqlite file.  If they don't exist, the toolkit will build them and that'll be sloooow.  So grab them out of the simulator and stick them in your bundle.

Displaying Vectors

Once you've got some vectors, you can display them.  As always, bigger batches are better, smaller are slower.  The call to add vectors to a WhirlyGlobeViewController is just like so.

WGComponentObject *compObj = [globeViewC addVectors:[NSArray arrayWithObject:wgVecObj]];

Vectors are then eligible for selection and they'll turn up in your globe view controller delegate like everything else.  They show up after labels and markers in priority, as their search is run last.

Upcoming Stuff

There's a lot more in the pipeline for WhirlyGlobe, Maply, and the Components.  Most of my time is devoted to WhirlyGlobe/Maply projects for clients and they're all spinning stuff back in to the toolkits.  Some of it is structural, such as OpenGL ES 2.0 support and some is pure features, such as a Shape layer.

Coming up next is WhirlyGlobe 2.1, which will be a minor release of what's in the master branch.  Primarily tweaks for retina, caps for the Spherical Mercator layers, and random bug fixes.