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.
For a guide on how to prepare your Drawing package, see Conversion Drawing Package Guide.
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 Azure Maps 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.
| Term | Definition |
|---|---|
| Layer | An AutoCAD DWG layer from the drawing file. |
| Entity | An AutoCAD DWG entity from the drawing file. |
| Xref | A file in AutoCAD DWG file format, attached to the primary drawing as an external reference. |
| Level | An area of a building at a set elevation. For example, the floor of a building. |
| Feature | An instance of an object produced from the Conversion service that combines a geometry with metadata information. |
| Feature classes | A common blueprint for features. For example, a unit is a feature class, and an office is a feature. |
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 Azure Maps 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 to be 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 will have 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 Azure Maps 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 table below outlines the supported entity types and converted map features for each layer. If a layer contains unsupported entity types, then the Azure Maps Conversion service ignores those entities.
| Layer | Entity types | Converted Features |
|---|---|---|
| Exterior | Polygon, PolyLine (closed), Circle, Ellipse (closed) | Levels |
| Unit | Polygon, PolyLine (closed), Circle, Ellipse (closed) | Units and Vertical penetrations |
| Wall | Polygon, PolyLine (closed), Circle, Ellipse (closed), Structures | |
| Door | Polygon, PolyLine, Line, CircularArc, Circle | Openings |
| Zone | Polygon, PolyLine (closed), Circle, Ellipse (closed) | Zones |
| UnitLabel | Text (single line) | Not applicable. This layer can only add properties to the unit features from the Units layer. For more information, see the UnitLabel layer. |
| ZoneLabel | Text (single line) | Not applicable. This layer can only add properties to zone features from the ZonesLayer. For more information, see the ZoneLabel layer. |
The sections below 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 will contain 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, the PolyLines are 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 Azure Maps 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.
The file paths in the buildingLevels object of the manifest file must be relative to the root of the zip folder. 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." Use an underscore, if your level name has a space.
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 Azure Maps Conversion service.
Note
Unless otherwise specified, all properties with a string property type allow for one thousand characters.
| Object | Required | Description |
|---|---|---|
version |
true | Manifest schema version. Currently, only version 1.1 is supported. |
directoryInfo |
true | Outlines the facility geographic and contact information. It can also be used to outline an occupant geographic and contact information. |
buildingLevels |
true | Specifies the levels of the buildings and the files containing the design of the levels. |
georeference |
true | Contains numerical geographic information for the facility drawing. |
dwgLayers |
true | Lists the names of the layers, and each layer lists the names of its own features. |
unitProperties |
false | Can be used to insert more metadata for the unit features. |
zoneProperties |
false | Can be used to insert more metadata for the zone features. |
The next sections detail the requirements for each object.
directoryInfo
| Property | Type | Required | Description |
|---|---|---|---|
name |
string | true | Name of building. |
streetAddress |
string | false | Address of building. |
unit |
string | false | Unit in building. |
locality |
string | false | Name of a city, town, area, neighborhood, or region. |
adminDivisions |
JSON array of strings | false | An array containing address designations. For example: (Country, State) Use ISO 3166 country codes and ISO 3166-2 state/territory codes. |
postalCode |
string | false | The mail sorting code. |
hoursOfOperation |
string | false | Adheres to the OSM Opening Hours format. |
phone |
string | false | Phone number associated with the building. |
website |
string | false | Website associated with the building. |
nonPublic |
bool | false | Flag specifying if the building is open to the public. |
anchorLatitude |
numeric | false | Latitude of a facility anchor (pushpin). |
anchorLongitude |
numeric | false | Longitude of a facility anchor (pushpin). |
anchorHeightAboveSeaLevel |
numeric | false | Height of the facility's ground floor above sea level, in meters. |
defaultLevelVerticalExtent numeric |
false | Default height (thickness) of a level of this facility to use when a level's verticalExtent is undefined. |
buildingLevels
The buildingLevels object contains a JSON array of buildings levels.
| Property | Type | Required | Description |
|---|---|---|---|
levelName |
string | true | Descriptive level name. For example: Floor 1, Lobby, Blue Parking, or Basement. |
ordinal |
integer | true | Determines the vertical order of levels. Every facility must have a level with ordinal 0. |
heightAboveFacilityAnchor |
numeric | false | Level height above the anchor in meters. |
verticalExtent |
numeric | false | Floor-to-ceiling height (thickness) of the level in meters. |
filename |
string | true | File system path of the CAD drawing for a building level. It must be relative to the root of the building's zip file. |
georeference
| Property | Type | Required | Description |
|---|---|---|---|
lat |
numeric | true | Decimal representation of degrees latitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (EPSG:3857). |
lon |
numeric | true | Decimal representation of degrees longitude at the facility drawing's origin. The origin coordinates must be in WGS84 Web Mercator (EPSG:3857). |
angle |
numeric | true | The clockwise angle, in degrees, between true north and the drawing's vertical (Y) axis. |
dwgLayers
| Property | Type | Required | Description |
|---|---|---|---|
exterior |
array of strings | true | Names of layers that define the exterior building profile. |
unit |
array of strings | false | Names of layers that define units. |
wall |
array of strings | false | Names of layers that define walls. |
door |
array of strings | false | Names of layers that define doors. |
unitLabel |
array of strings | false | Names of layers that define names of units. |
zone |
array of strings | false | Names of layers that define zones. |
zoneLabel |
array of strings | false | Names of layers that define names of zones. |
unitProperties
The unitProperties object contains a JSON array of unit properties.
| Property | Type | Required | Description |
|---|---|---|---|
unitName |
string | true | Name of unit to associate with this unitProperty record. This record is only valid when a label matching unitName is found in the unitLabel layers. |
categoryName |
string | false | Purpose of the unit. A list of values that the provided rendering styles can make use of is available here. |
occupants |
array of directoryInfo objects | false | List of occupants for the unit. |
nameAlt |
string | false | Alternate name of the unit. |
nameSubtitle |
string | false | Subtitle of the unit. |
addressRoomNumber |
string | false | Room, unit, apartment, or suite number of the unit. |
verticalPenetrationCategory |
string | false | When this property is defined, the resulting feature is a vertical penetration (VRT) rather than a unit. You can use vertical penetrations to go to other vertical penetration features in the levels above or below it. Vertical penetration is a Category name. If this property is defined, the categoryName property is overridden with verticalPenetrationCategory. |
verticalPenetrationDirection |
string | false | If verticalPenetrationCategory is defined, optionally define the valid direction of travel. The permitted values are: lowToHigh, highToLow, both, and closed. The default value is both. The value is case-sensitive. |
nonPublic |
bool | false | Indicates if the unit is open to the public. |
isRoutable |
bool | false | When this property is set to false, you can't go to or through the unit. The default value is true. |
isOpenArea |
bool | false | Allows the navigating agent to enter the unit without the need for an opening attached to the unit. By default, this value is set to true for units with no openings, and false for units with openings. Manually setting isOpenArea to false on a unit with no openings results in a warning, because the resulting unit won't be reachable by a navigating agent. |
zoneProperties
The zoneProperties object contains a JSON array of zone properties.
| Property | Type | Required | Description |
|---|---|---|---|
| zoneName | string | true | Name of zone to associate with zoneProperty record. This record is only valid when a label matching zoneName is found in the zoneLabel layer of the zone. |
| categoryName | string | false | Purpose of the zone. A list of values that the provided rendering styles can make use of is available here. |
| zoneNameAlt | string | false | Alternate name of the zone. |
| zoneNameSubtitle | string | false | Subtitle of the zone. |
| zoneSetId | string | false | Set ID to establish a relationship among multiple zones so that they can be queried or selected as a group. For example, zones that span multiple levels. |
Sample Drawing package manifest
Below 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"
}
]
}
Next steps
When your Drawing package meets the requirements, you can use the Azure Maps Conversion service to convert the package to a map dataset. Then, you can use the dataset to generate an indoor map by using the indoor maps module.
Feedback
Submit and view feedback for