MVF v2 Data Model
Mappedin SDK version 6 is currently in an alpha state while Mappedin perfects a new design. Breaking changes may occur, which will be posted in the v6 release notes.
The Mappedin Venue Format (MVF) bundle contains a number of GeoJSON and JSON files which describe the geometry of the map and suggest how it should be rendered. These files are grouped into Core (necessary geometry) and Extensions (render styles).
Core
The core data models of an MVF are the essential files required to render a building. They iclude Connection, Entrance, Manifest, Map, MapStack, Node, Obstruction and Space.
Connection
connection.json
A connection is a mechanism that facilitates traversal between levels, such as a staircase or an elevator. The connection.json file contains a array of the connections for the entire building.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with c_. | No |
| type | Possible values include "stairs" or "elevator". | No |
| nodes | A string array of node identifiers which are part of this this connection. | No |
| externalId | A string identifier which links this connection to an external service. | No |
| accessible | A boolean indicating whether or not this connection is wheelchair accessible. | Yes |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
Entrance
entrance/m_*.geojson
An entrance is an opening in the wall which facilitates traversal between two spaces. Entrances are represented in FeatureCollections of GeoJSON LineStrings. They are split up by map ID within the entrance directory.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with e_. | No |
| externalId | A string identifier which links this entrance to an external service. | No |
| node | A string identifier of a node associated with this entrance. | Yes |
| details | A Details object containing additional information about an entrance. | Yes |
| details | An optional object containing additional properties. See Details. | Yes |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
Manifest
manifest.geojson
The manifest is a GeoJSON FeatureCollection containing a single feature. This feature has a Point property called geometry which is roughly the center point of the MVF. The manifest properties describe the MVF bundle.
| Property | Description | Optional |
|---|---|---|
| name | A string containing the name of the building. | No |
| org_id | A unique string identifier for the organization which owns the building. | Yes |
| folder_struct | An array of objects describing the files and folders contained in the MVF bundle. | No |
| version | A string containing the MVF version. | No |
| time | An ISO 8601 date-time string, including timezone offset. | No |
Map
map.geojson
A map is a level or floor within a mapstack. The map.geojson file contains an array of maps for the current mapstack.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with m_. | No |
| externalId | A string identifier which links this map to an external service. | No |
| elevation | An integer representing the elevation of this map relative to other maps in the stack. | No |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
MapStack
mapstack.geojson
A map stack is a collection of maps for each level or floor in a building. The mapstack.geojson file contains an array of map stacks.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with mg_. | No |
| externalId | A string identifier which links this map stack to an external service. | No |
| name | A string containing the name of this map stack. | No |
| maps | A string array of map identifiers which are part of this this stack. | No |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
Node
node.geojson
A node is a point on the map that is used to create a path from a starting location to a destination. Nodes may be linked to other nodes which is represented by the neighbors property. The node.geojson file contains a FeatureCollection
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with n_. | No |
| externalId | A string identifier which links this node to an external service. | No |
| map | A string identifier of the map this node is found on. | No |
| space | A string array of space identifiers which this node map be contained within. | No |
| neighbors | An array of objects identifying traversable nearby nodes. See Neighbor. | No |
Obstruction
obstruction/m_*.geojson
An obstruction is a non-traversable area (e.g. wall), meaning a path will never be created through an obstruction. Obstructions are represented in FeatureCollections of GeoJSON Polygons or LineStrings. They are split up by map ID within the obstruction directory.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with o_. | No |
| externalId | A string identifier which links this obstruction to an external service. | No |
| kind | Possible values include "Wall" or "Desks". | Yes |
| footprintComponent | A boolean indicating whether this obstruction is considered part of the footprint of the building it is a part of. For example, an exterior wall would be considered part of the building footprint. | Yes |
| center | The center of mass of this obstruction, if it is a polygon. This is undefined for line strings as this can be trivially derived. | Yes |
| entrances | A string array of entrance identifiers which can be used to navigate through this obstruction. | No |
| details | An optional object containing additional properties. See Details. | Yes |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
Space
space/m_*.geojson
A space is traversable and enclosed with walls, such as a room or hallway. Spaces are represented in FeatureCollections of GeoJSON Polygons, LineStrings, or Points. They are split up by map ID within the space directory.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with s_. | No |
| externalId | A string identifier which links this space to an external service. | No |
| kind | Possible values include "default", "hallway", "exterior", "void", "connection.stairs", "connection.elevator", or "poi". | Yes |
| details | An optional object containing additional properties. See Details. | Yes |
| metadata | An object containing any extra metadata which is not part of the MVF spec. Presence of any key or value is not guaranteed. | Yes |
Extensions
Extensions are additional data models which describe how an MVF should be rendered and other properties not essential to the building geometry. Extensions are Annotation, Shapes, ShapeInstances, Styles, Polygons, LineStringds and Window.
Annotation
annotation/m_*.geojson
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with a_. | No |
| symbolId | A string identifier for the annotation symbol to be displayed. | No |
Shapes
shapes.json
| Property | Description | Optional |
|---|---|---|
| geometry | An array of number tuples for each vertex in a local coordinate system, measured in metres. | No |
| altitude | A number indicating how far off the "ground" the shape is, in metres. | No |
| height | A number indicating the height of the shape, in metres. | No |
ShapeInstances
shapeInstances/m_*.json
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with sh_. | No |
| material | An object describing the appearance of this shape instance. See Material. | No |
Styles
styles.json
Styles are non-essential properties which describe how the GeoJSON geometry should be rendered. The style.json file contains key-value pairs of styles. The key is a user-defined string and can be any value. The value is an object containing properties depending on the GeoJSON type.
Default
These style properties are available for all GeoJSON types.
| Property | Description | Optional |
|---|---|---|
| altitude | A number indicating how far off the "ground" the objects belonging to this layer should be drawn, in metres. | No |
| color | A string containing a hex code beginning with #. | No |
| height | A number indicating the height of the objects belonging to this layer, in metres. | No |
| opacity | A number between 0 and 1 indicating the opaqueness of objects belonging to this layer. | No |
Polygons
These style properties apply only to GeoJSON Polygons.
| Property | Description | Optional |
|---|---|---|
| polygons | A string array of obstruction or space identifiers which this style applies to. | No |
LineStrings
These style properties apply only to GeoJSON LineStrings.
| Property | Description | Optional |
|---|---|---|
| width | A number indicating how far off the "ground" the objects belonging to this layer should be drawn, in metres. | No |
| lineStrings | A string array of entrance, obstruction, or space identifiers which this style applies to. | No |
Window
window/m_*.geojson
A window is a non-traversable cutout in an wall, meaning a path will never be created through a window. Windows are represented in FeatureCollections of GeoJSON LineStrings. They are split up by map ID within the window directory.
| Property | Description | Optional |
|---|---|---|
| id | A unique string identifier beginning with w_. | No |
Additional Data Types
Additional data types provide further information about a map. They are made up of Details, Neighbor, Material and Texture.
Details
Additional information about a given entity.
| Property | Description | Optional |
|---|---|---|
| name | Name of the entity. | Yes |
| description | Description of the entity. | Yes |
| links | An array of objects containing properties url and optional displayName. | Yes |
| images | An array of objects containing properties url and optional altText. | Yes |
Neighbor
A traversable node neighbour.
| Property | Description | Optional |
|---|---|---|
| flags | A string containing special properties for this node. | No |
| id | The string identifier of the node. | No |
| weight | The cost of navigating to this node. Minimum is 0. | Yes |
Material
The color and/or texture that should be applied to an instance of a Shape.
| Property | Description | Optional |
|---|---|---|
| color | A string containing a hex code beginning with #. | Yes |
| texture | An object describing the texture properties of the material. See Texture. | Yes |
Texture
A reference to an image texture and how it should be applied to a component.
| Property | Description | Optional |
|---|---|---|
| path | The path to this asset, relative to the MVF's images folder. | No |
| repeat | An object describing how the texture should be placed on a component. Its properties are a number u and a number v. | Yes |