/spec/selector/v2/) at a new URL, leaving this version permanently resolvable for files that reference it.
MeshNotes records annotations on 3D surface meshes (typically the output of photogrammetry, structured-light, or laser-scanning documentation of archaeological and cultural-heritage objects). Each annotation is expressed using the
W3C Web Annotation Data Model [WADM]: the annotation target is a SpecificResource whose source is the 3D model and whose selector identifies the annotated geometry.
The W3C Web Annotation Data Model defines selectors for two-dimensional and textual media only. Neither it nor the
Media Fragments URI 1.0 Recommendation defines a syntax for selecting points, lines, polygons, surface regions, or oriented bounding boxes on a 3D mesh. The IIIF Presentation API 4.0 (Release Candidate) introduces a PointSelector with x/y/z properties for a single point in a scene, but defines no line, surface, face, or box selector on a mesh.
This specification therefore defines a small family of selector types in the meshnotes: namespace. Each is a subtype of oa:Selector, which the W3C Web Annotation Data Model explicitly permits to be extended with new subclasses (see [WADM] §4.2 and the Web Annotation Vocabulary). Each selector carries a dcterms:conformsTo reference to this document, which is the conformant way for a consumer to discover the standard a selector follows ([WADM] §4.2.1).
Where an established standard exists, this specification reuses it rather than inventing grammar. Linear geometry — points, polylines and polygons — is encoded as Well-Known Text (WKT) per OGC Simple Feature Access / ISO 19125-1 [SFA], the same encoding the cultural-heritage and geospatial communities consume through OGC GeoSPARQL [GEO]. Two selector types — surface regions and oriented boxes — have no WKT equivalent (WKT cannot express a mesh-face selection, and has no rotation or oriented-volume primitive) and are therefore defined as parametric structures, while still expressing their embedded coordinates in WKT point notation for a single, consistent coordinate syntax.
| Prefix | IRI |
|---|---|
meshnotes: | https://meshnotes.org/ns/ |
dcterms: | http://purl.org/dc/terms/ |
geo: | http://www.opengis.net/ont/geosparql# |
xsd: | http://www.w3.org/2001/XMLSchema# |
oa: | http://www.w3.org/ns/oa# |
A document conforms to this specification when every meshnotes: selector it contains:
type values defined in §4;"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/";https://meshnotes.org/ns/context-v1.jsonld.The key words must, must not, should, and may are used as defined in RFC 2119.
Coordinates are expressed in the model's local coordinate frame as exported by MeshNotes, which is Z-up and right-handed. (MeshNotes works internally in a Y-up frame; coordinates are transformed to Z-up on export for interoperability with photogrammetry and archaeology tooling such as Agisoft Metashape, CloudCompare and Blender.) The up-axis is declared once, on the model description (modelSource, which each annotation's target.source references), via meshnotes:upAxis (value "Z"). The linear unit of all coordinates is declared there via meshnotes:unit (e.g. "m", "cm", "mm"); the unit is optional, and a consumer should not assume one when none is declared.
Coordinates and linear geometry are written in Well-Known Text [SFA]. Three-dimensional geometries carry the dimensionality flag Z after the type keyword; coordinate components within a position are separated by a single space, and positions are separated by commas:
POINT Z (x y z)
LINESTRING Z (x1 y1 z1, x2 y2 z2, ...)
POLYGON Z ((x1 y1 z1, x2 y2 z2, ..., x1 y1 z1))Per [SFA], a polygon's ring must be topologically closed: the first position is repeated as the last.
The primary geometry of a point, polyline or polygon selector is carried in one of two mutually exclusive forms, depending on whether the target model is georeferenced:
meshnotes:wkt, a plain WKT string in the model's local frame. It is deliberately not typed as geo:wktLiteral: under GeoSPARQL [GEO §8.5], a WKT literal with no explicit CRS URI is assumed to be CRS84 (geographic longitude/latitude), which a local model frame is not. Emitting local coordinates as a bare geo:wktLiteral would therefore assert a false geographic reference.meshnotes:crs (an OGC CRS URI, e.g. http://www.opengis.net/def/crs/EPSG/0/25832 for ETRS89 / UTM zone 32N), the selector instead carries geo:asWKT, a geo:wktLiteral whose value begins with the CRS URI in angle brackets, followed by a space and the WKT string [GEO §8.5]. Such a selector is a first-class GeoSPARQL geometry and can be ingested directly by GeoSPARQL-aware stores and CRM/CRMgeo place-geometry mappings.
A selector must carry exactly one of meshnotes:wkt or geo:asWKT. Note the axis-order difference between coordinate systems: a projected CRS such as EPSG:25832 orders coordinates easting (x), northing (y); CRS84 orders them longitude, latitude. Local model coordinates carry no such convention and are interpreted in the model frame.
Orientation (used by meshnotes:BoxSelector) is expressed as a unit quaternion, an ordered four-number list [x, y, z, w] following the convention used by glTF 2.0 node rotations (vector part first, scalar part last; identity is [0, 0, 0, 1]). Quaternions are used in preference to Euler angles because Euler angles are ambiguous without an explicit rotation order and are therefore not reliably interpretable by an independent consumer.
Each selector is a JSON object with a type and a dcterms:conformsTo, plus the geometry properties listed below.
A single point on the mesh surface, as a WKT POINT Z.
"selector": {
"type": "meshnotes:PointSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"meshnotes:wkt": "POINT Z (12.4 -3.15 8.02)"
}Georeferenced form (target declares meshnotes:crs):
"selector": {
"type": "meshnotes:PointSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"geo:asWKT": "<http://www.opengis.net/def/crs/EPSG/0/25832> POINT Z (412300.5 5512100.2 145.8)"
}An open polyline of two or more positions, in order, as a WKT LINESTRING Z.
"selector": {
"type": "meshnotes:PolylineSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"meshnotes:wkt": "LINESTRING Z (1.0 2.0 3.0, 1.5 2.2 3.1, 2.0 2.4 3.0)"
}A closed polygon of three or more distinct positions, as a WKT POLYGON Z with a single exterior ring. Per [SFA] the ring is closed by repeating the first position as the last.
"selector": {
"type": "meshnotes:PolygonSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"meshnotes:wkt": "POLYGON Z ((1.0 2.0 3.0, 4.0 2.0 3.0, 4.0 5.0 3.2, 1.0 2.0 3.0))"
}A painted region of the mesh surface, identified primarily by a representative point and surface normal, with the set of covered mesh faces recorded as a non-authoritative hint (see §5).
| Property | Type | Description |
|---|---|---|
meshnotes:centroid | WKT POINT Z string | A representative point within the region, in the local model frame. |
meshnotes:normal (optional) | WKT POINT Z string | The outward surface normal at the centroid, as a unit direction vector encoded in POINT Z coordinate notation. Reserved: emitted only by tools that capture surface orientation; consumers must tolerate its absence. |
meshnotes:faces | set of strings | Mesh face identifiers covered by the region. Hint only — valid solely against the exact mesh identified by the model integrity hash (§5). |
"selector": {
"type": "meshnotes:SurfaceSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"meshnotes:centroid": "POINT Z (4.1 0.2 9.7)",
"meshnotes:normal": "POINT Z (0.0 0.0 1.0)",
"meshnotes:faces": [ "0_1024", "0_1025", "0_1090" ]
}The embedded coordinates of a surface or box selector are always expressed in the local model frame, regardless of whether the target is georeferenced; these selectors describe object-relative geometry. A consumer needing them in a geographic CRS applies the model's own CRS transform.
An oriented bounding box: an axis-aligned box of the given size, centred at the given point, then rotated by the given quaternion.
| Property | Type | Description |
|---|---|---|
meshnotes:center | WKT POINT Z string | Box centre, in the local model frame. |
meshnotes:size | WKT POINT Z string | Full edge lengths along the box's local x, y, z axes, encoded in POINT Z coordinate notation. |
meshnotes:rotation | quaternion [x, y, z, w] | Unit quaternion, glTF convention (§3.4). Identity is [0, 0, 0, 1]. |
"selector": {
"type": "meshnotes:BoxSelector",
"dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
"meshnotes:center": "POINT Z (5.0 5.0 2.0)",
"meshnotes:size": "POINT Z (1.2 0.8 0.5)",
"meshnotes:rotation": [ 0.0, 0.0, 0.0, 1.0 ]
}
Mesh face identifiers (meshnotes:faces) are indices into a specific triangulation. Any operation that changes the triangulation — decimation, retopology, hole-filling, re-export — invalidates them. They are therefore recorded as a hint and must not be treated as authoritative unless the consumer can confirm it holds the identical mesh.
To make that confirmation possible, an annotation document should bind to its target model by a content hash, expressed on the model description (modelSource) as schema:sha256 over the canonical model file, alongside a persistent identifier (e.g. a DOI) for the model where one exists. The durable, mesh-independent part of a meshnotes:SurfaceSelector is its centroid (and normal where present); a consumer that does not hold the matching mesh can still locate the region approximately from those.
The term namespace https://meshnotes.org/ns/ is unversioned and append-only: identifiers, once published, keep their meaning permanently, and new terms are only ever added. This specification, its companion JSON-LD context, and the annotation JSON Schema are versioned and frozen: a breaking change is published at a new version path and the prior version remains resolvable indefinitely, so that files referencing it continue to validate.
geo:asWKT, the geo:wktLiteral datatype, and the CRS-URI prefix convention (§8.5).