Namespace: MapConfig

MapConfig

Configuration options for a MapModel that control the appearance of the map, the data/imagery displayed, and which UI components are rendered. A MapConfig object can be used when initializing a Map model, e.g. `new Map(myMapConfig)`
Properties:
Name Type Attributes Default Description
homePosition MapConfig#CameraPosition <optional>
 A set of coordinates that give the (3D) starting point of the Viewer. This position is also where the "home" button in the Cesium widget will navigate to when clicked.
layers Array.<MapConfig#MapAssetConfig> <optional>
 A collection of imagery, tiles, vector data, etc. to display on the map. Layers wil be displayed in the order they appear. The array of the layer MapAssetConfigs are passed to a MapAssets collection. When layerCategories exist, this property will be ignored.
layerCategories Array.<MapConfig#MapAssetConfig> <optional>
 A collection of layer categories to display in the tool bar. Categories wil be displayed in the order they appear. The array of the AssetCategoryConfig are passed to a AssetCategories collection. When layerCategories exist, the layers property will be ignored.
terrains Array.<MapConfig#MapAssetConfig> <optional>
 Configuration for one or more digital elevation models (DEM) for the surface of the earth. Note: Though multiple terrains are supported, currently only the first terrain is used in the CesiumWidgetView and there is not yet a UI for switching terrains in the map. The array of the terrain MapAssetConfigs are passed to a MapAssets collection.
showToolbar boolean <optional>
 true Whether or not to show the side bar with layer list, etc. If true, the MapView will render a ToolbarView.
showLayerList boolean <optional>
 true Whether or not to show the layer list in the toolbar. If true, the ToolbarView will render a LayerListView.
showHomeButton boolean <optional>
 true Whether or not to show the home button in the toolbar.
showViewfinder boolean <optional>
 false Whether or not to show the viewfinder UI and viewfinder button in the toolbar. The ViewfinderView requires a Google Maps API key present in the AppModel. In order to work properly the Geocoding API and Places API must be enabled.
showShareUrl boolean <optional>
 false Whether or not to show the share as URL UI in the toolbar and update the URL as the user interacts with the map. This feature requires a `layerId` field on any layers that are expected to be saved to the URL search parameter, as that is the only unique identifier which can be used to turn the layer visibility on or off.
toolbarOpen boolean <optional>
 false Whether or not the toolbar is open when the map is initialized. Set to false by default, so that the toolbar is hidden by default.
showScaleBar boolean <optional>
 true Whether or not to show a scale bar. If true, the MapView will render a ScaleBarView.
showFeatureInfo boolean <optional>
 true Whether or not to allow users to click on map features to show more information about them. If true, the MapView will render a FeatureInfoView and will initialize "picking" in the CesiumWidgetView.
showDownloadPanel boolean <optional>
 false Set to true to enable the partial download panel, see DownloadPanelView. `showLayerList` must also be set to true.
clickFeatureAction string <optional>
 "showDetails" The default action to take when a user clicks on a feature on the map. The available options are "showDetails" (show the feature details in the sidebar) or "zoom" (zoom to the feature's location).
showNavHelp boolean <optional>
 true Whether or not to show navigation instructions in the toolbar.
showFeedback boolean <optional>
 false Whether or not to show a feedback section in the toolbar with the text specified in feedbackText.
feedbackText string <optional>
 null The text to show in the feedback section. showFeedback must be true for this to be shown.
globeBaseColor String <optional>
 null The base color of the globe when no layer is shown.
zoomPresets ZoomPresets <optional>
 null A Backbone.Collection of a predefined list of locations with an enabled list of layer IDs to be shown the zoom presets UI. Requires `showViewfinder` to be true as this UI appears within the ViewfinderView. UI appears within the ViewfinderView.
Source:

Example

{
  "homePosition": {
    "latitude": 74.23,
    "longitude": -105.7
  },
  "layers": [
    {
      "label": "My 3D Tile layer",
      "type": "Cesium3DTileset",
      "description": "This is an example 3D tileset. This description will be visible in the LayerDetailsView. It will be the default color, since to colorPalette is specified.",
      "cesiumOptions": {
        "ionAssetId": "555"
      },
    }
  ],
  "terrains": [
    {
      "label": "Arctic DEM",
      "type": "CesiumTerrainProvider",
      "cesiumOptions": {
        "ionAssetId": "3956",
        "requestVertexNormals": true
      }
    }
  ],
  "showToolbar": true,
  "showScaleBar": false,
  "showFeatureInfo": false
}

Type Definitions

AssetCategoryConfig

The source of a specific category to show in the ToolBarView, as well as display properties of the asset.
Type:
  • object
Properties:
Name Type Description
label string A user friendly name for this category, to be displayed in a map.
icon string A PID for an SVG saved as a dataObject, or an SVG string. The SVG will be used as an icon that will be displayed next to the category label. It should be an SVG file that has no fills, borders, or styles set on it (since the icon will be shaded dynamically by the maps CSS using a fill attribute). It must use a viewbox property rather than a height and width.
layers MapAssets The data to render in the map.
Source:

CameraPosition

Coordinates that describe a camera position for Cesium. Requires at least a longitude and latitude.
Type:
  • object
Properties:
Name Type Attributes Description
longitude number Longitude of the central home point
latitude number Latitude of the central home point
height number <optional>
 Height above sea level (meters)
heading number <optional>
 The rotation about the negative z axis (degrees)
pitch number <optional>
 The rotation about the negative y axis (degrees)
roll number <optional>
 The rotation about the positive x axis (degrees)
Source:
Examples
{
 longitude: -119.8489,
 latitude: 34.4140
}
{
 longitude: -65,
 latitude: 56,
 height: 10000000,
 heading: 1,
 pitch: -90,
 roll: 0
}

ColorConfig

A color to use in a map color palette, along with the value that the color represents.
Type:
  • object
Properties:
Name Type Attributes Description
value string | number The value of the attribute in a MapAsset that corresponds to this color. If set to null, then this color will be the default color.
label string <optional>
 A user-facing name for this attribute value, to show in map legends, etc. If not set, then the value will be displayed instead.
color string | Color Either an object with 'red', 'green', 'blue' properties defining the intensity of each of the three colours with a value between 0 and 1, OR a string with a hex color code beginning with #, e.g. '#44A96A'. The AssetColor model will convert the string to an AssetColor#Color object.
Source:
Examples
{
  value: 0,
  label: 'water',
  color: {
    red: 0,
    green: 0.1,
    blue: 1
  }
}
{
  value: 'landmark',
  color: '#7B44A9'
}

ColorPaletteConfig

The ColorPaletteConfig specifies a color scale that is mapped to some attribute of a MapAsset. For vector assets, like 3D tilesets, this palette is used to conditionally color features on a map. For any type of asset, including imagery, it can be used to generate a legend. The ColorPaletteConfig is passed to a AssetColorPalette model.
Type:
  • Object
Properties:
Name Type Attributes Default Description
paletteType 'categorical' | 'continuous' | 'classified' <optional>
 'categorical' NOTE: Currently only categorical and continuous palettes are supported. - Categorical: the color conditions will be interpreted such that one color represents a single value (e.g. a discrete palette). - Continuous: each color in the colors attribute will represent a point in a gradient. The point in the gradient will be associated with the number set with the color, and numbers in between points will be set to an interpolated color. - Classified: the numbers set in the colors attribute will be interpreted as maximums. Continuous properties will be forced into discrete bins.
property string The name (ID) of the property in the asset layer's attribute table to color the vector data by (or for imagery data that does not have an attribute table, just the name of the attribute that these colors represent).
label string <optional>
 A user-friendly name to display instead of the actual property name.
colors Array.<MapConfig#ColorConfig> The colors to use in the color palette, along with the conditions associated with each color (i.e. the properties of the feature that must be true to use the given color). The array of ColorConfig objects are passed to a AssetColors collection, which in turn passes each ColorConfig to a AssetColor model.
Source:
Example
{
   paletteType: 'categorical',
   property: 'landUse',
   label: 'Land Use in 2016',
   colors: [
     { value: "agriculture", color: "#FF5733" },
     { value: "park", color: "#33FF80" }
   ]
}

CustomDateProperty

An object that defines a formatted date to use as a property in a feature. Used in the MapConfig#CustomProperties object.
Type:
  • object
Properties:
Name Type Description
type 'date' Must be set to 'date' to indicate that this is a custom date property
property string The name/ID of the existing date property to format
format string A string that indicates the new format to use. Follows the syntax used by Day.JS, see https://day.js.org/docs/en/display/format
Since:
  • 2.19.0
Source:

CustomProperties

An object where the keys indicate the name/ID of the new custom property to create, and the values are an object that defines the new property.
Type:
  • Object
Since:
  • 2.19.0
Source:
Example
{
  "year": {
    "type": "date",
    "property": "dateTime",
    "format": "YYYY",
  },
  "urlText": {
    "type": "string",
    "value": "Click here to learn more about this feature"
  }
}

CustomStringProperty

An object that defines a custom string to use as a property in a feature. Used in the MapConfig#CustomProperties object.
Type:
  • object
Properties:
Name Type Description
type 'string' Must be set to 'string' to indicate that this is a custom string property
value string The new string to use. So far only static strings are available. In the future, templates that include other properties may be supported.
Since:
  • 2.19.0
Source:

FeatureTemplate

A feature template configures the format and content of information displayed in the Feature Info panel (FeatureInfoView). The Feature Info panel is displayed in a map when a user clicks on a vector feature in a map.
Type:
  • object
Properties:
Name Type Attributes Default Description
template 'story' | 'table' <optional>
 'table' The name/ID of the template to use. This must match the name of one of the templates available in FeatureInfoView#contentTemplates.
label string <optional>
 Sets which of the feature properties to use as the title for the FeatureInfoView. The string must exactly match the key for a property that exists in the feature.
options MapConfig#StoryTemplateOptions <optional>
 A list of key-value pairs that map the template variable to a property/attribute of the the feature. Keys are the template variable names and values are the names of properties in the feature. Template variable names are specific to each template. Currently only the 'story' template allows variables. These are specified in the FeatureInfoView#contentTemplates.
Since:
  • 2.19.0
Source:
Examples
// Use the "story" template, which shows a secondary title, image, description,
// and link.
{
  "template": "story",
  "label": "title",
  "options": {
    "subtitle": "formattedDate",
    "description": "summary",
    "thumbnail": "imageSrc",
    "url": "newsLink",
    "urlText": "newsTitle",
  }
}
// Use the default template (a table), but use the "forestName" attribute for
// the FeatureInfo panel label
{
  "label": "forestName"
}

MapAssetConfig

The source of a specific asset (i.e. layer or terrain data) to show on the map, as well as metadata and display properties of the asset. Some properties listed here do not apply to all asset types, but this is specified in the property description.
Type:
  • object
Properties:
Name Type Attributes Default Description
type 'Cesium3DTileset' | 'BingMapsImageryProvider' | 'IonImageryProvider' | 'WebMapTileServiceImageryProvider' | 'WebMapServiceImageryProvider' | 'TileMapServiceImageryProvider' | 'NaturalEarthII' | 'CesiumTerrainProvider' | 'GeoJsonDataSource' | 'USGSImageryTopo' | 'OpenStreetMapImageryProvider' A string indicating the format of the data. Some of these types correspond directly to Cesium classes. The NaturalEarthII type is a special imagery layer that automatically sets the cesiumOptions to load the Natural Earth II imagery that is shipped with Cesium/MetacatUI. If this type is set, then no other cesiumOptions are required. The same is true for USGSImageryTopo, which pulls imagery directly from USGS.
cesiumOptions Cesium3DTileset#cesiumOptions | CesiumImagery#cesiumOptions | CesiumTerrain#cesiumOptions | CesiumVectorData#cesiumOptions <optional>
 For MapAssets that are configured for Cesium, like Cesium3DTilesets, an object with options to pass to the Cesium constructor function that creates the Cesium model. Options are specific to each type of asset. For details, see documentation for each of the types.
label string A user friendly name for this asset, to be displayed in a map.
icon string <optional>
 A PID for an SVG saved as a dataObject, or an SVG string. The SVG will be used as an icon that will be displayed next to the label in the layers list. It should be an SVG file that has no fills, borders, or styles set on it (since the icon will be shaded dynamically by the maps CSS using a fill attribute). It must use a viewbox property rather than a height and width.
opacity number <optional>
 1 A number between 0 and 1 indicating the opacity of the layer on the map, with 0 representing fully transparent and 1 representing fully opaque. This applies to raster (imagery) and vector assets, not to terrain assets.
saturation number <optional>
 1 A number that indicates the saturation of the layer on the map. Less than 1.0 reduces the saturation while greater than 1.0 increases it. This applies to raster (imagery) only.
visible boolean <optional>
 true Set to true if the layer is visible on the map, false if it is hidden. This applies to raster (imagery) and vector assets, not to terrain assets.
description string <optional>
 A brief description about the asset, e.g. which area it covers, the resolution, etc.
attribution string <optional>
 A credit or attribution to display along with this asset.
moreInfoLink string <optional>
 A complete URL used to create a link to show in a map where a user can find more information about this resource.
downloadLink string <optional>
 A complete URL used to show a link in a map where a user can go to download the source data.
id string <optional>
 If this asset's data is archived in a DataONE repository, the ID of the data package.
colorPalette MapConfig#ColorPaletteConfig <optional>
 The color or colors mapped to attributes of this asset. This applies to raster/imagery and vector assets. For imagery, the colorPalette will be used to create a legend. For vector assets (e.g. 3Dtilesets), it will also be used to style the features.
featureTemplate MapConfig#FeatureTemplate <optional>
 Configuration for the content and layout of the Feature Info panel (FeatureInfoView) - the panel that shows information about a selected feature from a vector asset. If no feature template is set, then the default table layout is used.
customProperties MapConfig#CustomProperties <optional>
 Definitions of custom properties of features, potentially based on existing properties. For example, a custom property could be a formatted version of another date property. These custom properties can be used in the filters, colorPalette, or featureTemplate. So far, custom strings and formatted dates are supported. Eventually, the custom properties may be expanded to support formatted numbers and booleans.
filters MapConfig#VectorFilterConfig <optional>
 A set of conditions used to show or hide specific features of this tileset.
notification MapConfig#Notification <optional>
 A custom badge and message to display about the layer in the Layer list. For example, this could highlight the layer if it is new, give a warning if they layer is under development, etc.
hideInLayerList boolean <optional>
 Set to true to hide this asset from the layer list.
Source:

Notification

A notification displays a badge in the LayerListView and a message in the LayerDetailsView. This is useful for indicating some special status of the layer: "new", "under development", etc.
Type:
  • object
Properties:
Name Type Attributes Description
style 'yellow' | 'green' | 'blue' | 'contrast' <optional>
 The badge and message color. If none is set, then notification elements will be similar to the background colour (subtle).
badge string The text to display in the badge element next to the layer label in the list. This badge should be as few characters as possible.
message string A longer message to display explaining the status.
Since:
  • 2.22.0
Source:

StoryTemplateOptions

An object that maps template variable to feature properties for the "story" template.
Type:
  • object
Properties:
Name Type Description
subtitle string The name of a feature property to use for a secondary title in the template
description string The name of a feature property that contains a brief summary or description of the feature; displayed as a paragraph.
thumbnail string The name of a feature property that contains a URL for an image. Displayed as a thumbnail next to the description.
url string The name of a feature property with a URL to use to create a link (e.g. to learn more information about the given feature)
urlText string The name of a feature property that has text to display for the url. Defaults to 'Read More' if none is set.
Since:
  • 2.19.0
Source:

VectorFilterConfig

A VectorFilterConfig specifies conditions under which specific features of a vector layer on a map should be visible. The filter defines rules used to show features conditionally based on properties of the feature. For example, it could specify hiding all vectors for an asset that have an area greater than 10km2. This configuration is passed to the VectorFilter model.
Type:
  • Object
Properties:
Name Type Description
filterType 'categorical' | 'numeric' If categorical, then a feature will be visible when its property value exactly matches one of those listed in the values attribute. If numeric, then a feature will be visible when its property value is between the min and max.
property string The property (attribute) of the MapAsset feature to filter on.
values Array.<string> | Array.<number> Only used for categorical filters. If the property matches one of the values listed, the feature will be displayed. If the filter type is categorical and no values are set, then features will not be filtered on this property.
max number Only used for numeric filters. The property's value must be less than the value set here for the feature to be visible. If the filter type is numeric, and max is set, then the max is infinite.
min number Only used for numeric filters. The property's value must be greater than the value set here for the feature to be visible. If the filter type is numeric, and min is set, then the min is minus infinity.
Source:
Examples
// Only show vectors with an 'area' property set to less than 10
{
  filterType: 'numeric'
  property: 'area'
  max: 10
}
// Show only features that have the 'boreal' or 'tropical' property set on their 'forestType' attribute
{
  filterType: 'categorical'
  property: 'forestType'
  values: ['boreal', 'tropical']
}