# 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.
`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.
`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.

Source:
  - src/js/models/maps/Map.js, line 32

### 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

####
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:
  - src/js/models/maps/Map.js, line 96

##### 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 | AssetColor#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:
  - src/js/models/maps/AssetColor.js, line 34

##### 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:
  - src/js/models/maps/AssetColorPalette.js, line 74

##### 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:
  - src/js/models/maps/assets/MapAsset.js, line 262

####
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.<string, (MapConfig#CustomDateProperty|MapConfig#CustomStringProperty)>

Since:
  - 2.19.0
Source:
  - src/js/models/maps/assets/MapAsset.js, line 242

##### 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:
  - src/js/models/maps/assets/MapAsset.js, line 276

####
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:
  - src/js/models/maps/assets/MapAsset.js, line 183

##### 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' |  |  | 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.
`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.

Source:
  - src/js/models/maps/assets/MapAsset.js, line 118

####
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. /** Executed when a new MapAsset model is created.

Since:
  - 2.22.0
Source:
  - src/js/models/maps/assets/MapAsset.js, line 289

####
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:
  - src/js/models/maps/assets/MapAsset.js, line 224

####
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:
  - src/js/models/maps/VectorFilter.js, line 35

##### 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']
    }