[[PageOutline]]

= Introduction = 

A map object describes the parts required to display a map in Rappture. A
map may have several sources of information that when put together are
displayed as a map.

{{{
  <map>
    <about>
      <label>My Map</label>
      <description>Description of Map</description>
    </about>

    <type>projected</type>
    <projection>global-mercator</projection>
    <style>-color white -lighting 1</style>
    <camera>
      <x>-118.281</x>
      <y>34.4402</y>
      <z>562.291</z>
      <heading>-30.1011</heading>
      <pitch>-20.2908</pitch>
      <distance>538181</distance>
    </camera>

    <viewpoints>
      <viewpoint>...</viewpoint>
      ...
    </viewpoints>

    <layers>
      <layer>...</layer>
      ...
    </layers>
  </map>
}}}

Maps must have one or more '''<layer>''' subelements.  

 '''<about><label>'''::
   This is the label of the map.  It's used to label the output of the map in Rappture's drop down list of outputs.
 '''<about><description>'''::
   This is a longer description of the map.  It is used for the tool tip on Rappture's drop down list of outputs.
 '''<about><attribution>'''::
   This string should include any data copyright attributions required that aren't included in specific layer attributions.
 '''<type>'''::
   'geocentric' or 'projected'.  Geocentric is a 3D Earth model using ECEF coordinates, otherwise (the default) use a 2D projection defined by the projection element.
 '''<projection>'''::
     Defines the projection of the map if type is 'projected' (for geocetric maps this should be omitted).  All layers should ideally be in this projection, but any layers that are not will be re-projected.  If not specified, the map projection will be the Spherical Mercator (aka Web Mercator) projection.  The projection can be an EPSG code in the form "epsg:n" where n is a number, or it can be a PROJ4 command-line string.
 '''<extents>'''::
   This specifies the output extent of the map (i.e.the bounding box of the map). Any data in layers beyond these extents will not be visible.  The '''<extents>''' values are given in this format: <Lower Left X> <Lower Left Y> <Upper Right X> <Upper Right Y>, with spaces separating each value. This needs to be in the same projection and units as the map, i.e. the projection specified in the projection element.
 '''<camera>'''::
   The following camera parameter elements may be used to set the initial camera view of the map.
 '''<camera><layer>'''::
   Used without other camera parameters, the value for this parameter is the ID of the layer whose extent should be used to set the camera.
 '''<camera><xmin>''','''<camera><ymin>''','''<camera><xmax>''','''<camera><ymax>'''::
   Used without other camera parameters, these parameters specify the extent to be used to set the camera, in map SRS.
 '''<camera><x>'''::
   Easting map coordinate of focal point in map SRS.
 '''<camera><y>'''::
   Northing map coordinate of focal point in map SRS.
 '''<camera><longitude>'''::
   Alternative to <x> coordinate, in WGS84.
 '''<camera><latitude>'''::
   Alternative to <y> coordinate, in WGS84.
 '''<camera><z>'''::
   If specified, sets altitude of focal point in map vertical datum.
 '''<camera><distance>'''::
   Distance of camera to focal point in meters.
 '''<camera><heading>'''::
   If specified, sets compass heading angle in degrees (range: -180 to 180, use 0 for North up).
 '''<camera><pitch>'''::
   If specified, sets pitch angle in degrees of camera (range: -90 to -10, use -90 for top down view).
 '''<camera><srs>'''::
   If specified, indicates other parameters (horizontal coordinate system) are given in this spatial reference system (SRS).
 '''<camera><verticalDatum>'''::
   If specified, indicates other parameters (vertical coordinate system) are given relative to this vertical datum.
 '''<style>'''::
   Global map style parameters related to terrain background color, lighting, etc.

 ||**Parameter**||**Description**||
 ||-ambient||For sky lighting, the amount of ambient light on the night side.  (Range: 0.0 to 1.0)||
 ||-color||Background color of map.  May be a color name or hexidecimal RGB color (e.g. #FFFFFF for white).||
 ||-lighting||Set to 0 or 1 to disable or enable sky lighting by default.||
 ||-time||Ephemeris time in a format supported by Tcl's clock command, e.g. "HH:MM:SS".  Used to position the sun and stars for sky lighting.||

 '''<layers>'''::
   There can be one or more layers described. The first layer is by default the base layer.  Layers are drawn in the order they are found in the '''<map>'''.
 '''<viewpoints>'''::
   There can be one or more viewpoints given.  These viewpoints may be presented to users to allow navigating to views of points of interest.  See [#Viewpoints Viewpoints]

= Viewpoints =

A '''<viewpoint>''' is a pre-defined location and/or a 2D or 3D camera view of a location.  When selecting a viewpoint in the map viewer, any optional parameters not specified in the viewpoint are taken from the current camera settings in the viewer.

{{{
  <viewpoint id="view1">
    <label>Sample Viewpoint 1</label>
    <description>Description of the view.</description>
    <x>-118.281</x>
    <y>34.4402</y>
    <z>562.291</z>
    <heading>-30.1011</heading>
    <pitch>-20.2908</pitch>
    <distance>538181</distance>
  </viewpoint>
}}}

 '''<label>'''::
   Label to display on button/link
 '''<description>'''::
   Longer description of viewpoint
 '''<x>''','''<y>'''::
   Easting and Northing map coordinates
 '''<longitude>''','''<latitude>'''::
   Optional alternative to <x>,<y> in WGS84
 '''<z>''' OR '''<altitude>'''::
   Optional altitude coordinate, relative to map vertical datum
 '''<distance>'''::
   Camera distance to focal point in meters
 '''<heading>'''::
   Optional camera azimuth/heading angle in degrees (-180,180)
 '''<pitch>'''::
   Optional camera pitch angle in degrees (-90,-10)
 '''<srs>'''::
   If specified, indicates other parameters (horizontal coordinate system) are given in this spatial reference system (SRS).
 '''<verticalDatum>'''::
   If specified, indicates other parameters (vertical coordinate system) are given relative to this vertical datum.

= Layers =

A '''<layer>''' subelement describes a layer of the map.  Layers are drawn
one on top of the next.

{{{
  <layer>
    <label>My Layer</label>
    <description>...</description>
    <attribution>...</attribution>
    <type>image</type>
    <shared>false</shared>
    <visible>true</visible>
    <cache>false</cache>
    <opacity>1.0</opacity>
    <coverage>false</coverage>
    ...
  </layer>
}}}

 '''<label>'''::
   This is the name of the layer.  It is displayed in controls to hide/show individual layers.
 '''<description>'''::
   This is a description of the layer.
 '''<attribution>'''::
   The copyright attribution string to display for this layer.
 '''<type>'''::
   This is the type of layer.  Valid layer types are ''image'', ''elevation'', ''mask'', ''model'', ''feature'', ''point'', ''line'', ''polygon'', and ''label''.  
 '''<profile>'''::
   This optional element may be used to specify the projection and extents of the layer as a named profile such as ''global-geodetic'' or ''global-mercator''.  Use this if the layer data source does not include projection information.
 '''<shared>'''::
   This is a boolean property that indicates if the layer is a shared base/overlay layer (true) or a data layer (false).  Data layers would typically be the output layers which are the results of the tool's simulations.
 '''<visible>'''::
   The initial visibility of the layer.  The user may choose to display it using the map controls.
 '''<cache>'''::
   Boolean which determines if layer may be cached to disk.  The cache can be disabled if terms of use prohibit caching or if data is dynamic, e.g. a weather map layer that updates periodically.
 '''<opacity>'''::
   This sets the opacity of the layer.  The range is from 0.0 to 1.0 and the default is 1.0 (fully opaque).  This element is not valid if the layer type is 'elevation'.
 '''<coverage>'''::
   Applies only to image layers.  Turning this boolean setting on will treat the layer data as discrete coverage data and prevent interpolation of values.  This is useful for data such as land use categories.
 '''<minrange>'''::
   Applies only to feature layers.  Minimum distance in meters at which layer should be shown.
 '''<maxrange>'''::
   Applies only to feature layers.  Maximum distance in meters at which layer should be shown.
 '''<terrainPatch>'''::
   Applies only to model, feature, or polygon layers.  Set this boolean option on to use the layer in elevation queries.  This option should be used in combination with a mask layer to cut a hole in the terrain for the terrain patch.

= Layer Data Providers =

Layer providers are sources of layer data and may include local files loaded via GDAL or a network service such as WMS or TMS.

== Layer Source URLs ==

In the following documentation of layer providers, when a resource <url> is given, it may take a few different forms.  A <file> or <url> tag can be an absolute filesystem path to a file that is on an NFS-mounted filesystem shared between the HUB and the rendering servers.  Otherwise, the <url> tag can be a URL with a protocol specifier.  For tile services, this is typically the !http:// protocol specifier.  As an alternative to a bare file path, the !file:// protocol specifier can be used for absolute file paths.  Two additional special protocol specifiers have been defined:

=== Local File URLs ===

A local:// protocol specifier indicates that the file is on the local HUB filesystem (not a shared mount).  Rappture will then send the file data to the render server to be rendered.  These local URLs may be relative or absolute.  A relative URL will be relative to the Rappture tool's working directory.

=== IData URLs ===

An idata:// protocol specifier indicates that the file is in an iData collection.  The collection ID should follow the double slash where a server name typically goes in a URL.  The remainder of the URL should be the DOI path of the file within the collection.

== Raster Layers ==

=== Color Ramp Provider ===

This is a special type of image layer provider that currently uses GDAL to load a single band raster file (e.g. a GeoTIFF or netCDF file) and apply a color map to produce an RGB image layer.  The underlying implementation can also load raster data using other drivers such as TMS, but currently the GDAL driver is always selected.

{{{
  <layer>
    <label>Color Ramp Image Layer</label>
    <description>...</description>
    <type>image</type>
    <colorramp>
       <file>...</file>
         OR
       <url>...</url>
       <colormap>
        -33 0.5 0 1 1
        -24.75 0 0 1 1
        -16.5 0 0.5 1 1
         -8.75 0 1 1 1
          0 1 1 1 1
         16.5 1 1 0 1
         33 1 0 0 1
       </colormap> 
   </colorramp>
  </layer>
}}}


 '''<file>'''::
   This is the name of a single band file.  The file path must exist on the render servers. 
 '''<url>'''::
   This is the url of a file on a web server.
 '''<colormap>'''::
   This is a list of control points defining a color map.  Each color map entry consists of 5 floating-point numbers: a data value, and R, G, B, A values in the [0.0,1.0] range.  The data values are un-normalized: they should be defined over the range of values present in the raster file.

=== GDAL Provider ===

The GDAL provider can load a variety of file types such as GeoTIFF, jpeg, PNG, netCDF, etc.  This provider can be used for image or elevation layers.

{{{
  <layer>
    <label>GDAL Image Layer</label>
    <description>...</description>
    <type>image</type>
    <gdal>
       <file>...</file>
         OR
       <url>...</url>
    </gdal>
  </layer>
}}}


 '''<file>'''::
   This is the name of a file.  The file path must exist on the render servers. 
 '''<url>'''::
   This is the url of a file on a web server.

=== TMS Provider ===

The TMS provider can be used as a source for image or elevation layers.

{{{
  <layer>
    <label>TMS Image Layer</label>
    <description>...</description>
    <type>image</type>
    <tms>
       <url>http://example.com/foo/bar/tms</url>
    </tms>
  </layer>
}}}

 '''<url>'''::
   This is the url of the TMS server.

=== WMS Provider ===

{{{
  <layer>
    <label>WMS Image Layer</label>
    <description>...</description>
    <type>image</type>
    <wms>
       <url>http://example.com/foo/bar/wms</url>
       <layers>foo:bar</layers>
       <format>jpeg</fornat>
       <transparent>false</transparent>
    </wms>
  </layer>
}}}

 '''<url>'''::
   This is the url of the WMS server.
 '''<layers>'''::
   The name of the layer(s) to request from the server.
 '''<format>'''::
   The image format to request.
 '''<transparent>'''::
   If set to true, and the format is set to 'png', the layer will have a transparency mask, allowing the layer underneath to show through where this image layer is transparent.

=== XYZ Provider ===

This provider can be used with servers that provide compatible zoom/center coordinate based static URLs.  Examples include OpenStreetMap and MapQuest's OSM-based static maps.

{{{
  <layer>
    <label>XYZ Image Layer</label>
    <description>...</description>
    <type>image</type>
    <xyz>
       <url>http://example[1234].com/{z}/{x}/{y}.jpg</url>
    </xyz>
  </layer>
}}}

 '''<url>'''::
   This is the url pattern for the image server.  Numbers in square brackets can be used for round-robbin content delivery network server load balancing.  The x,y, and z coordinates will be substituted in for {x} {y} and {z} in the url pattern.  The z coordinate is a zoom level and the x,y coordinates indicate the center position of the image.

== Feature (Vector) Layers ==

=== OGR Provider ===

This provider can be used for feature layers using sources supported by the OGR library such as ESRI shapefile, postgis databases, etc.

{{{
  <layer>
    <label>OGR Feature Layer</label>
    <description>...</description>
    <type>line</type>
    <ogr>
       <file>/foo/bar/baz.shp</file>
         OR
       <url>http://example.com/foo/bar/baz.shp</url>
         OR
       <connection>PG:host=example.com dbname=foo user=bar password=baz</connection>
       <layer>tablename</layer>
    </ogr>
  </layer>
}}}

 '''<file>'''::
   This is the name of a shape file.  The file path must exist on the render servers. 
 '''<url>'''::
   This is the url of a shape file on a web server.
 '''<connection>'''::
   This is a connection string for a postgis (postgresql) database.
 '''<layer>'''::
   This is used in conjunction with the <connection> when connecting to a database.  It should be set to the name of a feature table.

=== TFS Provider ===

This provider can be used for feature layers.

{{{
  <layer>
    <label>TFS Feature Layer</label>
    <description>...</description>
    <type>line</type>
    <tfs>
       <url>http://example.com/foo/bar/tfs</url>
       <format>json</format>
    </tfs>
  </layer>
}}}

 '''<url>'''::
   This is the url of the TFS server.
 '''<format>'''::
   The format the TFS server should return: 'json' or 'gml'

=== WFS Provider ===

This provider can be used for feature layers.

{{{
  <layer>
    <label>WFS Feature Layer</label>
    <description>...</description>
    <type>line</type>
    <wfs>
       <url>http://example.com/foo/bar/wfs</url>
       <typename>namespace:featuretype</typename>
       <format>json</format>
    </wfs>
  </layer>
}}}

 '''<url>'''::
   This is the url of the WFS server.
 '''<typename>'''::
   This is the name of the feature
 '''<format>'''::
   The format the WFS server should return: 'json' or 'gml'

== Feature Layer Styles ==

For layers of type 'icon', 'text', 'point', 'line' or 'polygon', styles are specified with a set of setting name/value pairs in a <style> tag:

{{{
  <layer>
    <type>line</type>
    <style>-width 5 -color black</style>
  </layer>
}}}

For layers of type 'feature', styles follow the OSGEarth format.  A <styles> tag contains a <stylesheet> of CSS-formatted style definitions.  Optionally, a set of <selector> tags may be defined with a <query> to select a <style> name.  See the OSGEarth [http://docs.osgearth.org/en/latest/references/symbology.html symbology reference] for details of the CSS style properties for symbols.

{{{
  <layer>
    <type>feature</type>
    <styles>
      <stylesheet>
        s1 {
          stroke: #000000;
          fill: #ff0000;
        }
        s2 {
          stroke: #000000;
          fill: #0000ff;
        }
      </stylesheet>
      <selector id="1">
        <style>s1</style>
        <query>area &lt; 4</query>
      </selector>
      <selector id="2">
        <style>s2</style>
        <query>area &gt;= 4</query>
      </selector>
    </styles>
  </layer>
}}}

=== Selectors ===

 '''<style>'''::
   The name of the style in the stylesheet that should be used to style the result of the selector query.
 '''<styleExpression>'''::
   An alternative to <style>, this is !JavaScript code that returns a style name.
 '''<query>'''::
   This is a SQL WHERE clause used to select the features.  It may be left blank to select all features.
 '''<queryBounds>'''::
   A list (space separated) of xmin xmax ymin ymax bounds in the SRS of the feature source.  The results will be restricted to those inside (or intersecting) the bounds.  Features will not be clipped to the bounds.

== Feature Layer Attribute Display Placard ==

When selecting features from a feature layer, the map viewer can display an information placard with attribute data for the selected feature.  This placard can be customized by including a <placard> element in the <layer> element:

{{{
  <layer>
    <type>feature</type>
    ....
    <placard>
       <attributes>name Name aland "Land Area"</attributes>
       <style>fill: #00FF0088; text-fill: #000000; text-size: 18.0;</style>
       <padding>5</padding>
    </placard>
  </layer>
}}}

 '''<attributes>'''::
   This is a list of alternating attribute IDs and attribute labels (labels with spaces need to be quoted).
 '''<style>'''::
   This is a CSS-formatted style definition for the text symbol and backing polygon symbol.  See the OSGEarth [http://docs.osgearth.org/en/latest/references/symbology.html#text symbology reference] for details of the CSS style properties for symbols.
 '''<padding>'''::
   This is a pixel padding between the attribute labels and the edge of the backing quad.

== Model Layers ==

=== OSG Provider ===

The OSG provider can load any of the 3D model formats supported by the !OpenSceneGraph installation.

{{{
  <layer>
    <type>model</type>
    <osg>
      <x>-79.1</x>
      <y>36.09</y>
      <z>0.0</z>
      <rotx>0.0</rotx>
      <roty>0.0</roty>
      <rotz>0.0</rotz>
      <url>cow.osg</url>
    </osg>
  </layer>
}}}

== Mask Layers ==

A mask layer is used to cut a hole in the terrain to make space for a model or feature mesh.  It consists of a single polygon feature which represents the boundary of the hole.

=== OGR Provider ===

The OGR provider can be used to specify the polygon with inline WKT (Well Known Text), WKT in a file, or as the first feature in a feature source such as a shape file, postgis database query, etc.  By default the coordinate system is assumed to be WGS84.

{{{
  <layer>
    <type>mask</type>
    <ogr>
      <geometry>POLYGON((-79.1 36.09 0.0, -79.05 36.09 0.0, -79.05 36.096 0.0, -79.1 36.096 0.0, -79.1 36.09 0.0))</geometry>
       OR
      <geometryUrl>polygon_as_wkt.txt</geometryUrl>
       OR
      <url>boundary.shp</url>
    <ogr>
  </layer>
}}}