Appendix D: mapViews Field
This appendix provides a detailed description of the "mapViews" field, a field used to define the mapParameters field which is one of the fields used to define each of the Formbird components below:
1 Purpose
The "mapViews" field is an array of map view definitions. each defining the properties of a map view.
- A map view is a 2D image of an area of the earth's surface. For example:
- Satellite view displays a satellite photo of an area.
- Map view displays the streets of an area.
- Each map view definition is a set of name/value pair fields, some required, some optional.
2 Definition
The tables below list and describe the name/value pair fields used to define the properties of a map view.
Note:
- Default values for the fields described in the tables below are shown in bold text.
2.1 Required Customizable Fields
Field | Valid Values | Description |
---|---|---|
params | Array of map view parameters | Array of parameters defining how a map view is to be displayed. Section 2.3 params Field lists and describes the "params" field parameters . |
uiLabel | Any character | Defines the button label for a map view or a grouping of map views. Clicking a button will display the map in accordance with its associated map view definition or group map view definition. Example: "uiLabel": "V" |
url | url address to communicate with a particular geoserver for geospatial data. | |
Vicmap url | Vicmap geoserver for geospatial data. Example: "url": "https://base.maps.vic.gov.au/service" |
|
OSM url | Open Street Maps geoserver for geospatial data. Example: "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png" |
|
Formbird OSM url | Formbird geoserver for Open Street Map (OSM) geospatial data. Example: "url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png" |
|
Formbird agis url | Formbird geoserver for agis geospatial data. Example: "url": "https://agis-geoserver.formbird.com/geoserver/agis-dev/wms" |
2.2 Optional Customizable Fields
Field | Valid Values | Description |
---|---|---|
apiKey | Valid API key | Your API key, if required by the map server. Map servers are used to share geospatial data. Examples of map servers are Google and Geoserver. Example: "apiKey": "your API key" |
crossOrigin | Used for loaded images. Note: A crossOrigin value is required if using the WebGL renderer or if accessing pixel data from an image server. It's a way for the webpage to ask the image server for permission to use the image. |
|
User credentials | Asks for permission, sending user credentials to the server. Example: "CrossOrigin" : "jsmith.j53p19f5" |
|
anonymous | Asks for permission but don't send extra information. Example: "crossOrigin": anonymous |
|
null | Default value. Do not ask for permission. Example: "crossOrigin": null |
|
EPSG | Valid EPSG SRID | EPSG is a spatial coordinate system used to locate geographical entities on a map, a map being a 2D projection of the 3D earth's surface or a region of the earth's 3D surface. There are many 2D projections, each using different properties to represent distances, angles or areas. Certain projections are better suited for different regions in the world. An EPSG SRID (Spatial Reference System Identifier) value identifies a specific 2D projection coordinate system together with the region of the earth it covers. E.g. EPSG:3111 is the projection coordinate system used for rendering map of the state of Victoria (between 140.9500, -39.1500 and 149.9800, -34.0000). Example: "EPSG": "EPSG:3111" |
EPSG:3857 | Defaults to the Web Mercator projection (EPSG:3857) which is used to render a map of the world (between 85.06°S and 85.06°N) in Google Maps, OpenStreetMaps, OpenLayers, etc. | |
groupView | Array of map view definitions | A groupView field groups multiple map views together for display purposes. When map views are grouped, the uiLabel field is defined at the group level. |
isShow | true | Identifies the initial map view to show on load. Example: "isShow": true |
Defaults to the the first map view defined in the map views array. | ||
serverType | Defines the map source. | |
geoserver | An open source server for sharing geospatial data. Used for web based maps such as OpenLayers and Bing Maps. Example: "serverType": "geoserver" |
|
tile | A server providing a map as a set of square tiles (images) arranged in a grid. When a map moves to a new location, or to a new zoom level, the Map API determines which tiles are needed and translates that information into a set of tiles to retrieve from the server. Example: "serverType": "tile" |
|
Defaults to the google server for the source of geospatial data. |
2.3 params Field
The "params" field in Section 2.1 Required Customizable Fields is an array of parameters defining how a map view is to be displayed.
The table below lists and describes the "params" field parameters.
Parameter | Description |
---|---|
BBOX | Specifies the portion of the Earth to be mapped by specifying the the coordinates of the bounding box corners (lower left, upper right) in the units defined by the SRS field value. Example: "BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826", |
FIRSTTILE | Valid Values: true, false Example: "FIRSTTILE": true |
FORMAT | Specifies the output format of the response to the request. Valid Values: Dependent on the formats supported by the Map Server and the request operation being invoked. Example: "FORMAT": "image/png" Example: "FORMAT": "image/jpeg" |
HEIGHT | Height in integer pixels of the map image to be produced i.e. the number of pixels to be used between the minimum and maximum y values (inclusive) in the BBOX. In the case where the aspect ratio of the BBOX and the ratio WIDTH/HEIGHT values are different, the WMS will stretch the returned map so that the resulting pixels are rendered in the aspect ratio of the BBOX. Example: "HEIGHT": "512", |
LAYERS | Specifies the map view layer to be returned by the request. Examples: 1. Vicmap Basemap, Web Mercator, 256px, Cartographic. "LAYERS": "CARTO_WM_256" 2. Vicmap Basemap, Web Mercator, Aerial. "LAYERS": "AERIAL_WM" 3. Vicmap Basemap, Web Mercator, 256px, Overlay. "LAYERS": "CARTO_OVERLAY_WM_256" |
REQUEST | Specifies which service operation is being invoked. The value shall be the name of one of the operations offered by the map service. Valid Values: Dependent on the Map Service. Examples: "request": "GetMap" - returns a map image."request": "GetCapabilities" - returns parameters about the WMS (e.g. map image format and WMS version compatibility) and the available layers (e.g. map bounding box, coordinate reference systems). |
SERVICE | The Map Service protocol. Examples: "service": "WMS" WMS (Web Map Service) is a standard protocol developed by the Open Geospatial Consortium for serving geospatial map images over the Internet. These images are typically produced by a map server from data provided by a GIS database. |
SRS | Specifies which Spatial Reference System applies to values in the BBOX parameter. Examples: "SRS": "EPSG:3857" |
STYLES | Specifies the rendering style of the map layer. To request the default style, use the null value i.e. "" Example: "STYLES": "1.1.1" |
VERSION | Specifies the Map Service protocol version number. The version number contains three non-negative integers, separated by decimal points, in the form “x.y.z”. Example: "VERSION": "" |
WIDTH | Width in integer pixels of the map image to be produced i.e. the number of pixels to be used between the minimum and maximum y values (inclusive) in the BBOX parameter. In the case where the aspect ratio of the BBOX and the ratio WIDTH/HEIGHT values are different, the WMS will stretch the returned map so that the resulting pixels are rendered in the aspect ratio of the BBOX. Example: "WIDTH": "512", |
3 Example
A "mapViews" array containing 3 individual map views and 1 group map view.
"mapViews": [
{
"EPSG": "EPSG:3857",
"isShow": true,
"params": {
"BBOX": "16133701.716224,-4393099.8016821,16446787.78408,-4080013.733826",
"FIRSTTILE": true,
"FORMAT": "image/png",
"HEIGHT": "512",
"LAYERS": "CARTO_WM",
"REQUEST": "GetMap",
"SERVICE": "WMS",
"SRS": "EPSG:3857",
"STYLES": "",
"VERSION": "1.1.1",
"WIDTH": "512"
},
"serverType": "geoserver",
"uiLabel": "V",
"url": "https://base.maps.vic.gov.au/service"
},
{
"EPSG": "EPSG:3857",
"params": {
"BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
"FIRSTTILE": true,
"FORMAT": "image/png",
"HEIGHT": "512",
"LAYERS": "AERIAL_WM",
"REQUEST": "GetMap",
"SERVICE": "WMS",
"SRS": "EPSG:3857",
"STYLES": "",
"VERSION": "1.1.1",
"WIDTH": "512"
},
"serverType": "geoserver",
"url": "https://base.maps.vic.gov.au/service",
"uiLabel": "S"
},
{
"crossOrigin": null,
"serverType": "tile",
"uiLabel": "O",
"url": "https://osm.formbird.com/tiles/{z}/{x}/{y}.png"
},
{
"groupView": [
{
"EPSG": "EPSG:3857",
"params": {
"BBOX": "16280475.531304,-4696291.0150527,16593561.59916,-4383204.9471967",
"FIRSTTILE": true,
"FORMAT": "image/png",
"HEIGHT": "512",
"LAYERS": "AERIAL_WM",
"REQUEST": "GetMap",
"SERVICE": "WMS",
"SRS": "EPSG:3857",
"STYLES": "",
"VERSION": "1.1.1",
"WIDTH": "512"
},
"serverType": "geoserver",
"url": "https://base.maps.vic.gov.au/service"
},
{
"EPSG": "EPSG:3857",
"params": {
"BBOX": "16446787.78408,-4393099.8016821,16759873.851936,-4080013.733826",
"FIRSTTILE": true,
"FORMAT": "image/png",
"HEIGHT": "512",
"LAYERS": "CARTO_OVERLAY_WM",
"REQUEST": "GetMap",
"SERVICE": "WMS",
"SRS": "EPSG:3857",
"STYLES": "",
"VERSION": "1.1.1",
"WIDTH": "512"
},
"serverType": "geoserver",
"url": "https://base.maps.vic.gov.au/service"
}
],
"uiLabel": "M"
}
]