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"`
	google	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"
            }
        ]