Rover Model
=================
This section describes the object model for the Rover system.
Terms
-----
**geometry type**
The general classes of cartographic shapes stored by Rover.
These geometric types of shape are available:
* image - an image drawn directly over a geographic area,
* area - a polygon, generally drawn filled,
* line - a polyline, comprised of segments connecting vertices,
* point - a point object, generally drawn with an icon,
* text - a text shape, containing a string in addition to placement data.
Image shapes are defined by:
* center point,
* width and height in image pixels,
* scale, and
* rotation.
Area shapes are defined by:
* vertex count, and
* vertices.
Line shapes are defined by:
* vertex count, and
* vertices.
Point shapes are defined by:
* center point,
* offset, and
* rotation.
Text shapes are defined by:
* center point,
* offset,
* alignment,
* rotation, and
* text.
**rover data item**
The data portion of a rover element.
A rover data item has:
* a locally unique ID in the rover set,
* a globally unique UUID,
* a data type, and
* data values.
**rover element**
An individual geographic data element, composed of typed data, shapes, and parts. Each of these is optional; there may be no data set, or no shapes, or no parts.
Parts are just pointers to other rover elements that are considered to be associated with and comprise the one containing the pointers.
This is called **map data item** in v4.4, but in v5.0 **rover element** is preferred since data is just part of its function.
**rover set**
A collection of Rover data, largely independent from other Rover sets.
Rover sets contain this descriptive metadata:
* data types,
* shape types,
* find item indexes, and
* tile grids;
this data:
* elements,
* data items,
* shapes,
* find item entries, and
* tiles,
and this rendering configuration:
* styles, and
* legends.
**rover shape**
A geographic shape.
Rover shapes have this data:
* geometry type
* element id - optional, points at the element it's part of,
* shape type - used by the legend to determine how to draw the shape,
* properties - which vary by geometry type, and
* geometry - which also vary by geometry type.
**rover level-of-detail (LOD)**
A grid of tiles, configured to be appropriate for a certain scale range.
An LOD has:
* a unique sequential numeric ID
* an origin in map units
* a tile size in map units
* a set of tiles
**rover tile**
A tile in an LOD grid.
Rover tiles cover a specific area in map units, and contain some number of rover shapes. They have their own internal coordinate
representation since those coordinates only have to represent points within the area.
Tiles have a cell coordinate value (cellX and cellY), which provides the identifier for the tile and also, along with the LOD configuration,
provides the numbers needed to convert from tile coordinates to map
**coordinate**
A set of numbers describing a location within a coordinate system.
The definition and valid values of the numbers depend upon the coordinate system itself.
Refer to the definitions here for these:
* map coordinate
* cell coordinate
* tile coordinate
* screen coordinate
**coordinate system**
A coordinate system specifies the framework for locating something in space.
We deal with a lot of different coordinate systems
during rendering, so this can be confusing. See the definition to coordinate and thence the various types of coordinate.
**cell coordinate**
An XY coordinate that identifies a cell in a grid, rather than individual locations within the cell.
**tile coordinate**
An XY or XYZ coordinate inside a tile, using the internal tile coordinate system.
In the version 4.4 format, 2-byte unsigned integers are used for x and y inside a tile.
**map coordinate**
An XY or XYZ coordinate in the map's coordinate system.
**screen coordinate**
An XY coordinate in screen pixels, generally as referenced from the origin of the view panel, but sometimes from the origin of the display.
**display scale**
Ratio of geographic size in map units (e.g. feet) to screen size in pixels. Also called display scale.
Display scale should generally note the units (feet/pixel) if used outside of the system. Note that this differs from the cartographic scale.
**cartographic scale**
Ratio of the printed size to the geographic size.
E.g. 1/100 or 1:100 scale refers to a scale where an object 100 feet long is 1 foot long on a printed map. This a pure ratio since the same units are used for both parts of the ratio (e.g. feet/feet).
This is problematic with computer displays, since computer displays are measured in pixels and the "real world" size of a rendered image can vary enormously depending on the monitor or projector used.
Consider the projector in particular; you could modify the cartographic (apparent) scale of the display by simply moving the projector closer or further from the screen or wall, without the
software having any idea that the apparent scale has changed. Thus, there is no "right" conversion between screen scale and cartographic scale.
Partner uses the convention that a pixel is 1/144 inches square. This roughly corresponds to apparent size on most screens and works well when printed. The standard printing unit "pica" is 1/72 inch, and
this is half that size, which has other advantages when dealing with printing frameworks.
Thus, in Partner, cartographic scale can be calculated as
cartographic_scale = 1 / (display_scale * units_to_inches * 144)
So, a display scale 10 feet per pixel corresponds to a cartographic scale of 1:17280,
and a cartographic scale of 1:1 corresponds to a display scale of approximately 0.0005787 feet/pixel.
**granularity**
Minimum size representable, in map units.
Usage depends on context. On screen, a pixel is the minimum display unit,
so the granularity on a display is the current display scale (size of a pixel in map units).
In a rover tile, the granularity is determined by the distance between two consecutive tile coordinates.
In version 4.4, tile coordinates are 2-byte unsigned integers, so the tile granularity is limited by
the format to 1/65535 the width of the tile. During publishing, this is either configured manually or
automatically calculated to the minimum zoom scale configured. Whichever it is, that's the minimum
representable distance between drawn points or line vertices, and if it's substantially larger than the display
scale, graphics may appear strange or disconnected.
Non-tiled rovers, such as those used for highlighting a selection, also have a granularity. In 4.4, these are
stored using 4-byte single-precision IEEE floats, which are not particularly accurate. Their granularity depends on the
map coordinate system itself, since single-precision gives 6-9 decimal points of accuracy. So, if your map coordinates are
in the millions, you would have a granularity somewhere between 0.001 and 1.0.