Rover Performance
=================

The Rover system is designed specifically for high-performance map viewing, searching, and interaction. It has a number of mechanisms designed to provide this performance; 
however any system may require tuning to maximize its potential. This section describes some metrics to consider when tuning a Rover set, how to measure them, and how to modify
your configuration to change them.

Display Optimizations
---------------------

Our input for a frame consists of:
* map view frame parameters - center point, rotation, width, height, and scale,
* legend

A scale region is then selected from the legend based on the scale. This scale region contains the mapping from shape type to style that we use to decide what to render and how.

The process of rendering a frame from rover data goes through a number of pipelined stages. Each stage has optimization tools that seek to reduce the work required to render, mostly 
by ignoring or discarding individual shapes that aren't needed for the given frame.

The sequence is as follows:

* LOD selection,
* tile selection,
* style culling,
* geometric culling.

There are other optimizations along the way but these are the primary ones we can tune. 

LOD selection is done based on the scale region's LOD setting. The LOD determines the geometry of the grid the tiles are stored in, and, by extension, how precise and efficient they are for display at that scale.

Tile selection is straightforward; all tiles that overlap the frame's rectangle are chosen and processed. A tile is essentially just a stream of shapes, so now we move to optimization by shape.
Tuning the LOD parameters and thus the tile selection process is the most fundamental and important optimization. We compare the size of the tile (in map units) to the size of the frame (in map units).
If the tile is much larger, then many shapes that aren't going to go in the frame are loaded and read. If the tile is much smaller, then many tiles have to be read to fill the frame. 

Style culling is when we discard shapes that don't have a style associated with them in the legend scale region. If they aren't going to be drawn, we want to ignore them as early in the process as possible.

Geometric culling is discarding shapes based on whether their vertices lie in the frame or not. Cropping can then be applied to reduce things further but that's out of scope for this discussion.


Terms
-----

**rover element** or **map data item**
	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 data item**
	The data portion of a rover element.
	
	that refers to just the data and the 
	data/shape combination is an **entity**

**frame**
    A single, full render of the map view.
    
    This term is derived from film and video terminology, and is also a common term in computer graphics. Animated displays (which includes all computer graphics, even if they seem largely static 
    in some cases) provide an illusion of movement and change to your eyes by presenting a sequence of changing views. Each of these views can be thought of as a single static image; 
    swapping out images over time then creates the animation. A "flip book" animation is a simple example of this concept. Each of these images is a frame.
    
    There is an unfortunate overlap between this term and our own term, MapViewFrame, which describes the geometry of the frame (like a picture frame) around the map view. They have little in common,
    other than that an image frame is rendered based on a specific MapViewFrame geometry.
 
Metrics
-------

**frame rate**
	The number of frames that can be rendered in a second, also called frames per second or FPS.
	
	This is a measure of rendering speed that corresponds most directly to performance as perceived by a user. In general, the higher the rate, the smoother the appearance of animation. 
	This leads directly to better perceived performance and better usability, since slow frame rates result in jerky panning and zooming, which is distracting and can cause mistakes.
	
	There are three classic standards, which are worth considering as targets:
	* 24 FPS - this was the standard for film for years
	* 30 FPS - this was the standard for TV for years
	* 60 FPS - generally standard for modern lcd/led displays

	Higher framerates than 60 are generally "wasted" since the hardware can't render them that fast anyway, but may still be useful since FPS will not be constant
	across an entire map - more complicated areas or more elaborate styles may cause some areas to be slower than others, so shooting for higher average FPS may prevent "bogging down" in some areas.
	Higher framerates also indicate that the computer is not working so hard to render a frame. Less work for a laptop or tablet means less battery usage and less heat.
	
**map vertex density**  
    This is the number of shape vertices per map unit squared.
    
    Using a shape count is less useful, since line and area shapes may contain many vertices. Counting vertices is a reasonable generalization.
    
    Example: an area 100' by 100' containing 14 vertices has a map vertex density of 14/ (100*100), or 0.0014 vertices/sq. ft.

**display vertex density**
	This is the number of shape vertices per pixel at a given display scale.
	
	Example: at a display scale of 10 feet/pixel, 300 vertices are drawn in a 100x100 pixel area. This is a display vertex density of 0.03 vertices/pixel.
	
**tile vertex density**
	This is the number of shape vertices in a tile.

	Example: a tile containing 145 vertices has a tile density of 145 vertices/tile.

**average vertex density**
	This is an average of any of the different vertex densities over the entire Rover set or an LOD.
	
**LOD precision**
	This is the ratio of the lowest to highest display scale that an LOD is displayed at using a given legend.
	
	Each legend defines multiple scale regions; these regions point at individual LODs. Multiple regions may point at the same LOD. So, an LOD may be used for a wide range of scales.
	Since LODs are a scale-based optimization, this can result in poor performance, and overuse of an LOD can result in inaccurate placement of vertices onscreen.
	
	Higher is generally better. 1.0 is the maximum, but an LOD with precision of 1 is only used for a single scale and that's a poor use of disk space.
	
	Example: an LOD used from 10 feet/pixel to 40 feet/pixel has an LOD precision of 0.25.
	
**tile coverage**
	This is the ratio of the area of a tile in map units to the area of the frame in map units. 
	
	Example: A frame is drawn covering 800x600 pixels at 12 feet/pixel. Therefore the frame covers an area 9600x7200 feet, or 69120000 square feet.
	The LOD selected has tiles with dimensions 1000'x1000', or 1000000 square feet. The tile coverage is approximately 0.014468.