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.
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.
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.
Elements placed in the 3D scene take a position as either Cartesian or Cartographic coordinates.
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.
| Position | Offsets | Description |
|---|---|---|
| "TopLeft" | left, top | Measured from the top-left corner. This is the default. |
| "TopRight" | right, top | Measured from the top-right corner. |
| "BottomLeft" | left, bottom | Measured from the bottom-left corner. |
| "BottomRight" | right, bottom | Measured 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, top | The 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".
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.
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.
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.
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.
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.
Polygon
A filled area in the scene, either draped over the ground and models or extruded upwards.
Polyline
A line through points in the scene.
Circle
A filled circle in the scene, flat or extruded into a cylinder.
3D box
A box in the scene, centred on a position.
Sphere
A sphere in the scene, centred on a position.
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.
Section box
A section box hides what is inside or outside a box, for example to isolate one floor of a building.
Terrain section
A terrain section cuts a hole in the terrain around an outline, for example to show underground pipes.
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.
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.
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.
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.