JSON: Markup


Markup is the set of text boxes, callouts, lines, shapes, sections and labels drawn over a scene in Navigator. It is stored as a JSON object and rendered when a bookmark is opened.

Markup files use the file extension ".bmarkup" and are JSON text files. They can be exported and imported from the Markup panel in Navigator.

This article will cover where markup is stored, the top-level structure, and each kind of element.

Where markup is stored

Markup lives in three places, all with the same structure.

// 1. A bookmark's own markup, shown only with that bookmark.
Bookmark.Settings.markup

// 2. Markup shared across a Project View's bookmarks.
// Each element's "bookmarkIds" says which bookmarks it appears in.
ProjectView.Settings.defaults.settings.markup

// 3. Markup records, which hold the templates in Navigator's markup panel.
UI.Markup MarkupContent

When a bookmark is opened, its own markup and the shared elements that appear in it are drawn together. You can read about bookmarks in Project Views and Bookmarks and about Markup records in Markup.

Top-level structure

The root object holds three lists of elements and the screen size the markup was drawn at. Elements are scaled when the viewer is a different size.

interface IMarkup {
    // Text boxes, shapes and callout boxes, drawn over the viewer.
    divs?: IDiv[];
    // Lines and free-paint strokes, drawn over the viewer.
    vectors?: (ILine | IPaint)[];
    // Everything placed in the 3D scene, plus labels, dialogs and groups.
    cesiumObjects?: (IPolygon | IPolyline | ICircle | IRectangle | ISphere |
                     ISection | ISectionBox | ITerrainSection | IElementGroup | ILabels | INavDialog)[];
    // Screen size in pixels the markup was drawn at.
    width?: number;
    height?: number;
    // Set to false to hide the whole markup.
    // Default is true.
    visible?: boolean;
}

Elements in "cesiumObjects" are told apart by their "type" value. Lines and free-paint strokes are told apart by "pathType", and anything with "contentRows" is a div.

Base element

Every element shares the fields below. The id must be unique within the markup, as other elements refer to it. For example a line snaps to a div by its id.

interface IElement {
    // Unique id of the element within the markup.
    id: string;
    // Human readable name shown in Navigator's markup panel.
    name?: string;
    // Default is true.
    visible?: boolean;
    // Screen size in pixels when the element was drawn.
    screenWidth?: number;
    screenHeight?: number;
    // Only read on shared markup. The bookmark IDs the element appears in.
    // When empty, the element appears in every bookmark of the Project View.
    bookmarkIds?: string[];
}

Elements placed in the 3D scene take a position as either Cartesian or Cartographic coordinates.

// Earth-centred Cartesian coordinates, in metres.
interface ICartes3 {
    x: number;
    y: number;
    z: number;
}

// Latitude and longitude in degrees, altitude in metres.
interface ICarto {
    latitude: number;
    longitude: number;
    altitude: number;
}

Div

A div is a box drawn over the viewer. Divs are used for text boxes, info panels, legends, image tiles and callout boxes.

The div has a width and height in pixels. Its content is laid out as rows, and each row as cells. Row heights are a percentage of the div's height and cell widths a percentage of the row's width, so each should add up to 100. For example two equal cells in one row would each have a width of 50.

The "position" value sets which corner of the viewer the div is measured from, and which pair of offsets is read.

PositionOffsetsDescription
"TopLeft"left, topMeasured from the top-left corner. This is the default.
"TopRight"right, topMeasured from the top-right corner.
"BottomLeft"left, bottomMeasured from the bottom-left corner.
"BottomRight"right, bottomMeasured from the bottom-right corner. This is the usual spot for legends, as it has the most free space. A typical offset is a right of 120 and a bottom of 12.
"fixed"left, topThe div is not moved when Navigator's panels open or close.

When the viewer is resized, the div keeps its distance from its corner. All colour values accept css colour strings, such as "#1d70e7", "rgba(29, 112, 231, 0.75)" or "white".

interface IDiv extends IElement {
    // "callout" for a box tied to a point in the scene by a line. See the Div: Callout section below.
    // Default is "default".
    type?: "default" | "callout";
    // The div's content. See the Div: Row and cell section below.
    contentRows: IRow[];
    // Width and height in pixels.
    width: number;
    height: number;
    // FIXED = the height is the height, and content that does not fit is clipped.
    // AUTO = the content decides the height, with the stored height as the minimum.
    // Default is "FIXED".
    cellSizing?: "FIXED" | "AUTO";
    // Which corner the offsets are measured from. See the table above.
    position?: "TopLeft" | "TopRight" | "BottomLeft" | "BottomRight" | "fixed";
    // Offsets in pixels. Use the pair that matches the position.
    left?: number;
    top?: number;
    right?: number;
    bottom?: number;
    borderColor?: string;
    borderWidth?: number;
    // Border radius in pixels, or percent when "borderUsingPercent" is true.
    borderRadius?: number;
    borderUsingPercent?: boolean;
    boxShadow?: {
        horizontal: number;
        vertical: number;
        blur: number;
        spread: number;
        color: string;
    };
    // Default text styling for the div.
    backgroundColor?: string;
    fontColor?: string;
    fontSize?: number;
    // For callouts. Camera distance in metres beyond which the div is hidden.
    visibleMaxDistance?: number;
    // For callouts. Camera distance in metres inside which the div is hidden.
    // Absent or 0 means it never hides for being close.
    visibleMinDistance?: number;
}

Div: Row and cell

A div's content is a list of rows, and each row holds cells. Each cell has a content type that dictates what it shows.

interface IRow {
    // Unique id of the row within the div.
    id?: string;
    // Height as a percentage of the div's height. All rows should add up to 100.
    height: number;
    // The cells within this row.
    items: IRowItem[];
}

interface IRowItem {
    // Unique id of the cell within the row.
    id?: string;
    /**
     * What the cell shows.
     *
     * Default = the text in "text".
     * Embed = the html in "embedRaw", filling the whole cell.
     * Icon = the font-awesome icon in "icon".
     * Image = the background image only.
     * None = no content, only the cell's colours.
     */
    contentType?: "DEFAULT" | "EMBED" | "ICON" | "IMAGE" | "NONE";
    // Text to show. Html is cleaned before it is shown.
    text?: string;
    // Raw html to show when the content type is "EMBED".
    embedRaw?: string;
    // Font-awesome icon class when the content type is "ICON". Eg: "fas fa-star".
    icon?: string;
    // Background image for the cell.
    bgImage?: {
        // Client File ID of the image.
        FileID?: string;
        // If true then the default image of the markup's Entity is used.
        UseEntityDefault?: boolean;
    };
    // Width as a percentage of the row's width. All cells in a row should add up to 100.
    width?: number;
    backgroundColor?: string;
    fontColor?: string;
    fontSize?: number;
    // css text alignment. Eg: "center".
    textAlign?: string;
    verticalAlign?: string;
    // css padding. Eg: "5px 5px 5px 5px".
    innerPadding?: string;
    textShadow?: {
        horizontal: number;
        vertical: number;
        blur: number;
        color: string;
    };
    // What happens when the cell is clicked. See the Div: Cell actions section below.
    action?: IItemAction;
}

Div: Cell actions

Each cell can have an action that runs when it is clicked. Actions that open Entity details act on the Entity the markup belongs to.

interface IItemAction {
    /**
     * The action to run.
     *
     * None = nothing happens.
     * Link = opens the URL in the params.
     * Info view = opens the Entity's details panel.
     * Gallery = opens the Entity's gallery.
     * Relationships = toggles the Entity's relationships in the scene.
     * Draggable = the cell can be used to drag the div around.
     * Close = closes the markup.
     * Bookmark = opens another bookmark in the same Project View.
     */
    type: "NONE" | "LINK" | "INFOVIEW" | "GALLERY" | "RELATIONSHIPS" | "DRAGABBLE" | "CLOSE" | "BOOKMARK";
    // Params are based on the action type. Use {} when there are none.
    params: ILinkParams | IGalleryParams | IBookmarkParams | {};
}

interface ILinkParams {
    // URL to open.
    // Use ${"your_attribute_path"} to substitute in the attribute value of the Entity.
    URL?: string;
    openInNewTab?: boolean;
    // If true then the markup is closed when the link opens.
    closeMarkupOnOpen?: boolean;
}

interface IGalleryParams {
    // Only show attachments of this type.
    documentType?: string;
}

interface IBookmarkParams {
    // Bookmark ID to open.
    bookmarkID?: string;
    // Cell colours while that bookmark is the one open.
    activeBackgroundColor?: string;
    activeFontColor?: string;
}

Div: Callout

A callout is a div with a "type" of "callout" and a line that connects it to a point in the scene. The line's start snap holds the 3D position, and its end snap names the div's id and the side of the div to attach to. As the camera moves, the line follows the point and the box stays on screen.

Callout lines are usually white with a "brushSize" of 3 and "angled" set to true. The div usually has a partly transparent background such as "rgba(29, 112, 231, 0.75)" with white text.

// The div, in "divs".
{
    id: "callout-1",
    type: "callout",
    width: 160,
    height: 40,
    borderRadius: 8,
    borderColor: "white",
    borderWidth: 1,
    contentRows: [
        {
            height: 100,
            items: [
                {
                    text: "Pump Station A",
                    width: 100,
                    backgroundColor: "rgba(29, 112, 231, 0.75)",
                    fontColor: "white",
                    fontSize: 13,
                    textAlign: "center",
                    verticalAlign: "center"
                }
            ]
        }
    ]
}

// The line, in "vectors".
{
    id: "callout-line-1",
    pathType: "LINE",
    path: null,
    transform: null,
    brushColor: "rgba(255, 255, 255, 0.75)",
    brushSize: 3,
    angled: true,
    snaps: [
        // Start of the line, at a point in the scene.
        {
            side: 0,
            position: { latitude: 40.7128, longitude: -74.0060, altitude: 0 }
        },
        // End of the line, on the left middle of the div.
        {
            side: 1,
            id: "callout-1",
            snapPosition: 5
        }
    ]
}

Line

A line is drawn over the viewer between two snaps. Each snap is a point in the scene, a point on the screen, or a side of a div. When a snap names a div, the line follows the div as it moves.

interface ILine extends IElement {
    pathType: "LINE";
    // svg path and transform. These are recalculated from the snaps, so they can be null.
    path: string;
    transform: string;
    // The two ends of the line.
    snaps: IAnchor[];
    // css colour of the line.
    brushColor?: string;
    // Line width in pixels.
    brushSize?: number;
    // If true then the line bends towards its end rather than running straight.
    angled?: boolean;
    // css colour of the line's heads.
    outlineColor?: string;
}

interface IAnchor {
    // Which end of the line this is. 0 = start, 1 = end.
    side?: 0 | 1;
    // A point in the scene.
    position?: ICartes3 | ICarto;
    // A point on the screen, in pixels.
    screenPos?: { x: number; y: number };
    // If true then the position is taken from the markup's Entity.
    positionFromEntity?: boolean;
    // Id of a div to attach to.
    id?: string;
    /**
     * Where on the div to attach.
     *
     * 0 = top left, 1 = top right, 2 = bottom left, 3 = bottom right, 4 = centre,
     * 5 = centre left, 6 = centre right, 7 = centre top, 8 = centre bottom.
     */
    snapPosition?: number;
    // How this end is drawn.
    brushHead?: "NONE" | "CIRCLE" | "ARROW";
    // css fill and stroke colours of the head.
    fill?: string;
    stroke?: string;
    // Size of an "ARROW" head.
    size?: number;
    // Multiplied by "size" to give the size of a "CIRCLE" head.
    outlineFactor?: number;
}

Free-paint

A free-paint stroke is a hand drawn path over the viewer. Unlike a line it has no snaps, so it stays where it was drawn on the screen.

interface IPaint extends IElement {
    pathType: "PLAIN";
    // svg path and transform of the stroke.
    path: string;
    transform: string;
    brushColor?: string;
    // Stroke width in pixels.
    brushSize?: number;
    // How the ends of the stroke are drawn.
    brushHead?: "NONE" | "CIRCLE" | "ARROW";
    // css colour of the heads.
    outlineColor?: string;
}

Polygon

A filled area in the scene, either draped over the ground and models or extruded upwards.

interface IPolygon extends IElement {
    type: "POLYGON";
    // The boundary of the polygon.
    positions: (ICartes3 | ICarto)[];
    // css colour of the fill.
    color?: string;
    // css colour and width in pixels of the outline.
    outlineColor?: string;
    outlineWidth?: number;
    // Extrusion height in metres. 0 draws a flat polygon.
    extrudedHeight?: number;
    // BOTH = drapes over terrain and 3D models.
    // TERRAIN = drapes over terrain only.
    classificationType?: "BOTH" | "TERRAIN";
    // How many smoothing passes to run on the boundary. 0 means no smoothing.
    smoothen?: number;
}

Polyline

A line through points in the scene.

interface IPolyline extends IElement {
    type: "POLYLINE";
    positions: (ICartes3 | ICarto)[];
    // css colour of the line.
    color?: string;
    // Line width in pixels.
    outlineWidth?: number;
    // How many smoothing passes to run on the line. 0 means no smoothing.
    smoothen?: number;
}

Circle

A filled circle in the scene, flat or extruded into a cylinder.

interface ICircle extends IElement {
    type: "CIRCLE";
    // Centre of the circle.
    position: ICartes3 | ICarto;
    // Radius in metres.
    radius: number;
    // css colour of the fill.
    color?: string;
    // Extrusion height in metres.
    extrudedHeight?: number;
    // css colour, width in metres and height in metres of the outline.
    outlineColor?: string;
    outlineWidth?: number;
    outlineExtrusion?: number;
}

3D box

A box in the scene, centred on a position.

interface IRectangle extends IElement {
    type: "RECTANGLE";
    // Centre of the box.
    position: ICartes3 | ICarto;
    // Size in metres, along east, north and up. Default is 5 each.
    width: number;
    depth: number;
    height: number;
    // css colour of the box. Default is "rgba(255, 255, 0, 0.2)".
    color: string;
}

Sphere

A sphere in the scene, centred on a position.

interface ISphere extends IElement {
    type: "SPHERE";
    // Centre of the sphere.
    position: ICartes3 | ICarto;
    // Radius in metres.
    radius: number;
    // css colour of the fill. A fully transparent fill draws only the outline.
    color: string;
    // css colour of the outline. When absent no outline is drawn.
    outlineColor?: string;
}

Section plane

A section cuts away part of a tileset so you can see inside it. A plane section cuts along a plane through a point, and a polygon section cuts around an outline.

Only one section or section box applies at a time. See the element group section below for how the active one is picked.

interface ISection extends IElement {
    type: "SECTION";
    // PLANE = cuts along a plane through "position", facing "orient".
    // POLYGON = cuts around the outline in "points".
    sectionType: "PLANE" | "POLYGON";
    // Tileset to cut. When empty, every tileset is cut.
    tilesetId?: string;
    // For PLANE sections. A point on the plane, as Cartesian coordinates.
    position?: ICartes3;
    // For PLANE sections. The direction the plane faces, as a Cartesian vector.
    // When absent, the plane lies flat on the ground at the position.
    orient?: ICartes3;
    // For POLYGON sections. The outline, as Cartesian coordinates.
    points?: ICartes3[];
    // If true then the plane's move and rotate handles are hidden.
    disabled?: boolean;
    // If this section is the one applied. See the element group section below.
    active?: boolean;
    // css colour and width in pixels of the line drawn where the section cuts.
    // Default is red and 1.
    cullLinesColor?: string;
    cullLinesWidth?: number;
}

Section box

A section box hides what is inside or outside a box, for example to isolate one floor of a building.

interface ISectionBox extends IElement {
    type: "SECTION_BOX";
    // Centre of the box.
    position: ICartes3 | ICarto;
    // Size in metres.
    width: number;
    depth: number;
    height: number;
    // Rotation in degrees away from east, north and up. When absent the box lines up with them.
    transform?: {
        heading?: number;
        pitch?: number;
        roll?: number;
    };
    // ALL = cuts every tileset.
    // SELECTED = cuts only the tileset in "tilesetId". Use "GOOGLE_3D" for Google 3D tiles.
    sectionType?: "ALL" | "SELECTED";
    tilesetId?: string;
    // false = hides what is inside the box.
    // true = hides what is outside the box.
    invert?: boolean;
    // If this box is the one applied. See the element group section below.
    active?: boolean;
    // css colour and width in pixels of the line drawn where the box cuts.
    // Default is red and 1.
    cullLinesColor?: string;
    cullLinesWidth?: number;
}

Terrain section

A terrain section cuts a hole in the terrain around an outline, for example to show underground pipes.

interface ITerrainSection extends IElement {
    type: "TERRAIN_SECTION";
    // The outline of the hole, as Cartesian coordinates.
    points: ICartes3[];
    // If this section is the one applied. See the element group section below.
    active?: boolean;
}

Element group

Some elements can only apply one at a time. Sections and section boxes share one group, and terrain sections have their own. The member with "active" set to true is applied. When no member has "active" set, the first one is applied.

An element group stands in for the members in Navigator's markup panel, and can pick a different member for each bookmark.

interface IElementGroup extends IElement {
    type: "ELEMENT_GROUP";
    // The group this stands for. "section" covers sections and section boxes.
    groupType: "section" | "terrainSection";
    description?: string;
    // If true then a "None" option is offered, so nothing is applied.
    // Default is true.
    showNone?: boolean;
    // Wording for the "None" option.
    noneLabel?: string;
    // Bookmark ID to the member ID applied in that bookmark. null applies nothing.
    // This takes precedence over the members' "active" values.
    activeByBookmark?: { [bookmarkId: string]: string | null };
}

Labels

A labels element places a label on each of a set of Entities. The set comes from a saved DataLab query, a query written out in full, or a list of Entity IDs, in that order of precedence.

You can read about DataLab queries in DataLab queries.

interface ILabels extends IElement {
    type: "LABELS";
    /**
     * Which of the common ways of labelling this is. Navigator uses it to pick which settings to show.
     *
     * Text = text read from each Entity.
     * Icon = the same icon on every Entity.
     * Map icons = an attribute's value picks each Entity's icon and colour.
     * Map text = an attribute's value picks each Entity's text.
     * Custom = any combination of the settings below.
     */
    mode?: "TEXT" | "ICON" | "MAP_ICONS" | "MAP_TEXT" | "CUSTOM";

    // Saved DataLab query ID.
    queryId?: number;
    // A DataLab query written out in full.
    query?: any;
    // Entity IDs, used when neither query is set.
    entityIds?: string[];

    // How each label is drawn. Default is "text".
    presentation?: "text" | "icon" | "icon-text-above" | "icon-text-side";
    // Attribute each label shows. When empty, the Entity's name is shown.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    textAttribute?: string;
    // Hand written text for specific Entities.
    textOverrides?: { entityId: string; text: string }[];
    // Maps an attribute's values to the text shown.
    textValueMap?: IValueMap;

    // Where the icon comes from.
    iconSource?: "FONT_AWESOME" | "CLIENT_FILE";
    // Font-awesome icon class. Eg: "fas fa-cube".
    iconClass?: string;
    // Client File ID of an icon image.
    iconClientFileId?: string;
    iconColor?: string;
    iconBackground?: boolean;
    // Multiplies the icon image's own size. Default is 1.
    iconScale?: number;
    // Maps an attribute's values to the icon shown.
    iconValueMap?: IValueMap;

    // If the label is joined to its Entity by a line.
    // When unset, text labels have a line and icon labels do not.
    leader?: boolean;
    // default = a straight line from the Entity to the label.
    // angled = the label sits beside the Entity and the line bends across.
    leaderStyle?: "default" | "angled";
    // SELECT = clicking a label selects its Entity. Default is "NONE".
    userAction?: "NONE" | "SELECT";
}

interface IValueMap {
    // Attribute to read. Each segment is wrapped in quotes. Eg: "\"address\"/\"city\"".
    attribute?: string;
    values?: {
        // The attribute value this option matches.
        value?: string;
        // What is shown for it: text, a font-awesome class, or a Client File ID.
        applied?: string;
        // Icon colour for this value. When unset the element's "iconColor" is used.
        color?: string;
    }[];
}

Navigation dialog

A navigation dialog is a small panel over the viewer that lists places to go. It lists the Project View's bookmarks, or the members of an element group so the viewer can switch which section is applied.

interface INavDialog extends IElement {
    type: "NAV_DIALOG";
    description?: string;
    // Which corner of the viewer the dialog sits in.
    anchor?: "TopLeft" | "TopRight" | "BottomLeft" | "BottomRight";
    // BOOKMARKS = lists bookmarks.
    // GROUP = lists the members of the element group in "groupType".
    // Default is "BOOKMARKS".
    source?: "BOOKMARKS" | "GROUP";
    groupType?: "section" | "terrainSection";
    // AUTOMATIC = lists everything the source offers.
    // MANUAL = lists only the rows in "items".
    layout?: "AUTOMATIC" | "MANUAL";
    // The rows to list, in order, when the layout is "MANUAL".
    items?: {
        // Bookmark ID.
        targetId: string;
        // Font-awesome icon html. Eg: "<i class=\"fas fa-home\"></i>".
        icon?: string;
        iconColor?: string;
    }[];
    // If false then bookmark groups are ignored and every bookmark is listed together.
    // Default is true.
    grouped?: boolean;
    // Heading for bookmarks that are not in a group.
    ungroupedLabel?: string;
    // How the rows are laid out.
    // Default is "VERTICAL", or "HORIZONTAL" for a GROUP source.
    orientation?: "VERTICAL" | "HORIZONTAL";
    // For GROUP sources. NONE = the camera is not moved.
    // BUTTON = a button on the active row moves the camera. AUTO = picking a row moves the camera.
    flyTo?: "NONE" | "BUTTON" | "AUTO";
    theme?: "DEFAULT" | "DARK" | "LIGHT";
}

Example: Colour legend

A common use is a colour legend in the bottom-right corner of the viewer that can be dragged around. The example below is a single div with a title row and three category rows, each pairing a label cell with a colour swatch cell.

{
    "width": 1920,
    "height": 1008,
    "visible": true,
    "cesiumObjects": [],
    "vectors": [],
    "divs": [
        {
            "id": "legend-001",
            "type": "default",
            "position": "BottomRight",
            "right": 120,
            "bottom": 15,
            "width": 200,
            "height": 160,
            "borderRadius": 8,
            "borderWidth": 0,
            "borderColor": "black",
            "screenWidth": 1920,
            "screenHeight": 1008,
            "boxShadow": {
                "horizontal": 2,
                "vertical": 2,
                "blur": 5,
                "spread": 3,
                "color": "rgba(0, 0, 0, 0.25)"
            },
            "contentRows": [
                {
                    "height": 25,
                    "items": [
                        {
                            "width": 100,
                            "contentType": "DEFAULT",
                            "text": "Colour Legend",
                            "textAlign": "center",
                            "verticalAlign": "center",
                            "fontSize": 13,
                            "fontColor": "white",
                            "backgroundColor": "rgba(1, 39, 73, 1)",
                            "innerPadding": "5px 5px 5px 5px",
                            "action": { "type": "DRAGABBLE", "params": {} }
                        }
                    ]
                },
                {
                    "height": 25,
                    "items": [
                        { "width": 60, "contentType": "DEFAULT", "text": "Category A", "fontSize": 13, "fontColor": "black", "backgroundColor": "white", "textAlign": "center", "verticalAlign": "center" },
                        { "width": 40, "contentType": "NONE", "backgroundColor": "rgba(0, 184, 217, 1)" }
                    ]
                },
                {
                    "height": 25,
                    "items": [
                        { "width": 60, "contentType": "DEFAULT", "text": "Category B", "fontSize": 13, "fontColor": "black", "backgroundColor": "white", "textAlign": "center", "verticalAlign": "center" },
                        { "width": 40, "contentType": "NONE", "backgroundColor": "rgba(0, 200, 83, 1)" }
                    ]
                },
                {
                    "height": 25,
                    "items": [
                        { "width": 60, "contentType": "DEFAULT", "text": "Category C", "fontSize": 13, "fontColor": "black", "backgroundColor": "white", "textAlign": "center", "verticalAlign": "center" },
                        { "width": 40, "contentType": "NONE", "backgroundColor": "rgba(170, 0, 255, 1)" }
                    ]
                }
            ]
        }
    ]
}