====== Rendering MapObjects ======

This page tries to bring an overview of what MapObjects are all about.\\ 
A ''MapObject'' is an object that defines everything needed to render it :
  * Spatial information (point,line,area)
  * Legend information (line color, etc…)

===== MapObject Types =====

The SDK defines 4 types of MapObjects.  
  * Field-of-views : visualisation of view states.
  * Measurements : Visualisation of measurements.
  * Globals : Visualisation of global state (focus, mouse hover).
  * Footprints : Visualisation of where resource shave data available.

Each of these types should be rendered in their own layer, with the Field-of-view layer on top.

===== How are MapObjects kept up-to-date? =====

Each MapObject type has its own **Signal** to get notified, and **Function** to retrieve the updated MapObjects.  With those, you can update the MapObject type's layer.

The following Signals and Functions pair up : 

^ Signal ^ Function ^
| onFootprintsChanged | getFootprints2D()\\ getFootprints3D() | 
| onGlobalsChanged | getGlobals() | 
| onFieldOfViewsChanged | getFieldOfViews2D()\\ getFieldOfViews3D() | 
| onMeasureStateChanged | getMeasureState() ((The MeasureState class has a mapObjects property holding a list of MapObjects)) |

===== Rendering a MapObject =====

Rendering a MapObject is essential to implementing a good plugin.  

Keep in mind that MapObjects with different spatial types need to be in one layer.  On some platforms this can be a problem.  The solution in such a situations can be to render MapObjects using an overlay layer, or use a customized symbol renderer.

To determine the spatial type of the ''MapObject'', look at the presence of these properties :
  * ''spatialPoint'' not null ? It's a point.
  * ''spatialLine'' not null ? It's a line.
  * ''spatialArea'' not null ? It's an area.

Only one of these three properties will ever be defined.

==== Rendering Lines ====

The ''spatialLine'' property is a CoordinatePath instance containing one or more CoordinateLine instances.  Each CoordinateLine instance holds a list of Coordinate instances defining the outline of a single line.

Render the line, using the following legend properties : 
  * color : the outline color.
  * lineWidth : the outline width in 96dpi pixels.

==== Rendering Areas ====

The ''spatialArea'' property is a CoordinatePath instance containing one or more CoordinateLine instances.  Each CoordinateLine instance holds a list of Coordinate instances defining the outline of a single area.

Fill and then Stroke the area, using the following legend properties : 
  * color : the outline color.
  * lineWidth : the outline width in 96dpi pixels.
  * fillColor : the fill color.

==== Rendering Points ====

The ''spatialPoint'' property is a symbol at a specific coordinate.

=== Custom symbols ===

If the ''symbolPath'' property is set, we are rendering a custom symbol.

The ''symbolPath'' property is a CoordinatePath instance that defines a symbol expressed in 96dpi pixel units.

The symbol should be placed with its origin placed on top of the point's ''spatialPoint'' coordinate.

Fill and then Stroke the ''symbolPath'', using the following legend properties : 
  * color : the outline color.
  * lineWidth : the outline width in 96dpi pixels.
  * fillColor : the fill color.

=== Named symbols ===

If the ''symbolPath'' property is not set, we are rendering a named symbol.

The default symbol is ''circle_filled''.

If ''symbolName'' is specified, use this symbol instead.

Fill and then Stroke the ''symbolPath'', using the following legend properties : 
  * color : the outline color.
  * lineWidth : the outline width in 96dpi pixels.
  * fillColor : the fill color.
  * symbolSize : the symbol size in 96dpi pixels

Possible ''symbolName'' values : 
  * ''circle_filled'' : a filled circle.

===== Coordinate System =====

By default, all spatial data returned by the SDK is expressed in WGS/84.  To change the CRS of data returned by the SDK, please provide the ''Constants.STARTUP_CRS'' option at Viewer startup.

The default CRS is EPSG:4326 (2D WGS/84).