Constraining the Map

Constraining the map to a smaller area

Constraining the Map

If your application only makes sense at the scale of localised regions, such as a city or even smaller sections of a city, we provide support for pre-fetching and caching the environment for your area of interest. This means that the environment data does not need to be downloaded on-demand as the user visits the area. This page discusses how to specify your area of interest, and presents an example application which demonstrates specifying a pre-cache volume to download all data for an area, and how to constrain the camera to this area.

In this section:

Identifying a World Cell

The streaming of the environment resources works by partitioning the world into grid cells, which form a Quadtree spatial structure. Each cell has a unique identifier, referred to as a Morton Key and represented by the Eegeo::Streaming::MortonKey type.

The Morton Key value encodes the path from the root of the tree to a particular cell, and implies a world space location and boundary for the cell. Morton Keys exist in a hierarchy, so the key which encodes the value “0123” is a child of the key “012” and a parent of the keys “01230”, “01231”, “01232”, and “01233”. What is conceptually a single environment resource may exist at multiple levels of detail, which aligns to the Quadtree structure inherent in the MortonKey hierarchy.

Pre-caching the Streaming Volume

In order to pre-fetch and cache an area, the Eegeo::Web::PrecacheService can be used. This service is capable of maintaining a queue of web requests for environment resources, which will download in the background; the Precache service attempts to avoid disrupting the regular streaming behaviour, so a client can begin a precache while still exploring the environment.

The Precache service presents an API to inform the user if it currently has an active precache, and if so, the progress of that precache.

In order to begin pre-fetch and cache region, the PrecacheService must be provided with an implementation of Eegeo::Streaming::IStreamingVolume. To determine which environment resources to load, the PrecacheService will query the IStreamingVolume with a sequence of MortonKey values, to determine if the cell described by the MortonKey lies within the boundary of the IStreamingVolume; if so, the children of that cell will be queried. This process will continue until the PrecacheService has determined the full set of keys which are covered by the IStreamingVolume at all levels of detail.

Specifying a Streaming Volume

In order to specify a streaming volume, you must provide an implementation of Eegeo::Streaming::IStreamingVolume. This interface contains a single method, which asks if a Morton key is intersected by the volume (and optionally allows the the implementation to provide some additional information to the querier). To implement this method, a Volume should perform an intersection test between its geometric representation and a selected geometric representation for the cell described by the ‘key’ argument, returning true if the volumes intersect.

The following example shows a world space spherical volume (defined by m_ecefCentre and m_sphereVolumeRadius), which constructs a spherical volume for the cell described by the ‘key’ argument, then performs a sphere intersection test;

Applying Camera Constraint

In addition to the ability to pre-fetch and locally cache resources, a localised application should constrain the camera to its region of interest. This can be accomplished by detecting that the camera has left the region of interest, then by moving the camera back inside this region. For the default GlobeCameraController, the SetView, SetInterestBasis and SetAltitude methods can be used. For a custom camera controller, an appropriate interface should be defined to allow these constraints to be implemented.

The following example demonstrates how to constain the default GlobeCameraController to an arbitrary volume, defined by a radius and a height;


SingleCityExample – This example illustrates how to constrain the camera to a small region in San Francisco city. A spherical implementation of IStreamingVolume is defined by the example, which is provided to the PrecacheService as described above. The camera is also constrained to this region, by detecting if the camera has left the region and if so moving back inside.

The example logs diagnostics as it tests keys for intersection, and logs the full set of intersected keys. The example also logs the progress of the PrecacheService as it loads resources in the background. When the PrecacheService has completed its task, a data in the IStreamingVolume will be resident on the device. This can be verified by turning off device connectivity and loading the example; all environment data at all levels of detail within the IStreamingVolume should be present.

The example is available here.