Classes

Active Objects are used implement animation.

Active Objects work in conjuction with the renderer to make updates on the main thread.  The way they work is this.  They're called right at the beginning of a frame draw.  They can make updates to regular Maply objects via the MaplyBaseViewController add and remove calls with the MaplyThreadMode set to MaplyThreadCurrent.  This forces the changes to happen immediately on the current (main) thread.

Active Objects have access to the internals of the toolkit, for historical reasons.  That makes it difficult to document them here.  Look at the AnimationTest example in the test app.  You will need to fill in the following methods at least.

Active Objects are run on the main thread and you're probably going to be asking the view controller to add and remove objects on the main thread.  As such, this can be slow.  Be sure to precalculate whatever you might need to make this run faster.  Also consider implementing your changes another way.  If it can be done on another thread, do it on another thread.

Represents an Aeris layer.

This object contains information about an Aeris weather image layer.

Don’t construct these objects except from the MaplyAerisTiles object. Instead, get them from MaplyAerisTiles.

MaplyAerisTiles provides access to available layer information.

Instantiate a MaplyAerisTiles object to retrieve information about available Aeris weather imagery layers.

A MaplyAerisTileSet object provides tile sources for display in WhirlyGlobe-Maply.

The MaplyAerisTileSet object provides access to weather imagery from Aeris. Instantiate this object with the desired layer and number of frames. Then, initiate a fetch of the most recent frames. MaplyAerisTileSet will provide an array of tile sources that can be combined using a MaplyMultiplexTileSource to feed a MaplyQuadImageTilesLayer, which will display the imagery on the map or globe.

The animation test tile source provides fake images to test the animation functionality in the quad image tiles layer. In general, don’t use it for anything.

This object displays an annotation at a particular point and will track that point as the map or globe moves.

An annotation is used to point out some feature on the globe or map, typically that the user has tapped on. It’s a multi-part beast that may contain titles, subtitles, images, background views and such.

To add one, create the MaplyAnnotation and then call addAnnotation:forPoint:offset: on the MaplyBaseViewController.

The MaplyAnnotation is a wrapper around the SMCalloutView by Nick Farina. It exposes much of the functionality, but sets things up correctly and deals with moving the annotation around.

Sets up the objects and shaders to implement an atmosphere.

This object sets up a shader implementation of the simple atmosphere from GPU Gems 2 http://http.developer.nvidia.com/GPUGems2/gpugems2_chapter16.html

When selecting multiple objects, one or more of these is returned.

When you implement one of the selection delegates that takes multiple objects, you’ll get an NSArray of these things.

Base class for the Maply and WhirlyGlobe view controllers.

The Maply Base View Controller is where most of the functionality lives. For the most part Maply and WhirlyGlobe share methods and data structures. This view controller sets up the rendering, the threading, basically everything that makes WhirlyGlobe-Maply work.

Don’t create one of these directly, instead use the MaplyViewController or the WhirlyGlobeViewController.

A billboard is tied to a specific point, but rotates to face the user.

The billboard object represents a rectangle which is rooted at a specific point, but will rotate to face the user. These are typically used in 3D, when the globe or map has a tilt. They make little sense in 2D.

A blank tile sources just generates a single colored image for each tile.

Information about the group of objects to cluster.

This object is passed in when the developer needs to make an image for a group of objects.

Visual representation for a group of markers.

Fill this in for the

The basic cluster generator installed by default.

This cluster generator will make images for grouped clusters of markers/labels.

The color ramp generator will take a set of color values and generate a linear ramp of those colors in an output image. You typically feed the color ramp image into a shader.

Used to represent the view controller resources attached to one or more visual objects.

When you add one or more objects to a view controller, you’ll get a component object back. It’s an opaque object (seriously, don’t look inside) that we use to track various resources within the toolkit.

You can keep these around to remove the visual objects you added earlier, but that’s about all the interaction you’ll have with them.

An NSObject based wrapper for 3D coordinates.

This wrapper encapsulates a MaplyCoordinate3d so we can pass them around in NSDictionary objects.

An NSObject based wrapper for 3D coordinates.

This wrapper encapsulates a MaplyCoordinate3d so we can pass them around in NSDictionary objects.

Coordinate system for tiling systems and data sources and such.

This object represents the spatial reference system and bounding box for objects like the MaplyTileSource or vectors or other things. Not all data is in lat/lon geographic (actually MaplyPlateCaree) nor is it always in MaplySphericalMercator. Sometimes it’s in one or the other, or a bit of both.

We use this base class to express the coordinate system and we threw in the bounding box, which we will surely come to regret. Oh well, it’s in there.

This object gets passed around to tell us what coordinate system data is in or how we’re displaying things. Right now only MaplySphericalMercator and MaplyPlateCarree are represented. In the future, there will be more.

Plate Carree is lat/lon stretched out to its full extents.

This coordinate system is used when we’re tiling things over the whole earth, from -180 to +180 and from -90 to +90. Use this if you chopped up your data in that way.

Spherical Mercator is what you’ll most commonly see on web maps.

The Spherical Mercator system, with web extents is what MapBox, Google, Bing, etc. use for their maps. If you ever want to annoy a cartographer, suggest that spherical mercator is all you ever really need.

The drawback with Spherical Mercator is that it doesn’t cover the poles and it distorts (and how) its north and south extents. Web Standard refers to the extents you’ll find in most online maps. This is probably want you want.

A generic coordinate system wrapper around proj4.

You create one of these with a proj4 string. It’ll act like a normal MaplyCoordinateSysterm after that.

Be sure to check that the system is valid. The proj4 string could be wrong.

An elevation source corresponding to a custom sqlite database.

The Maply Elevation Database object interfaces to a custom sqlite database that contains elevation tiles. This is the output of the elev_tile_pyramid command line tool. See that for details. Suffice it to say that each tile is separate, contains one extra cell on the northern and eastern sides and is made up for shorts (16 bit).

The elevation chunk is a base class for representing elevation data in Maply.

Elevation can be grids or triangles, or whatever. They follow an internal (hidden) protocol for interpolation and conversion into visual data.

The Maply Elevation Chunk holds elevations for a single tile.

This object holds elevation data for a single tile. Each tile overlaps the the eastern and northern neighbors by one cell. Why? Because we’re generating triangles with these and they’re independent. Draw a picture, it’ll make sense.

Data values are currently onl 32 bit floating point. There may be a type parameter in the future.

Initialize the elevation data with a Cesium terrain tile.

Processes Cesium’s terrain tile format into a form we can use.

A simple test elevation source.

This just generates a bumpy elevation field to cover the whole earth in Spherical Mercator. Don’t be using this for anything real.

Undocumented

Geometry State is used to describe the visual look of objects as they’re added.

Set the various fields in the geometry state to control how geometry looks when you add it. There are defaults for all of these fields.

The geometry builder is used to construct 3D models.

You use the geometry builder when you have a custom 3D model to build. This can include things like airport runways, buildings, or anything else that’s particular to a certain location.

Start by construting the builder and then adding polygons and strings to it.

You can combine multiple geometry builders together to build up repeated portions of a model.

The builder has an immediate mode where you add points individually to build up polygons and then add those. This is one of the simpler ways to use the system.

Contains a big pile of geometry and textures (e.g. a model).

The geometry model

Place a geometry model at a given location

Geometry models tend to be expensive so we load and place them in a two step process. First you create the MaplyGeomModel and then you place it in one or more spots with this MaplyGeomModelInstance.

A version of the geometry model instance that moves.

This version of the geometry model instance can move in a limited way over time.

An interface/loader for Icons in general.

Describes a single tile worth of data, which may be multiple images.

Delegates can pass back a single UIImage or NSData object, but if they want to do anything more complex, they need to do it with this.

This is a 3D label.

The Maply Label is a 3D object that sits on top of the globe (or map) at a specified location. If you want a 2D label that sits on top of everything else, you want the MaplyScreenLabel. Seriously, you probably want that.

The Light provides a simple interface to basic lighting within the toolkit.

You can have up to 8 lights in the current version of the toolkit. Obviously this is all shader implementation with OpenGL ES 2.0, so you can always just bypass this and do what you like. However, the default shaders will look for these lights.

The lights are very simple, suitable for the globe, and contain a position, a couple of colors, and a view dependent flag.

Undocumented

MapBox Tiles format tile source object.

This is the MBTiles format tile source. It’ll read local MBTiles archives (https://github.com/mapbox/mbtiles-spec?source=c) which are basically just collections of image tiles in a sqlite database.

The sqlite file must be local, that is contained within the bundle or copied into it at some point. To access remote tile sources look at the MaplyRemoteTileSource.

MBtiles archives tell us how big they are, including min and max zoom levels. You can also limit the max zoom by setting it directly.

The Marker places a UIImage on the globe or map at a given location.

The Maply Marker takes a location and image, using those to display a textured rectangle on the globe (or map). Since it’s a real 3D object it will get larger and smaller as the user moves around.

If you want a screen based object that stays the same size and is displayed on top of everything else, look to the MaplyScreenMarker.

Represents a matrix for position manipulation.

Encapsulates a 4x4 matrix used for object placement and other things. This is more a wrapper than a full service object.

Utility for calculating moon position.

This is a utility class that figures out where the moon is at a given data and provides the position.

The multiplex tile source is for bunging other tile sources together.

The Multiplex Tile source takes a bunch of other tiles source objects and switches between them. Strictly speaking, it doesn’t multiplex. The quad image layer asks for all of its images at once for a given tile. I just like the word ‘multiplex’. Multiplex. Multiplex. So futuristic in a 1970’s way. Multiplex.

Anyway, this is useful for animating between different tile sources.

A data source used for testing paging layer.

This data source puts up a colored and numbered rectangle for each tile loaded. It’s useful for debugging paging schemes.

A data source used for testing paging layer.

This data source puts up a colored and numbered rectangle for each tile loaded. It’s useful for debugging paging schemes.

A particle system is used to spawn large numbers of small moving objects.

The particle system defines what the objects are and how they’re controlled. Actual data is handled through the MaplyParticleBatch.

You set up a particle system and then add MaplyParticleBatches via a view controller.

A particle batch adds a set number of particles to the system.

The particle batch holds the number of particles defined in the MaplyParticleSystem batchSize property. Each attribute array is added individually via an NSData object. All attributes must be present or the batch is invalid and won’t be passed through the system.

The Maply Points object is used to add a large number of static points to the scene.

Rather than add a single 3D point we assume you want to add a lot of them all at once. This object lets you do that and lets you assign the various data values to input attributes in your custom shader.

All the cool kids have custom shaders.

The offline renderer passes over images like so

The quad image offline layer renders a single image at irregular intervals from a standard input tile source.

The offline renderer will fetch a tile image basemap like a normal MaplyQuadImageTilesLayer. What it does with it is completely different. It renders a stack of static images from it and calls a delegate with them.

The images produced correspond to the bbox set. Think of it as providing a window into a tiled base map. Why? Eh, it’s complicated.

The Maply Quad Image Tiles Layer is for paging image pyramids local or remote.

This layer pages image pyramids. They can be local or remote, in any coordinate system Maply supports and you provide a MaplyTileSource conformant object to do the actual image tile fetching.

This is the main interface for image pyramid paging and so has a lot of knobs you can twiddle. The defaults should work fine in most cases.

You probably don’t have to implement your own tile source. Go look at the MaplyRemoteTileSource and MaplyMBTileSource objects, as well as MaplyMultiplexTileSource. Those will do remote, local, and sources for animation respectively. There’s also MaplyWMSTileSource, but I wouldn’t expect to use that.

The Quad Paging Layer is for loading things like vector tile sets.

The Maply Quad Paging Layer implements a general purpose paging interface for quad tree based data sources. This is different from the MaplyQuadImageTilesLayer in that it’s meant for paging things like vector tiles, or really any other features that are not images.

You set up an object that implements the MaplyPagingDelegate protocol, create the MaplyQuadPagingLayer and respond to the startFetchForTile:forLayer: method.

Once you’ve fetched your data for a given tile, you’ll need to call tileDidLoad: or tileFailedToLoad:. Then you’ll want to create the visual objects in the MaplyViewController or WhirlyGlobeViewController and pass them in to addData:forTile:

This is how the paging layer keeps track of which objects you’ve created for a given tile and can then remove them when the time comes.

Objects must be created with @enable set to @(NO) in the description dictionary. Tiles are paged before they are needed for dipslay and so the paging layer must have control over when data is displayed. It uses the enable/disable options for the various Maply objects in the view controllers.

The quad tracker keeps track of quad tree nodes.

This object tracks quad tree nodes as they’re added to and removed from an internal quad tree that tracks them by screen importance. This version is intended for use in Objective-C and is much simpler than the internal version.

All the methods are thread safe.

Undocumented

Undocumented

Undocumented

Undocumented

The Cesium terrain server uses an odd tiling system with two top level nodes.

The remote tile info encapsulates settings for a remote tile source. It describes where the tile source is and presents URLs for getting the data, and information about local caching.

The remote tile source knows how to fetch remote image pyramids.

This is the MaplyTileSource compliant object that communicates with remote servers and fetches individual tiles as needed by the MaplyQuadImageTileLayer.

It can be initialized in a couple of different ways depending on the information you have available. Either you explicitly provide the baseURL, min and max levels and such, or hand in an NSDictionary that’s been parsed from a tile spec.

The remote tile source also handles cacheing if it you give it a cacheDir to work in. By default cacheing is off (so be careful).

Represents a render target (other than the screen)

Individual objects can ask to be drawn somewhere other than the screen. This is how we do that.

A render target is just a link between a render every frame and a MaplyTexture. To get at the actual image you use the MaplyTexture.

At the moment a render target can only draw the full screen, possibly at a lower resolution.

The Screen Label is a 2D label that tracks a given geographic location.

This screen label will track the given geographic position. If it’s behind the globe it will disappear. The label is rendered in a fixed size and will always appear on top of other geometry.

A version of the maply screen label that moves.

This version of the screen label can move in a limited way over time.

The Screen Marker is a 2D object that displays an image on the screen tracking a given location.

The screen marker will track the given geographic location and display a centered rectangle with the given image. Essentially it’s a free floating icon, similar to the MaplyScreenLabel and it will always be drawn on top of other objects. If the location would be behind the globe (in globe mode), the marker will disappear.

If you’re looking for a 3D marker object, that’s the MaplyMarker.

A version of the maply screen marker that moves.

This version of the screen marker can move in a limited way over time.

The Maply Screen Object is used to build up a more complex screen object from multiple pieces.

You can use one or more of these to build up a combination of labels and images that form a single marker, label, or billboard.

The shader is a direct interface to OpenGL ES 2.0 shader language.

You can set your own shader programs in the toolkit!  Yeah, that's as complex as it sounds.

The underyling toolkit makes a distinction between the name of the shader and the scene name.  The scene name is used as a way to replace the default shaders we use for triangles and lines.  This would let you replace the shaders you're already using with your own.  See the addShaderProgram:sceneName: method in the MaplyBaseViewController.

You can also add your own shader and hook it up to any features that can call out a specific shader, such as the MaplyQuadImageTilesLayer.

When writing a new shader, go take a look at DefaultShaderPrograms.mm, particularly the vertexShaderTri and fragmentShaderTri.  The documentation here is for the uniforms and attributes the system is going to hook up for you.  All of these are optional, but obviously nothing much will happen if you don't use the vertices.

Uniform Values

These are uniform values provided to each shader, if requested.

|uniform|type|description| |:——|:—|:———-| |u_mvpMatrix|mat4| The model/view/projection matrix. Shaders typically run vertices through this. | |u_mvMatrix|mat4| The model/view matrix. Less comonly used. | |u_mvNormalMatrix|mat4| The model/view matrix for normals. A shader typically uses this when we want view dependent lighting. | |u_fade|float| Available in regular drawables, but not yet in big drawables (e.g. atlases). This is intended to fade geometry in and out over time. | |u_interp|float| If we’re doing multiple textures, this is how to interpolate them. | |u_numLights|int| The number of active lights to use. | |light[8]|directional_light| A data structure for each active light. See the table below. | |material|material_properties| Material information used to calculate lighting. See the table below. | |u_hasTexture|bool| True if there’s a texture available to fetch data from. | |s_baseMapX|sampler2D| s_baseMap0, s_baseMap1 and so forth are references to texture data. |

Material properties

These are the fields for the material properties.

Light properties

These are the fields for each individual light.

|field|type|description| |:—-|:—|:———-| |direction|vec3| The light’s direction, used in diffuse lighting. | |halfplane|vec3| This would be used in specular lighting. | |ambient|vec4| The ambient value of the light. | |diffuse|vec4| The diffuse value of the light. | |specular|vec4| Not currently used. | |viewdepend|float| If greater than 0.0, the shader should run each normal through the u_mvNormalMatrix. |

Attributes

These are the per vertex attributes provided to each vertex shader.

|field|type|description| |:—-|:—|:———-| |a_position|vec3| The position in display space for a vertex. Shaders typically multiply this by u_mvpMatrix. | |a_texCoord0|vec2| If textures are present, this is the texture coordinate for the first one. | |a_texCoord1|vec2| If two textures are present, this is the texture coordinate for the second. | |a_color|vec4| An RGBA color for the vertex. | |a_normal|vec3| A normal in display space. This is used purely for lighting and often run through u_mvNormalMatrix. | |a_elev|float| An optional elevation value provided by the MaplyQuadImageTiles layer. You can use it to do elevation dependent shading. |

Maply Shape is the base class for the actual shape objects.

The maply shape is just the base class. Look to MaplyShapeCircle, MaplyShapeCylinder, MaplyShapeSphere, MaplyShapeGreatCircle, and MaplyShapeLinear.

Shows a circle at the given location on the globe or map.

This object represents a circle at the given geographic location. It needs a radius (in display coordinates) and can optionally have a height above the globe or map.

Display a sphere at the given location with the given radius.

This object represents a sphere at the

Represent a cyclinder on the globe or map.

This object represents a cylinder with it’s base tied to the surface of the globe or map and it’s top pointed outward (on the globe anyway). The base can be offset and the overall radius and height are adjustable.

Represents an great circle or great circle with height.

Great circles are the shortest distance between two points on a globe. We extend that a bit here, by adding height. The result is a curved object that can either sit on top of the globe or rise above it. In either case it begins and ends at the specified points on the globe.

Represents a simple rectangle in 3D.

The rectangle is a 2D object in 3D. Specify the lower left and upper right coordinates as well as an optional texture.

A linear feature offset from the globe.

The main difference between this object and a regular MaplyVectorObject is that you specify coordiantes in 3D. You can use this to create linear features that are offset from the globe.

An extruded shape with an arbitrary outline.

This object represents an extruded shape with the given thickness. It can be oriented according to the pitch, roll, yaw and height.

Spherical quad earth layer is an older style of base map

The Spherical quad earth layer fires up an older style of image map generated by the ImageChopper program. It can be either an image pyramid or a flat grid of images. In general, we recommend using the MaplyQuadImageTilesLayer instead.

The Stars Model parses and then displays a star field.

This is used to display a star field around the earth.

Stickers are rectangles placed on the globe with an image.

The Maply Sticker will stretch a rectangle (in geographic) over the given extents and tack the given image on top of it. Stickers differ from MaplyMarker objects in that they’re big. They can stretch over a larger are and need to be subdivided as such.

Utility for calculating sun position and shading info.

This is a utility class that figures out where the sun is at a given date and provides positional information for lighting calculations.

Represents an OpenGL texture.

The MaplyTexture is an opaque object used to track OpenGL ES textures. You create one from the MaplyBaseViewController’s addImage call. Then that texture will live until this object is released.

These can be used in place of UIImages in the various objects (e.g. MaplyScreenMarker).

Status information for each frame’s loading status.

When loading animated frames, this contains the status of a single frame.

An encapsulation of where the viewer is and what they’re looking at.

This wraps information about where the viewer is currently looking from and at.

This layer will call a delegate as the user moves around, but constrained to distance and time.

This layer is responsible for calling a delegate you provide as the user moves their viewpoint around. You’ll be called if they move from than a certain amount, but not more often than the minimum time.

Maply Vector Object represents zero or more vector features.

The Vector Object can hold several vector features of the same or different types. It’s meant to be a fairly opaque structure, often read from GeoJSON or Shapefiles. It’s less opaque than originally planned, however, and sports a number of specific methods.

If you’re doing real vector manipulation, it’s best to do it somewhere else and then create one of these as needed for display.

Vector Objects can be created directly or read from a MaplyVectorDatabase. They are typically then displayed on top of a MaplyViewController or WhirlyGlobeViewController as vectors.

Vector Objects vertices are always in geographic, with longitude = x and latitude = y.

The Maply Vector Database holds reference to a group of features that you can query.

This object wraps more complex database-like objects that contain geometric features. Primarily, that’s just shapefiles.

You can set this up and then query the database for features you’d like back. There’s an option to make a SQL query or you can just fetch all the vectors at once.

The point of this object is to keep most features out of memory until needed. However, a better way of doing that is probably using the MaplyPagingLayer.

Vertex Attributes are passed all the way though on objects to shaders.

If you have your own custom shader, you often need a way to feed it data. The toolkit will set up the standard data, like vertices, texture coordinates and normals, but sometimes you need something custom.

Vertex attributes are the mechanism you use to pass that custom data all the way down to the shader.

How the vertex attributes are used depends on the data type, so consult the appropriate object.

Animation State used by the MaplyViewControllerAnimationDelegate.

You fill out one of these when you’re implementing the animation delegate. Return it and the view controller will set the respective values to match.

A simple animation delegate for moving the map around.

The animation delegate support provides a lot of flexibility. This version just provides all the standard fields and interpolates from beginning to end.

This view controller implements a map.

This is the main entry point for displaying a 2D or 3D map. Create one of these, fill it with data and let your users mess around with it.

You can display a variety of features on the map, including tile base maps (MaplyQuadImageTilesLayer), vectors (MaplyVectorObject), shapes (MaplyShape), and others. Check out the add calls in the MaplyBaseViewController for details.

The Maply View Controller can be initialized in 3D map, 2D map mode. The 2D mode can be tethered to a UIScrollView if you want to handle gestures that way. That mode is very specific at the moment.

To get selection and tap callbacks, fill out the MaplyViewControllerDelegate and assign the delegate.

Most of the functionality is shared with MaplyBaseViewController. Be sure to look in there first.

The View Controller Layer is a base class for other display layers.

You don’t create these directory. This is a base class for things like the MaplyQuadPagingLayer and the MaplyQuadImageTilesLayer.

The View Tracker associates a view with a geographic location.

The Maply View Tracker will move a UIView around to keep track of a geographic location. This is basically used for popups. The system will move the view around at the end of the frame render. It will hide the UIView if needed or make it reappear. The UIView should be a child of view controller’s view.

A bounding box for a specific CRS in that coordinate system. This is part of the Web Map Server parser.

Style of a WMS layer as returned by GetCapabilities. This is part of the Web Map Service parser.

Description of a WMS layer as returned by a GetCapabilities call. This is part of the Web Map Service parser.

Encapsulates the capabilities coming back from a WMS server. We can query this to see what layers and coordinate systems are available. Part of the Web Map Service parser.

This is a MaplyTileSource that works with a remote Web Map Service implementation. WMS is not the most efficient way to access remote image data, but there are still a few places that use it.

Animation State used by the WhirlyGlobeViewControllerAnimationDelegate.

You fill out one of these when you’re implementing the animation delegate. Return it and the view controller will set the respective values to match.

A simple animation delegate for moving the globe around.

The animation delegate support provides a lot of flexibility. This version just provides all the standard fields and interpolates from beginning to end.

This view controller implements a 3D interactive globe.

This is the main entry point for displaying a globe. Create one of these, fill it with data and let your users mess around with it.

You can display a variety of features on the globe, including tiled base maps (MaplyQuadImageTilesLayer), vectors (MaplyVectorObject), shapes (MaplyShape), and others. Check out the add calls in the MaplyBaseViewController for details.

To get selection and tap callbacks, fill out the WhirlyGlobeViewControllerDelegate and assign the delegate.

Most of the functionality is shared with MaplyBaseViewController. Be sure to look in there first.