Drawing package requirements

You can convert uploaded drawing packages into map data by using the Azure Maps Conversion service. This article describes the drawing package requirements for the Conversion API. To view a sample package, you can download the sample Drawing package.

Prerequisites

The drawing package includes drawings saved in DWG format, which is the native file format for Autodesk's AutoCAD® software.

You can choose any CAD software to produce the drawings in the drawing package.

The Conversion service converts the drawing package into map data. The Conversion service works with the AutoCAD DWG file format AC1032.

Glossary of terms

For easy reference, here are some terms and definitions that are important as you read this article.

Drawing package structure

A drawing package is a .zip archive that contains the following files:

• DWG files in AutoCAD DWG file format.
• A manifest.json file that describes the DWG files in the drawing package.

The drawing package must be zipped into a single archive file, with the .zip extension. The DWG files can be organized in any way inside the package, but the manifest file must live at the root directory of the zipped package. The next sections detail the requirements for the DWG files, manifest file, and the content of these files. To view a sample package, you can download the sample drawing package.

DWG file conversion process

The Conversion service does the following on each DWG file:

• Extracts feature classes:
  • Levels
  • Units
  • Zones
  • Openings
  • Walls
  • Vertical penetrations
• Produces a Facility feature.
• Produces a minimal set of default Category features referenced by other features:
  • room
  • structure
  • wall
  • opening.door
  • zone
  • facility

DWG file requirements

A single DWG file is required for each level of the facility. All data of a single level must be contained in a single DWG file. Any external references (xrefs) must be bound to the parent drawing. For example, a facility with three levels has three DWG files in the drawing package.

Each DWG file must adhere to the following requirements:

• The DWG file must define the Exterior and Unit layers. It can optionally define the following layers: Wall, Door, UnitLabel, Zone, and ZoneLabel.
• The DWG file can't contain features from multiple levels.
• The DWG file can't contain features from multiple facilities.
• The DWG must reference the same measurement system and unit of measurement as other DWG files in the drawing package.

DWG layer requirements

Each DWG layer must adhere to the following rules:

• A layer must exclusively contain features of a single class. For example, units and walls can’t be in the same layer.
• A single class of features can be represented by multiple layers.
• Self-intersecting polygons are permitted, but are automatically repaired. When they repaired, the Conversion service raises a warning. It's advisable to manually inspect the repaired results, because they might not match the expected results.
• Each layer has a supported list of entity types. Any other entity types in a layer will be ignored. For example, text entities aren't supported on the wall layer.

The following table outlines the supported entity types and converted map features for each layer. If a layer contains unsupported entity types, then the Conversion service ignores those entities.

The following sections describe the requirements for each layer.

Exterior layer

The DWG file for each level must contain a layer to define that level's perimeter. This layer is referred to as the exterior layer. For example, if a facility contains two levels, then it needs to have two DWG files, with an exterior layer for each file.

No matter how many entity drawings are in the exterior layer, the resulting facility dataset contains only one level feature for each DWG file. Additionally:

• Exteriors must be drawn as POLYGON, POLYLINE (closed), CIRCLE, or ELLIPSE (closed).
• Exteriors may overlap, but are dissolved into one geometry.
• Resulting level feature must be at least 4 square meters.
• Resulting level feature must not be greater 400,000 square meters.

If the layer contains multiple overlapping PolyLines, they're dissolved into a single Level feature. Instead, if the layer contains multiple non-overlapping PolyLines, the resulting Level feature has a multi-polygonal representation.

You can see an example of the Exterior layer as the outline layer in the sample drawing package.

Unit layer

The DWG file for each level defines a layer containing units. Units are navigable spaces in the building, such as offices, hallways, stairs, and elevators. If the VerticalPenetrationCategory property is defined, navigable units that span multiple levels, such as elevators and stairs, are converted to Vertical Penetration features. Vertical penetration features that overlap each other are assigned one setid.

The Units layer should adhere to the following requirements:

• Units must be drawn as POLYGON, POLYLINE (closed), CIRCLE, or ELLIPSE (closed).
• Units must fall inside the bounds of the facility exterior perimeter.
• Units must not partially overlap.
• Units must not contain any self-intersecting geometry.

Name a unit by creating a text object in the UnitLabel layer, and then place the object inside the bounds of the unit. For more information, see the UnitLabel layer.

You can see an example of the Units layer in the sample drawing package.

Wall layer

The DWG file for each level can contain a layer that defines the physical extents of walls, columns, and other building structure.

• Walls must be drawn as POLYGON, POLYLINE (closed), CIRCLE, or ELLIPSE (closed).
• The wall layer or layers should only contain geometry that's interpreted as building structure.

You can see an example of the Walls layer in the sample drawing package.

Door layer

You can include a DWG layer that contains doors. Each door must overlap the edge of a unit from the Unit layer.

Door openings in an Azure Maps dataset are represented as a single-line segment that overlaps multiple unit boundaries. The following images show how Azure Maps converts door layer geometry into opening features in a dataset.

Zone layer

The DWG file for each level can contain a Zone layer that defines the physical extents of zones. A zone is a non-navigable space that can be named and rendered. Zones can span multiple levels and are grouped together using the zoneSetId property.

• Zones must be drawn as POLYGON, POLYLINE (closed), or ELLIPSE (closed).
• Zones can overlap.
• Zones can fall inside or outside the facility's exterior perimeter.

Name a zone by creating a text object in the ZoneLabel layer, and placing the text object inside the bounds of the zone. For more information, see ZoneLabel layer.

You can see an example of the Zone layer in the sample drawing package.

UnitLabel layer

The DWG file for each level can contain a UnitLabel layer. The UnitLabel layer adds a name property to units extracted from the Unit layer. Units with a name property can have more details specified in the manifest file.

• Unit labels must be single-line text entities.
• Unit labels must fall entirely inside the bounds of their unit.
• Units must not contain multiple text entities in the UnitLabel layer.

You can see an example of the UnitLabel layer in the sample drawing package.

ZoneLabel layer

The DWG file for each level can contain a ZoneLabel layer. This layer adds a name property to zones extracted from the Zone layer. Zones with a name property can have more details specified in the manifest file.

• Zones labels must be single-line text entities.
• Zones labels must fall inside the bounds of their zone.
• Zones must not contain multiple text entities in the ZoneLabel layer.

You can see an example of the ZoneLabel layer in the sample drawing package.

Manifest file requirements

The zip folder must contain a manifest file at the root level of the directory, and the file must be named manifest.json. It describes the DWG files to allow the Conversion service to parse their content. Only the files identified by the manifest are ingested. Files that are in the zip folder, but aren't properly listed in the manifest, are ignored.

Although there are requirements when you use the manifest objects, not all objects are required. The following table shows the required and optional objects for version 1.1 of the Conversion service.

The next sections detail the requirements for each object.

directoryInfo

buildingLevels

The buildingLevels object contains a JSON array of buildings levels.

georeference

dwgLayers

unitProperties

The unitProperties object contains a JSON array of unit properties.

zoneProperties

The zoneProperties object contains a JSON array of zone properties.

Sample drawing package manifest

The following is the manifest file for the sample drawing package. Go to the Sample drawing package for Azure Maps Creator on GitHub to download the entire package.

Manifest file

{
    "version": "1.1", 
    "directoryInfo": { 
        "name": "Contoso Building", 
        "streetAddress": "Contoso Way", 
        "unit": "1", 
        "locality": "Contoso eastside", 
        "postalCode": "98052", 
        "adminDivisions": [ 
            "Contoso city", 
            "Contoso state", 
            "Contoso country" 
        ], 
        "hoursOfOperation": "Mo-Fr 08:00-17:00 open", 
        "phone": "1 (425) 555-1234", 
        "website": "www.contoso.com", 
        "nonPublic": false, 
        "anchorLatitude": 47.636152, 
        "anchorLongitude": -122.132600, 
        "anchorHeightAboveSeaLevel": 1000, 
        "defaultLevelVerticalExtent": 3  
    }, 
    "buildingLevels": { 
        "levels": [ 
            { 
                "levelName": "Basement", 
                "ordinal": -1, 
                "filename": "./Basement.dwg" 
            }, { 
                "levelName": "Ground", 
                "ordinal": 0, 
                "verticalExtent": 5, 
                "filename": "./Ground.dwg" 
            }, { 
                "levelName": "Level 2", 
                "ordinal": 1, 
                "heightAboveFacilityAnchor": 3.5, 
                "filename": "./Level_2.dwg" 
            } 
        ] 
    }, 
    "georeference": { 
        "lat": 47.636152, 
        "lon": -122.132600, 
        "angle": 0 
    }, 
    "dwgLayers": { 
        "exterior": [ 
            "OUTLINE", "WINDOWS" 
        ], 
        "unit": [ 
            "UNITS" 
        ], 
        "wall": [ 
            "WALLS" 
        ], 
        "door": [ 
            "DOORS" 
        ], 
        "unitLabel": [ 
            "UNITLABELS" 
        ], 
        "zone": [ 
            "ZONES" 
        ], 
        "zoneLabel": [ 
            "ZONELABELS" 
        ] 
    }, 
    "unitProperties": [ 
        { 
            "unitName": "B01", 
            "categoryName": "room.office", 
            "occupants": [ 
                { 
                    "name": "Joe's Office", 
                    "phone": "1 (425) 555-1234" 
                } 
            ], 
            "nameAlt": "Basement01", 
            "nameSubtitle": "01", 
            "addressRoomNumber": "B01", 
            "nonPublic": true, 
            "isRoutable": true, 
            "isOpenArea": true 
        }, 
        { 
            "unitName": "B02" 
        }, 
        { 
            "unitName": "B05", 
            "categoryName": "room.office" 
        }, 
        { 
            "unitName": "STRB01", 
            "verticalPenetrationCategory": "verticalPenetration.stairs", 
            "verticalPenetrationDirection": "both" 
        }, 
        { 
            "unitName": "ELVB01", 
            "verticalPenetrationCategory": "verticalPenetration.elevator", 
            "verticalPenetrationDirection": "high_to_low" 
        } 
    ], 
    "zoneProperties": 
    [ 
        { 
            "zoneName": "WifiB01", 
            "categoryName": "Zone", 
            "zoneNameAlt": "MyZone", 
            "zoneNameSubtitle": "Wifi", 
            "zoneSetId": "1234" 
        }, 
        { 
            "zoneName": "Wifi101",
            "categoryName": "Zone",
            "zoneNameAlt": "MyZone",
            "zoneNameSubtitle": "Wifi",
            "zoneSetId": "1234"
        }
    ]
}

You can convert uploaded drawing packages into map data by using the Azure Maps Conversion service. This article describes the drawing package requirements for the Conversion API. To view a sample package, you can download the sample drawing package v2.

For a guide on how to prepare your drawing package, see Drawing Package Guide.

Changes and Revisions

• Added support for user defined feature classes.
• Simplified requirements of DWG layers.

Prerequisites

The drawing package includes drawings saved in DWG format, which is the native file format for Autodesk's AutoCAD® software.

You can choose any CAD software to produce the drawings in the drawing package.

The Conversion service converts the drawing package into map data. The Conversion service works with the AutoCAD DWG file format AC1032.

Glossary of terms

For easy reference, here are some terms and definitions that are important as you read this article.

Drawing package structure

A drawing package is a ZIP archive that contains the following files:

• DWG files in AutoCAD DWG file format.
• A manifest.json file that describes the DWG files in the drawing package.

The drawing package must be compressed into a single archive file, with the .zip extension. The DWG files can be organized in any way inside the drawing package, but the manifest file must be in the root directory. The next sections explain the conversion process and requirements for both the DWG and manifest files, and the content of these files. To view a sample package, you can download the sample drawing package v2.

DWG file conversion process

The Azure Maps Conversion service converts DWG file(s) of a facility to map data representing a facility and features of a facility.

The Azure Maps Conversion service creates:

• Facility Feature: The top-level feature of a facility that all levels of a facility are associated to.
• Level features: One Level feature is created for each floor of a facility. All features on a level are associated with a level.
• User defined features: DWG layers are mapped to a user defined feature class and become instances of the feature class.

DWG file requirements

Each DWG file must adhere to these requirements:

• The DWG file can't contain features from multiple facilities.
• The DWG file can't contain features from multiple levels. For example, a facility with three levels has three DWG files in the drawing package.
• All data of a single level must be contained in a single DWG file. Any external references (xrefs) must be bound to the parent drawing.
• The DWG file must define layer(s) representing the boundary of that level.
• The DWG must reference the same measurement system and unit of measurement as other DWG files in the drawing package.
• The DWG file must be aligned when stacked on top of another level from the same facility.

DWG layer requirements

Feature classes

One or more DWG layer(s) can be mapped to a user defined feature class. One instance of the feature is created from an entity on the mapped layer. For example, DWG layers chair, table, and couch are mapped to a feature class called furniture. A furniture feature is created for every entity from the defined layers. Additionally:

• All layers should be separated to represent different feature types of the facility.
• All entities must fall inside the bounds of the level perimeter.
• Supported AutoCAD entity types: TEXT, MTEXT, POINT, ARC, CIRCLE, LINE, POLYLINE, ELLIPSE.

Feature class properties

Text entities that fall within the bounds of a closed shape can be associated to that feature as a property. For example, a room feature class might have text that describes the room name and another the room type sample drawing package v2. Additionally:

• Only TEXT and MTEXT entities are associated to the feature as a property. All other entity types are ignored.
• The TEXT and MTEXT justification point must fall within the bounds of the closed shape.
• If more than one TEXT property is within the bounds of the closed shape and both are mapped to one property, one is randomly selected.

Facility level

The DWG file for each level must contain a layer to define that level's perimeter. For example, if a facility contains two levels, then it needs to have two DWG files, each with a layer that defines that level's perimeter.

No matter how many entity drawings are in the level perimeter layer, the resulting facility dataset contains only one level feature for each DWG file. Additionally:

• Level perimeters must be drawn as POLYGON, POLYLINE (closed), CIRCLE, or ELLIPSE (closed).
• Level perimeters may overlap but are dissolved into one geometry.
• The resulting level feature must be at least 4 square meters.
• The resulting level feature must not be greater than 400,000 square meters.

If the layer contains multiple overlapping POLYLINES, they're combined into a single Level feature. Instead, if the layer contains multiple nonoverlapping POLYLINES, the resulting Level feature has a multi-polygonal representation.

You can see an example of the Level perimeter layer as the GROS$ layer in the sample drawing package v2.

Manifest file requirements

The drawing package must contain a manifest file at the root level and the file must be named manifest.json. It describes the DWG files allowing the  Conversion service to parse their content. Only the files identified by the manifest are used. Files that are in the drawing package, but aren't properly listed in the manifest, are ignored.

The file paths in the buildingLevels object of the manifest file must be relative to the root of the drawing package. The DWG file name must exactly match the name of the facility level. For example, a DWG file for the "Basement" level is Basement.dwg. A DWG file for level 2 is named as level_2.dwg. Filenames can't contain spaces, you can use an underscore to replace any spaces.

Although there are requirements when you use the manifest objects, not all objects are required. The following table shows the required and optional objects for the 2023-03-01-preview Conversion service.

Manifest JSON file

The next sections detail the requirements for each object.

buildingLevels

level

featureClass

featureClassProperty

georeference

Sample drawing package manifest

The JSON in this example shows the manifest file for the sample drawing package. Go to the sample drawing package v2 for Azure Maps Creator on GitHub to download the entire package.

Manifest file

{
  "version": "2.0",
  "buildingLevels": {
    "dwgLayers": [
      "GROS$"
    ],
    "levels": [
      {
        "filename": "Ground.dwg",
        "levelName": "level 1",
        "ordinal": 0
      },
      {
        "filename": "Level_2.dwg",
        "levelName": "level 2",
        "ordinal": 1
      }
    ]
  },
  "georeference": {
    "lat": 47.63529901,
    "lon": -122.13355885,
    "angle": 0
  },
  "featureClasses": [
    {
      "featureClassName": "room",
      "dwgLayers": [
        "RM$"
      ],
      "featureClassProperties": [
        {
          "featureClassPropertyName": "name",
          "dwgLayers": [
            "A-IDEN-NUMR-EXST"
          ]
        },
        {
          "featureClassPropertyName": "roomType",
          "dwgLayers": [
            "A-IDEN-NAME-EXST"
          ]
        }
      ]
    },
    {
      "featureClassName": "wall",
      "dwgLayers": [
        "A-WALL-EXST",
        "A-WALL-CORE-EXST",
        "A-GLAZ-SILL-EXST",
        "A-GLAZ-SHEL-SILL-EXST",
        "A-GLAZ-SHEL-EXST",
        "A-GLAZ-EXST"
      ]
    },
    {
      "featureClassName": "workspace",
      "dwgLayers": [
        "A-BOMA"
      ]
    },
    {
      "featureClassName": "workspaceFurniture",
      "dwgLayers": [
        "A-FURN-SYTM-EXST"
      ]
    },
    {
      "featureClassName": "buildingFurniture",
      "dwgLayers": [
        "A-FURN-FREE-EXST"
      ]
    }
  ],
  "facilityName": "Contoso Building"
}