Merge pull request #212284 from stevemunk/SM-Creator-Custom-Styling-Preview

Articles for the creator custom styling preview

Author: jborsecnik

articles/azure-maps/creator-indoor-maps.md

@@ -10,7 +10,6 @@ services: azure-maps
 
 ---
 
-
 # Creator for indoor maps
 
 This article introduces concepts and tools that apply to Azure Maps Creator. We recommend that you read this article before you begin to use the Azure Maps Creator API and SDK.
@@ -51,6 +50,7 @@ Creator services create, store, and use various data types that are defined and
 - Converted data
 - Dataset
 - Tileset
+- Custom styles
 - Feature stateset
 
 ## Upload a Drawing package
@@ -74,6 +74,7 @@ Azure Maps Creator provides the following services that support map creation:
 - [Dataset service](/rest/api/maps/v2/dataset).
 - [Tileset service](/rest/api/maps/v2/tileset).
 Use the Tileset service to create a vector-based representation of a dataset. Applications can use a tileset to present a visual tile-based view of the dataset.
+- Custom styles. Use the [style service][style] or [visual style editor][style editor] to customize the visual elements of an indoor map.
 - [Feature State service](/rest/api/maps/v2/feature-state). Use the Feature State service to support dynamic map styling. Applications can use dynamic map styling to reflect real-time events on spaces provided by the IoT system.
 
 ### Datasets
@@ -95,10 +96,119 @@ After a tileset is created, it can be retrieved by the [Render V2 service](#rend
 If a tileset becomes outdated and is no longer useful, you can delete the tileset. For information about how to delete tilesets, see [Data maintenance](#data-maintenance).
 
 >[!NOTE]
->A tileset is independent of the dataset from which it was created. If you create tilesets from a dataset, and then subsequently update that dataset, the tilesets isn't updated. 
+>A tileset is independent of the dataset from which it was created. If you create tilesets from a dataset, and then subsequently update that dataset, the tilesets isn't updated.
 >
 >To reflect changes in a dataset, you must create new tilesets. Similarly, if you delete a tileset, the dataset isn't affected.
 
+### Custom styling (Preview)
+
+A style defines the visual appearance of a map. It defines what data to draw, the order to draw it in, and how to style the data when drawing it. Azure Maps Creator styles support the MapLibre standard for [style layers][style layers] and [sprites][sprites].
+
+When you convert a drawing package after uploading it to your Azure Maps account, default styles are applied to the elements of your map. The custom styling service enables you to customize the visual appearance of your map. You can do this by manually editing the style JSON and importing it into your Azure Maps account using the [Style - Create][create-style] HTTP request, however the recommended approach is to use the [visual style editor][style editor]. For more information, see [Create custom styles for indoor maps](how-to-create-custom-styles.md).
+
+Example layer in the style.json file:
+
+```json
+{
+	"id": "indoor_unit_gym_label",
+	"type": "symbol",
+	"filter": ["all", ["has","floor0"], ["any", ["==", "categoryName", "room.gym"]]],
+	"layout": {
+		"visibility": "none",
+		"icon-image": "gym",
+		"icon-size": {"stops": [[17.5, 0.7], [21, 1.1]]},
+		"symbol-avoid-edges": true,
+		"symbol-placement": "point",
+		"text-anchor": "top",
+		"text-field": "{name}",
+		"text-font": ["SegoeFrutigerHelveticaMYingHei-Medium"],
+		"text-keep-upright": true,
+		"text-letter-spacing": 0.1,
+		"text-offset": [0, 1.05],
+		"text-size": {"stops": [[18, 5], [18.5, 6.5], [19, 8], [19.5, 9.5], [20, 11]]}
+	},
+	"metadata": {"microsoft.maps:layerGroup": "labels_indoor"},
+	"minzoom": 17.5,
+	"paint": {
+		"text-color": "rgba(0, 0, 0, 1)",
+		"text-halo-blur": 0.5,
+		"text-halo-color": "rgba(255, 255, 255, 1)",
+		"text-halo-width": 1,
+		"text-opacity": ["step", ["zoom"], 0, 18, 1]
+	},
+	"source-layer": "Indoor unit"
+},
+```
+
+| Layer Properties | Description                                                       |
+|------------------|-------------------------------------------------------------------|
+| id               | The name of the layer                                             |
+| type | The rendering type for this layer.<br/>Some of the more common types include:<br/>**fill**: A filled polygon with an optional stroked border.<br/>**Line**: A stroked line.<br/>**Symbol**: An icon or a text label.<br/>**fill-extrusion**: An extruded (3D) polygon. |
+| filter          | Only features that match the filter criteria are displayed.       |
+| layout          | Layout properties for the layer.                                  |
+| minzoom | A number between 0 and 24 that represents the minimum zoom level for the layer. At zoom levels less than the minzoom, the layer will be hidden. |
+| paint           | Default paint properties for this layer.                          |
+| source-layer | A source supplies the data, from a vector tile source, displayed on a map. Required for vector tile sources; prohibited for all other source types, including GeoJSON sources.|
+
+#### Map configuration
+
+The map configuration is an array of configurations. Each configuration consists of a [basemap][basemap] and one or more layers, each layer consisting of a [style][style] + [tileset][tileset] tuple.
+
+The map configuration is used when you [Instantiate the Indoor Manager][instantiate-indoor-manager] of a Map object when developing applications in Azure Maps. It's referenced using the `mapConfigurationId` or `alias`. Map configurations are immutable. When making changes to an existing map configuration, a new map configuration will be created, resulting in a different `mapConfingurationId`. Anytime you create a map configuration using an alias already used by an existing map configuration, it will always point to the new map configuration.
+
+Below is an example of a map configuration JSON showing the default configurations. See the table below for a description of each element of the file:
+
+```json
+{
+    "version": 1.0,
+    "description": "This is the default Azure Maps map configuration for facility ontology tilesets.",
+    "defaultConfiguration": "indoor_light",
+    "configurations": [
+        {
+            "name": "indoor_light",
+            "displayName": "Indoor light",
+            "description": "A base style for Azure Maps.",
+            "thumbnail": "indoor_2022-01-01.png",
+            "baseMap": "microsoft_light",
+            "layers": [
+                {
+                    "tilesetId": "fa37d225-924e-3f32-8441-6128d9e5519a",
+                    "styleId": "microsoft-maps:indoor_2022-01-01"
+                }
+            ]
+        },
+        {
+            "name": "indoor_dark",
+            "displayName": "Indoor dark",
+            "description": "A base style for Azure Maps.",
+            "thumbnail": "indoor_dark_2022-01-01.png",
+            "baseMap": "microsoft_dark",
+            "layers": [
+                {
+                    "tilesetId": "fa37d225-924e-3f32-8441-6128d9e5519a",
+                    "styleId": "microsoft-maps:indoor_dark_2022-01-01"
+                }
+            ]
+        }
+    ]
+}
+```
+
+| Style Object Properties | Description                    |
+|-------------------------|--------------------------------|
+| Name        | The name of the style.                     |
+| displayName | The display name of the style.             |
+| description | The user defined description of the style. |
+| thumbnail   | Use to specify the thumbnail used in the style picker for this style. For more information, see the [style picker control][style-picker-control]. |
+| baseMap     | Use to Set the base map style.             |
+| layers      | The layers array consists of one or more *tileset + Style* tuples, each being a layer of the map. This enables multiple buildings on a map, each building represented in its own tileset. |
+
+#### Additional information
+
+- For more information how to modify styles using the style editor, see [Create custom styles for indoor maps][style-how-to].
+- For more information on style Rest API, see [style][style] in the Maps Creator Rest API reference.
+- For more information on the map configuration Rest API, see [Creator - map configuration Rest API][map-config-api].
+
 ### Feature statesets
 
 Feature statesets are collections of dynamic properties (*states*) that are assigned to dataset features, such as rooms or equipment. An example of a *state* can be temperature or occupancy. Each *state* is a key/value pair that contains the name of the property, the value, and the timestamp of the last update.
@@ -126,7 +236,7 @@ You can use the [Web Feature Service (WFS) API](/rest/api/maps/v2/wfs) to query
 
 ### Alias API
 
-Creator services such as Conversion, Dataset, Tileset, and Feature State return an identifier for each resource that's created from the APIs. The [Alias API](/rest/api/maps/v2/alias) allows you to assign an alias to reference a resource identifier.
+Creator services such as Conversion, Dataset, Tileset and Feature State return an identifier for each resource that's created from the APIs. The [Alias API](/rest/api/maps/v2/alias) allows you to assign an alias to reference a resource identifier.
 
 ### Indoor Maps module
 
@@ -161,3 +271,18 @@ The following example shows how to update a dataset, create a new tileset, and d
 
 > [!div class="nextstepaction"]
 > [Tutorial: Creating a Creator indoor map](tutorial-creator-indoor-maps.md)
+
+> [!div class="nextstepaction"]
+> [Create custom styles for indoor maps](how-to-create-custom-styles.md)
+
+[style layers]: https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#layout
+[sprites]: https://docs.mapbox.com/help/glossary/sprite/
+[create-style]: /rest/api/maps/v20220901preview/style/create
+[basemap]: supported-map-styles.md
+[style]: /rest/api/maps/v20220901preview/style
+[tileset]: /rest/api/maps/v20220901preview/tileset
+[style-picker-control]: choose-map-style.md#add-the-style-picker-control
+[style-how-to]: how-to-create-custom-styles.md
+[map-config-api]: /rest/api/maps/v20220901preview/mapconfiguration
+[instantiate-indoor-manager]: how-to-use-indoor-module.md#instantiate-the-indoor-manager
+[style editor]: https://azure.github.io/Azure-Maps-Style-Editor