Command list
Every oniyanma operation goes through a command. All five entry points — UI buttons, keyboard shortcuts, the ⌘K palette, the in-app AI console, and MCP — pass through these 125 without exception.
The argument tables below are generated by reading toolDefs() — the same value the app hands to the AI at runtime — from packages/app/src/command/registry.ts. Nothing here is copied by hand, so it never drifts from the implementation.
For how to call these, see window.oniyanma; for coordinate-system conventions, see the reference overview.
Quick reference
The 29 commands marked read-only also run on the read-only surface (surface: 'read'). A confirmation gate command inserts one dry run when called by a machine.
| Command | Mark | Summary |
|---|---|---|
| Display | ||
setMeasureMode | Switch measurement mode (off / distance=between two poi… | |
addMeasurePoint | Add one point to the current measurement (real coordina… | |
undoMeasurePoint | Undo the last measurement point (measurement points are… | |
getPickedPoint | Return the real coordinates (m) of the last point picke… | |
clearMeasure | Cancel the measurement in progress (clears every point … | |
setColorMode | Switch color mode (rgb / intensity / elevation / classi… | |
setDeviationSurface | Pick the design surface (TIN) the deviation heatmap com… | |
setDeviationRange | Color range (m) of the deviation heatmap | |
setPointSize | Set point size (px) | |
setEdl | Set EDL shading strength (0=off) | |
setGrid | Toggle the grid / coordinate axes | |
setBasemap | Toggle the basemap (GSI tiles, standard map) | |
getBasemapStatus | R | Basemap state |
setBudget | Set the point budget (upper bound on rendered points) | |
setBackend | Switch the render backend (webgl / webgpu) | |
| Camera / navigation | ||
home | Return to the overview (isometric) home view | |
lookAlong | View the whole dataset from a given direction | |
setNavMode | Switch navigation mode (orbit=rotate and zoom around a … | |
getCamera | R | Get the current camera position and target in real coor… |
setCameraReal | Place the camera in real coordinates (m) | |
saveView | Name and save the current camera position and target (p… | |
listViews | R | List the saved views |
gotoView | Move the camera to a saved view | |
deleteView | Delete a saved view | |
nameRegion | Name and save the current selection (or the box given a… | |
listRegions | R | List the named regions |
selectRegion | Recall a named region as the selection (pass an id from… | |
deleteRegion | Delete a named region | |
measureDistance | R | Return the distance between two real coordinates (m) (d… |
measureAngle | R | Return the angle at 3 points (the spatial angle between… |
measureHeight | R | Return the height difference between two points (dz is … |
measureVolume | R | Earth volume of a polygon (prism method) |
measureLineOffset | R | Return the perpendicular distance from a guideline (a→b… |
| Section | ||
setSection | Set the section (slab) | |
querySection | R | Return the dimensions (width m × height m) and point co… |
| Selection | ||
selectBox | Select points with an AABB in the aligned (scene) frame | |
selectAll | Select everything loaded (uses the whole aligned-frame … | |
clearSelection | Clear the selection | |
zoomToSelection | Move the camera so the current selection fits on screen… | |
| Non-destructive editing | ||
hideSelection | C | Hide the selected points (removed from the display only… |
deleteSelection | C | Delete the selected points (removed from the deliverabl… |
reclassifySelection | C | Change the classification of the selected points (the i… |
colorSelection | C | Override the color of the selected points ('#rrggbb' or… |
undo | Undo one operation (point edits, TIN, color mode, data … | |
redo | Redo an operation | |
clearEdits | C | Clear every edit (during collaboration this covers ever… |
| Data | ||
loadData | Load a point cloud (replacing the current one) | |
addData | Load an additional point cloud (overlaid on the current… | |
addAlignedSource | Register two point clouds with ICP (server-side job ali… | |
removeSource | Remove a source (by the id from listSources / getState) | |
setSourceVisible | Show or hide a source | |
setSourceObservedAt | Record when a source was observed (when it was captured… | |
loadSplat | Load 3DGS (splats), replacing the current one (there is… | |
removeSplat | Clear the 3DGS (splat) display and go back to the point… | |
addSurface | Load J-LandXML (TIN design surface), DXF (3DFACE only),… | |
setSurfaceVisible | Show or hide a reference surface (TIN) (see getState().… | |
removeSurface | Remove a reference surface (TIN) (see getState().surfac… | |
queryDesignDeviation | R | Aggregate the vertical deviation from a design surface … |
createDesignDeviationFindings | Automatically raise findings where the deviation from t… | |
| Photo sets | ||
addPhotoSet | Load a photo set (one capture session = one manifest) (… | |
listPhotos | List photos | |
setPhotoCameras | Show or hide the camera positions (where each photo was… | |
getPhoto | Return the details of one photo (full-size / thumbnail … | |
rotatePhoto | Fix a photo orientation by hand (2026-09-21) | |
| Camera pose sets | ||
addCameraPoses | Load a camera pose set (design 0004 M2) | |
listCameraPoseSets | List the camera pose sets that are loaded (design 0004 … | |
setPlacement | Create or update the placement of a pose set (design 00… | |
lookThroughPhoto | Put the 3D camera at a photo's viewpoint (design 0004 M… | |
| 2D→3D projection | ||
projectPoint | R | Project one point on a photo (pixel coordinates) into r… |
projectPoint | R | Project one point on a photo (pixel coordinates) into r… |
projectPoints | R | Project several points on a photo into real coordinates… |
| Detection import | ||
previewDetectionImport | Validate and project the same input importDetections ta… | |
importDetections | Bulk-import the output of an external damage-detection … | |
| Multi-view merge | ||
queryMergeCandidates | R | Group findings (per-photo detections) whose 3D position… |
mergeFindings | C | Merge several findings (per-photo detections) into one,… |
unmergeFinding | Undo a merge ($mergedInto) and return the finding to li… | |
confirmFinding | Confirm an AI detection (a finding created by importDet… | |
rejectFinding | Reject an AI detection (a finding created by importDete… | |
| Query | ||
queryElevation | R | Get the elevation (real Z, m) distribution: {min,max,me… |
queryClasses | R | Get the classification histogram: {total, counts:{class… |
queryLayers | R | Per-layer (source) information: [{id,name,visible,resid… |
querySelection | R | Get the point count and aligned-frame AABB of the curre… |
queryBoxCount | R | Get the number of points inside an aligned-frame AABB (… |
queryCrs | R | Get the coordinate reference system and coordinate fram… |
setAlignYaw | C | Manually adjust the alignment angle (yaw) (degrees, add… |
| Export | ||
exportSelection | Export the selected points (real coordinates m, class, … | |
exportCloud | Export the whole point cloud with edits applied (not li… | |
cropSelectionToCopc | Crop the current selection into a standalone COPC (serv… | |
convertToCopc | Convert raw LAS/LAZ to COPC (the server-side job cropTo… | |
classifyGroundToSource | Ground classification (the server-side job classifyGrou… | |
removeOutliersToSource | Noise point removal (the server-side job removeOutliers… | |
decimateToSource | Point decimation (the server-side job decimate, PDAL fi… | |
removeDuplicatesToSource | Duplicate point removal (the server-side job removeDupl… | |
colorizeByElevationToSource | Colorize by mapping elevation (Z) to color (the server-… | |
generateTinSurface | TIN generation plus LandXML conversion (the server-side… | |
generateContoursJob | Contour generation (the server-side job generateContour… | |
generateDtmJob | DTM (GeoTIFF) generation (the server-side job generateD… | |
generateDsmJob | DSM (GeoTIFF) generation (the server-side job generateD… | |
generateMeshJob | TIN / mesh generation (the server-side job generateMesh) | |
| Findings | ||
defineFindingType | Create or update a finding type (the item definitions o… | |
listFindingTypes | R | List the finding types: [{id,label,standard,entryId,ver… |
getFindingTypeSchema | R | Get a finding type as a JSON Schema (the shape you can … |
createFinding | Raise a finding (a draft; the client does not see it un… | |
updateFinding | Update part of a finding (pass only the fields you want… | |
queryFindings | R | Filter findings by type (typeId), by the detector's raw… |
listFindings | R | List findings |
getFinding | R | Details of one finding |
publishFinding | Publish a finding (fixed as the version the client sees | |
unpublishFinding | Withdraw a finding from publication (back to draft | |
deleteFinding | C | Withdraw a finding (the record remains but it drops out… |
restoreFinding | Restore a withdrawn finding (edits made while it was wi… | |
commentFinding | Reply to a finding (a thread) | |
editComment | Edit the body of a reply (id is the reply itself; use u… | |
listComments | R | Return the replies to a finding, oldest first: [{id,tex… |
exportFindings | Export findings (by default only the published version,… | |
exportFindingsForm23 | Export findings to CSV in the item order of the bridge_… | |
| Batches | ||
listBatches | R | List batches (one continuous operation = a human's run … |
revertBatch | C | Revert a whole batch (one continuous operation) |
acceptBatch | Accept a status:'proposed' batch (an AI proposal a huma… | |
queryBatchImpact | R | Return the number of points a batch touches, the kinds … |
getBatch | R | Details of one batch (intent in full) |
| Persistence | ||
saveEdits | Download the current non-destructive edits as a sidecar… | |
| Project folders | ||
createFolder | Create a folder to classify data within the Project (de… | |
moveFolder | Move a folder itself into another folder (design 0024 M… | |
moveAssetToFolder | Change an Asset's folder (by the ids from getState / th… | |
deleteFolder | C | Delete a folder |
R = read-only / C = confirmation gate
Display
Changes only how things look. Touches neither the data nor the edit log, so these are outside Undo.
setMeasureMode
Switch measurement mode (off / distance=between two points / path=polyline / area=horizontally projected area / angle=angle (spatial angle at 3 points) / height=height (rise and grade) / volume=earth volume / guideline=offset from a guideline). Any points placed so far are cleared.
| Argument | Type | Required | Constraint |
|---|---|---|---|
mode | string | ✔ | 'off' | 'distance' | 'path' | 'area' | 'angle' | 'height' | 'volume' | 'guideline' |
addMeasurePoint
Add one point to the current measurement (real coordinates, m). The given coordinate is measured as-is without snapping to the point cloud. Requires setMeasureMode (nothing is added while off).
| Argument | Type | Required | Constraint |
|---|---|---|---|
point | number[] | ✔ | 3 items |
undoMeasurePoint
Undo the last measurement point (measurement points are not in the Undo history, so undo does not bring them back).
No arguments.
getPickedPoint
Return the real coordinates (m) of the last point picked on screen (recorded for any click that hit, regardless of measure mode). tolerance is the width (m) within which the returned point lies — the tolerance circle is decided in screen px, so it is wider the further away you click. point is null if nothing has been hit yet. It can be passed straight to seesPoint of listPhotos.
No arguments.
clearMeasure
Cancel the measurement in progress (clears every point placed).
No arguments.
setColorMode
Switch color mode (rgb / intensity / elevation / classification=classification, requires classified data (unclassified data renders in a single color; check with queryClasses, and classifyGroundToSource can create ground/non-ground) / deviation=design deviation heatmap, requires setDeviationSurface).
| Argument | Type | Required | Constraint |
|---|---|---|---|
mode | string | ✔ | 'rgb' | 'intensity' | 'elevation' | 'classification' | 'deviation' |
setDeviationSurface
Pick the design surface (TIN) the deviation heatmap compares against. Omit surfaceId to clear it (all points return to grey). See getState().surfaces for ids. Displaying it also requires setColorMode(mode:'deviation').
| Argument | Type | Required | Constraint |
|---|---|---|---|
surfaceId | number | — |
setDeviationRange
Color range (m) of the deviation heatmap. The color saturates where |deviation| reaches this value (default 0.1 m, must be greater than 0).
| Argument | Type | Required | Constraint |
|---|---|---|---|
range | number | ✔ | 0.001 – ∞ |
setPointSize
Set point size (px).
| Argument | Type | Required | Constraint |
|---|---|---|---|
px | number | ✔ | 0.5 – 8 |
setEdl
Set EDL shading strength (0=off).
| Argument | Type | Required | Constraint |
|---|---|---|---|
strength | number | ✔ | 0 – 2 |
setGrid
Toggle the grid / coordinate axes.
| Argument | Type | Required | Constraint |
|---|---|---|---|
on | boolean | ✔ | — |
setBasemap
Toggle the basemap (GSI tiles, standard map). It has no effect outside the supported CRS (JGD2011 plane rectangular coordinate systems, EPSG:6669-6687). Check the result with getBasemapStatus.
| Argument | Type | Required | Constraint |
|---|---|---|---|
on | boolean | ✔ | — |
getBasemapStatus
read-only
Basemap state. 'on'|'off'|'no-data'(no data loaded)|'unsupported-crs'(CRS not supported)|'unknown-axis-order'(the file does not declare its axis order and we do not guess).
No arguments.
setBudget
Set the point budget (upper bound on rendered points).
| Argument | Type | Required | Constraint |
|---|---|---|---|
points | number | ✔ | 100000 – ∞ |
setBackend
Switch the render backend (webgl / webgpu).
| Argument | Type | Required | Constraint |
|---|---|---|---|
kind | string | ✔ | 'webgl' | 'webgpu' |
Camera / navigation
Camera placement and movement mode. All coordinates are passed as real coordinates (m).
home
Return to the overview (isometric) home view.
No arguments.
lookAlong
View the whole dataset from a given direction. axis is where the camera is placed, i.e. which side you look from ([0,0,1]=straight down from above, [0,0,-1]=straight up from below, [1,0,0]=from +X, [0,1,0]=from +Y). Zoom is preserved.
| Argument | Type | Required | Constraint |
|---|---|---|---|
axis | number[] | ✔ | 3 items |
setNavMode
Switch navigation mode (orbit=rotate and zoom around a target / walk=free fly: left-drag to look, wheel to move forward and back, WASD to move, unconstrained).
| Argument | Type | Required | Constraint |
|---|---|---|---|
mode | string | ✔ | 'orbit' | 'walk' |
getCamera
read-only
Get the current camera position and target in real coordinates (m).
No arguments.
setCameraReal
Place the camera in real coordinates (m). pos=camera position, target=look-at point. Switches to orbit.
| Argument | Type | Required | Constraint |
|---|---|---|---|
pos | number[] | ✔ | 3 items |
target | number[] | ✔ | 3 items |
saveView
Name and save the current camera position and target (pass pos/target to save that position instead). The starting point for 'take everyone to this view'.
| Argument | Type | Required | Constraint |
|---|---|---|---|
name | string | ✔ | — |
pos | number[] | 3 items | |
target | number[] | 3 items |
listViews
read-only
List the saved views.
No arguments.
gotoView
Move the camera to a saved view.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
deleteView
Delete a saved view.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
nameRegion
Name and save the current selection (or the box given as min/max). selectRegion(id) then recalls it by name (semantic grounding).
| Argument | Type | Required | Constraint |
|---|---|---|---|
name | string | ✔ | — |
min | number[] | 3 items | |
max | number[] | 3 items |
listRegions
read-only
List the named regions.
No arguments.
selectRegion
Recall a named region as the selection (pass an id from listRegions).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
deleteRegion
Delete a named region.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
measureDistance
read-only
Return the distance between two real coordinates (m) (distance=straight line, horizontal, vertical). The display is unchanged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
a | number[] | ✔ | 3 items |
b | number[] | ✔ | 3 items |
measureAngle
read-only
Return the angle at 3 points (the spatial angle between the two edges meeting at vertex; deg / rad). The display is unchanged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
vertex | number[] | ✔ | 3 items |
a | number[] | ✔ | 3 items |
b | number[] | ✔ | 3 items |
measureHeight
read-only
Return the height difference between two points (dz is signed; the grade comes back as gradePercent and as a 1:n gradeRatio). The display is unchanged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
a | number[] | ✔ | 3 items |
b | number[] | ✔ | 3 items |
measureVolume
read-only
Earth volume of a polygon (prism method). polygon is an array of real coordinates (m); base is 'mean' (default, the mean elevation of the given points) or a numeric elevation. cut/fill are returned separately, and cases such as concave polygons put the reason in warnings.
| Argument | Type | Required | Constraint |
|---|---|---|---|
polygon | array[] | ✔ | — |
base | string | — | |
baseZ | number | — |
measureLineOffset
read-only
Return the perpendicular distance from a guideline (a→b) to point p (offset, unsigned) and the distance along the line from a (station; negative before a, greater than the segment length past b). The display is unchanged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
a | number[] | ✔ | 3 items |
b | number[] | ✔ | 3 items |
p | number[] | ✔ | 3 items |
Section
Clips the display to an axis-aligned slab in the aligned frame. Points are not deleted — only hidden from view.
setSection
Set the section (slab). axis 0=X 1=Y 2=Z; pos/thick are 0..1 (relative to the aligned frame). on=false clears it.
| Argument | Type | Required | Constraint |
|---|---|---|---|
on | boolean | ✔ | — |
axis | number | 0 | 1 | 2 | |
pos | number | 0 – 1 | |
thick | number | 0 – 1 |
querySection
read-only
Return the dimensions (width m × height m) and point count of a given section (slab). Same arguments as setSection (axis/pos/thick). The display is unchanged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
axis | number | 0 | 1 | 2 | |
pos | number | 0 – 1 | |
thick | number | 0 – 1 |
Selection
A selection is not a set of point IDs but a predicate (a condition such as "points inside this shape"). So the same points stay selected even as LOD drops and reloads points, or as the camera moves.
selectBox
Select points with an AABB in the aligned (scene) frame. min/max must be inside getState().alignedBounds.
| Argument | Type | Required | Constraint |
|---|---|---|---|
min | number[] | ✔ | 3 items |
max | number[] | ✔ | 3 items |
selectAll
Select everything loaded (uses the whole aligned-frame AABB as the predicate).
No arguments.
clearSelection
Clear the selection.
No arguments.
zoomToSelection
Move the camera so the current selection fits on screen (returns ok:false if there is no selection).
No arguments.
Non-destructive editing
Applies to the current selection. The source .copc.laz is never rewritten. The issuing actor (human / ai / api) is recorded in the Command log, and Undo works per actor.
hideSelection
confirmation gate
Hide the selected points (removed from the display only; they remain in exports and aggregates. Non-destructive, and the issuer is recorded as AI).
| Argument | Type | Required | Constraint |
|---|---|---|---|
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
deleteSelection
confirmation gate
Delete the selected points (removed from the deliverable, i.e. excluded from exports and aggregates. The original COPC is untouched and this is undoable. Non-destructive, and the issuer is recorded as AI).
| Argument | Type | Required | Constraint |
|---|---|---|---|
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
reclassifySelection
confirmation gate
Change the classification of the selected points (the issuer is recorded as AI).
| Argument | Type | Required | Constraint |
|---|---|---|---|
class | number | ✔ | 0 – 255 |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
colorSelection
confirmation gate
Override the color of the selected points ('#rrggbb' or a 0xRRGGBB number).
| Argument | Type | Required | Constraint |
|---|---|---|---|
color | string | ✔ | — |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
undo
Undo one operation (point edits, TIN, color mode, data loading, and so on).
No arguments.
redo
Redo an operation.
No arguments.
clearEdits
confirmation gate
Clear every edit (during collaboration this covers every participant's edits).
| Argument | Type | Required | Constraint |
|---|---|---|---|
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
Data
Loading, overlaying, and toggling point cloud sources and reference surfaces (TIN).
loadData
Load a point cloud (replacing the current one). COPC plus raw LAS/LAZ are supported. A large raw LAS automatically becomes a decimated preview (measurement and findings are then unavailable). Only a large compressed LAZ that cannot be decimated returns confirm-required.
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
force | boolean | Read every point without decimating (a huge file can crash the tab) |
addData
Load an additional point cloud (overlaid on the current one). COPC plus raw LAS/LAZ are supported. A large raw LAS automatically becomes a decimated preview (measurement and findings are then unavailable). Only a large compressed LAZ that cannot be decimated returns confirm-required.
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
force | boolean | Read every point without decimating (a huge file can crash the tab) |
addAlignedSource
Register two point clouds with ICP (server-side job alignToReference) and then load the result. inputUri is aligned to referenceUri (the URL of the first source when omitted), written to outputUri, and by default added to the scene. The job can take tens of seconds or more (depending on point count).
| Argument | Type | Required | Constraint |
|---|---|---|---|
inputUri | string | ✔ | uri of the point cloud to align and add (must be registered in this Project's Asset ledger) |
outputUri | string | Output uri for the aligned result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
referenceUri | string | uri of the reference point cloud (must be registered in the ledger). When omitted, the URL of the current first source is used | |
maxIterations | number | Maximum ICP iterations (the job-side default when omitted) | |
load | boolean | Default true. False runs the job without adding the result to the scene |
removeSource
Remove a source (by the id from listSources / getState).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | number | ✔ | — |
setSourceVisible
Show or hide a source.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | number | ✔ | — |
visible | boolean | ✔ | — |
setSourceObservedAt
Record when a source was observed (when it was captured; ISO8601). Recording only — neither the display nor any computation changes. This is not sys.createdAt (when it was recorded). Omitting observedAt resets it to unknown (the same convention as setDeviationSurface).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | number | ✔ | — |
observedAt | string | ISO8601 (e.g. 2026-07-14T00:00:00.000Z). Omit to reset to unknown |
loadSplat
Load 3DGS (splats), replacing the current one (there is no add equivalent). On mobile, exceeding the size threshold returns confirm-required.
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
force | boolean | Override the size threshold gate |
removeSplat
Clear the 3DGS (splat) display and go back to the point cloud.
No arguments.
addSurface
Load J-LandXML (TIN design surface), DXF (3DFACE only), SHP (MultiPatch TriangleStrip/Fan only) or IFC and overlay it on the point cloud (a point cloud must be loaded). The kind is decided by the URL extension (.dxf/.shp/.ifc).
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
setSurfaceVisible
Show or hide a reference surface (TIN) (see getState().surfaces for ids).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | number | ✔ | — |
visible | boolean | ✔ | — |
removeSurface
Remove a reference surface (TIN) (see getState().surfaces for ids).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | number | ✔ | — |
queryDesignDeviation
read-only
Aggregate the vertical deviation from a design surface (TIN) (the display is unchanged). dz=measured Z − design Z (signed, m). Points outside the TIN are excluded. clusters is sorted by descending |dz| and capped at maxClusters (default 20). The result is an estimate, and basis (what was scanned) / axis (how distance is taken) / coverage (how much of the area the design surface covered) / lodRatio (the share of all points that are resident) describe its nature.
| Argument | Type | Required | Constraint |
|---|---|---|---|
surfaceId | number | ✔ | — |
thresholdM | number | ✔ | — |
clusterSizeM | number | — | |
maxClusters | number | — |
createDesignDeviationFindings
Automatically raise findings where the deviation from the design surface is large (using the clusters from queryDesignDeviation). Every location is type-checked up front, and if a single one fails the type, none are created. fields are the base values shared by all findings; give valueField to write the deviation (m, signed) into that field. Each finding freezes into $provenance that it is an estimate measured vertically against an LOD sample (so it is reviewable).
| Argument | Type | Required | Constraint |
|---|---|---|---|
surfaceId | number | ✔ | — |
thresholdM | number | ✔ | — |
typeId | string | ✔ | — |
fields | object | ✔ | — |
valueField | string | — | |
clusterSizeM | number | — | |
maxFindings | number | — |
Photo sets
Loaded as one manifest per shoot, not photo by photo (design 0004 M1). Usable for browsing, viewing, and filing findings even before camera poses exist (a superset of option A). Not marked readonly — exposing a photo listing to a read-only token is a bigger surface than point cloud coordinates, an open question from design 0004.
addPhotoSet
Load a photo set (one capture session = one manifest) (design 0004 M1). Usable for browsing and raising findings even without camera poses.
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
label | string | — |
listPhotos
List photos. setId narrows the set and limit caps the count. Pass real coordinates [x,y,z] (m) as seesPoint to get back only the photos whose field of view contains that point, nearest first, each carrying projection (pixel u,v and the size of that pixel space, distance from the camera, metersPerPixel, and the placement rms with its pixel equivalent). Only the field of view is checked — occlusion is not, so a point behind a girder still comes back if the direction lines up (these are candidates, not photos the point is visible in). Pass the positional uncertainty (m) of the point as seesPointTolerance and each photo also reports it in pixels (uncertaintyPixels) — at close range an error of a few metres points at a different member, so do not read the result as "that member is in this photo" without looking at it and at metersPerPixel. Photos without a pose or placement cannot be judged, so they are not candidates and their counts appear in seesPoint.skipped (they are not silently dropped to zero).
| Argument | Type | Required | Constraint |
|---|---|---|---|
setId | string | — | |
limit | number | — | |
seesPoint | number[] | 3 items | |
seesPointTolerance | number | — |
setPhotoCameras
Show or hide the camera positions (where each photo was taken) in 3D. Off by default — with dozens of photos the markers outnumber the point cloud. Candidates for a point picked in 3D are highlighted regardless of this toggle. The list is built from the poses present at the moment you switch it on, so switch it again after loading more photos or poses (changes to the placement are followed automatically). The returned count is how many were actually shown. A count of 0 has more than one cause, so skipped breaks it down (noPose / noIntrinsics / noPlacement / unusablePlacement / ambiguousId) — ambiguousId means conflicting poses match the same photo (duplicate pose sets or a name collision).
| Argument | Type | Required | Constraint |
|---|---|---|---|
on | boolean | ✔ | — |
getPhoto
Return the details of one photo (full-size / thumbnail URLs). id has the shape listPhotos returns.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
rotatePhoto
Fix a photo orientation by hand (2026-09-21). Pixels are not rotated — only the viewing angle is recorded, so crop rects, detection bboxes and camera intrinsics all stay put. Pass photo (an id from listPhotos) for one photo, or photoSet (a setKey) for the whole set. Omitting rotation advances 90 degrees clockwise (four presses come back around). clear: true returns to what the producer declared (displayRotation in the manifest). A hand-set value wins over the declaration.
| Argument | Type | Required | Constraint |
|---|---|---|---|
photo | string | To fix one photo. The id listPhotos returns | |
photoSet | string | To fix a whole set. The setKey getPhoto returns (ADR 0021) | |
rotation | number | 0 | 90 | 180 | 270 / Clockwise degrees. Omitting it advances 90 from the current value | |
clear | boolean | Drop the hand-set value and return to what the producer declared |
Camera pose sets
Reads COLMAP sparse/0 (cameras.bin / images.bin) and aligns the 3D camera to a photo's viewpoint (design 0004 M2). While placement stays unknown, lookThroughPhoto fails with precondition-failed — not something confirming would fix, but genuinely impossible until alignment is done (unlike confirm-required).
addCameraPoses
Load a camera pose set (design 0004 M2). Without a placement (setPlacement) it cannot be used for photo viewpoints. format is stated by the caller (default colmap = the URL of a sparse/0 directory). It is not guessed from the URL or file name because reading another format as COLMAP does not fail — it produces poses that are silently wrong.
| Argument | Type | Required | Constraint |
|---|---|---|---|
url | string | ✔ | — |
label | string | — | |
format | string | 'colmap' / Default colmap. An unsupported format is refused with invalid-argument (it is never silently read as colmap) |
listCameraPoseSets
List the camera pose sets that are loaded (design 0004 M2). id can be passed straight to the poseSet of setPlacement. placement is the current alignment (null when unset; kind:"unknown" means the heading was never determined). sessions are the capture session names carried in the pose names — the same strings as session in oohashi's placement-seed.json. cameras is how many camera positions land inside the point cloud bbox (horizontal, 150 m margin); offTarget true means a majority are outside (the photo viewpoint flies into empty space). No signed url is returned — use id to refer to the same set.
No arguments.
setPlacement
Create or update the placement of a pose set (design 0004 M2/M3). Either give transform directly (manual or a known similarity transform) or pass correspondences (SfM↔real coordinate pairs, 3 or more) to least-squares fit from GCPs. An existing assignment for the same poseSet is updated. When it can be counted, cameras comes back: inside/total is how many camera positions land inside the point cloud bbox (horizontal, 150 m margin), offTarget says a majority did not, and nearestDistanceM is how far the nearest camera is from the edge of the bbox (m). Nothing is blocked, but going on with 0/42 means the photo viewpoint flies into empty space.
| Argument | Type | Required | Constraint |
|---|---|---|---|
poseSet | string | ✔ | id of the CameraPoseSet (the setId returned by addCameraPoses) |
transform | object | {kind:'unknown'} or {kind:'similarity', s, q:[w,x,y,z], t:[x,y,z], method:'gcp'|'icp'|'manual', rms?}. Cannot be used together with correspondences | |
correspondences | object[] | An array of {sfm:[x,y,z], real:[x,y,z]} (3 or more pairs; the SfM side must not be collinear). Passing it fits automatically with method:gcp |
lookThroughPhoto
Put the 3D camera at a photo's viewpoint (design 0004 M2). The target (the orbit pivot) is re-derived from the view after the move, i.e. the distance at which the optical axis hits the point cloud. The camera is then placed back along the optical axis at distanceScale times that distance (default 2), because standing exactly at the photo's viewpoint fills the frame with the subject and hides the whole. 1 means the photo's viewpoint itself, and 1000 is the upper bound (beyond it the photo's footprint is under a pixel and nothing is visible). It cannot run while the placement is unset or unknown (precondition-failed).
| Argument | Type | Required | Constraint |
|---|---|---|---|
photoId | string | ✔ | — |
distanceScale | number | — |
2D→3D projection
Projects a pixel on a photo to real coordinates (m) (design 0004 M4). On sparse surfaces the ray may not intersect, and a detection that fails to project returns ok:false rather than throwing. While placement stays unknown this is precondition-failed — unlike confirm-required, no confirmation makes it runnable until alignment is done. What comes back is a position, not a shape (fine features like cracks are finer than the point cloud's resolution).
projectPoint
read-only
Project one point on a photo (pixel coordinates) into real coordinates (m) (design 0004 M4). Where the point cloud is sparse or missing, the ray does not intersect and the result comes back as a detection that could not be projected, with ok:false (not an exception). An unset or unknown placement gives precondition-failed. Position comes out but shape does not — thin features such as cracks are finer than the point cloud resolution, so what comes back is a single point. When imageWidth/imageHeight are given, u/v are treated as being in that pixel space (the resolution of whatever image the caller actually picked coordinates on, e.g. a photo tile in design 0020 M2a) and are scaled proportionally, preserving aspect ratio, to the camera intrinsics resolution before projecting (the same conversion importDetections uses). Omitted, u/v are treated as already being in the camera intrinsics resolution, as before.
| Argument | Type | Required | Constraint |
|---|---|---|---|
photoId | string | ✔ | — |
u | number | ✔ | — |
v | number | ✔ | — |
imageWidth | number | — | |
imageHeight | number | — |
projectPoint
read-only
Project one point on a photo (pixel coordinates) into real coordinates (m) (design 0004 M4). Where the point cloud is sparse or missing, the ray does not intersect and the result comes back as a detection that could not be projected, with ok:false (not an exception). An unset or unknown placement gives precondition-failed. Position comes out but shape does not — thin features such as cracks are finer than the point cloud resolution, so what comes back is a single point. When imageWidth/imageHeight are given, u/v are treated as being in that pixel space (the resolution of whatever image the caller actually picked coordinates on, e.g. a photo tile in design 0020 M2a) and are scaled proportionally, preserving aspect ratio, to the camera intrinsics resolution before projecting (the same conversion importDetections uses). Omitted, u/v are treated as already being in the camera intrinsics resolution, as before.
| Argument | Type | Required | Constraint |
|---|---|---|---|
photoId | string | ✔ | — |
u | number | ✔ | — |
v | number | ✔ | — |
imageWidth | number | — | |
imageHeight | number | — |
projectPoints
read-only
Project several points on a photo into real coordinates at once (design 0004 M4). Each point comes back in the same shape as projectPoint. Batching the rays into a single traversal is not implemented yet (correctness was settled first, and the performance work is recorded as a known issue in docs/design/0004).
| Argument | Type | Required | Constraint |
|---|---|---|---|
photoId | string | ✔ | — |
points | object[] | ✔ | — |
Detection import
Bulk-imports the output of an external damage-detection AI (bbox / polygon / confidence) as draft Findings (E2). Every item is type-checked and its photo pose is confirmed up front; if even one fails, none are created. The import is grouped into a single batch (kind:'import'), revertible all at once with revertBatch. Damage categories are carried as typeId/fields against the finding type definition (ADR 0010), not baked into this schema.
previewDetectionImport
Validate and project the same input importDetections takes, before handing it over, and return the breakdown (design 0020 "importing external detections"). Nothing is created — no findings, no batch; what comes back is the count (total), how many could not be projected (noIntersection), photo ids that have no camera pose (unknownPhotoIds) and photo ids that cannot be resolved to an actual photo (unresolvedPhotoIds). Validation goes through the same function as importDetections, so a malformed record stops here with the same exception (i.e. you can confirm up front that it would stop without creating anything). Only missing camera poses are collected instead of stopping at the first one — so a person can fix every unknown photo id. When unknownPhotoIds is non-empty, importDetections fails for the whole batch (importable:false). The id lists are capped at the first 50 entries and the counts are returned separately. Projection casts a ray into the point cloud per detection, so calling importDetections afterwards repeats the same computation. noIntersection is a snapshot of the point cloud at that moment — it can differ at import time if LOD streaming or visibility changes (it is information, not a gate; the $pin values and counts that end up on record are the ones importDetections returns).
| Argument | Type | Required | Constraint |
|---|---|---|---|
schemaVersion | string | '1.0' | |
source | object | — | |
intent | string | — | |
detections | object[] | ✔ | — |
importDetections
Bulk-import the output of an external damage-detection AI as draft Findings (a continuation of design 0004; the E2 detection import schema). Every record is type-checked and its photo pose verified up front, and if a single one fails, none are created (the same discipline as createDesignDeviationFindings). The import is grouped into one batch (kind:'import') so it can be reverted wholesale with revertBatch. Each detection gives its representative point on the image as bbox (COCO convention [x,y,width,height], absolute px, origin top-left), polygon (a single ring) or projectionPoint, and is projected into real coordinates using the photo's camera pose (position comes out but shape does not — it is always a single point). imageWidth/imageHeight is the resolution of the image the detector ran inference on, and is scaled proportionally, preserving aspect ratio, to the resolution of the camera intrinsics in the camera pose set (COLMAP) — the resolution registered by addCameraPoses is the reference, not that of the photo asset. Detections inferred on cropped, letterboxed, EXIF-rotated or undistorted images are out of scope in v1 (proportional scaling would silently shift the coordinates). The damage category is decided by typeId/fields and is not baked into this schema. confidence is held as null when absent (never filled in with 1.0). photoId and bbox/polygon/projectionPoint are stored on the Finding as $sourcePhoto/$sourceBbox (so the triage UI can crop the photo), kept in the pixel space the caller passed, separately from the internal conversion used for $pin.
| Argument | Type | Required | Constraint |
|---|---|---|---|
schemaVersion | string | '1.0' | |
source | object | — | |
intent | string | — | |
detections | object[] | ✔ | — |
Multi-view merge
Groups per-photo detections (findings that carry $pin) by 3D proximity, merged into one after human review (E2). Automatic grouping only proposes candidates — confirming is the caller's responsibility via a separate mergeFindings call. A merge is not a deletion, only a $mergedInto marker, so it can be undone individually with unmergeFinding.
queryMergeCandidates
read-only
Group findings (per-photo detections) whose 3D positions (real coordinates, m) are close, as candidates for the same damage (E2 'multi-view fusion'). Read-only — neither the display nor the data changes; confirming a merge is a separate call to mergeFindings. batchId/typeId narrow the target (all findings when unspecified). Findings without a $pin (detections that could not be projected) are excluded.
| Argument | Type | Required | Constraint |
|---|---|---|---|
radiusM | number | ✔ | The distance (m) at which two detections count as the same damage. Transitively connected by single linkage |
batchId | string | — | |
typeId | string | — |
mergeFindings
confirmation gate
Merge several findings (per-photo detections) into one, as 'the same real-world damage' (intended to take a group from queryMergeCandidates). Every finding except the survivor (the highest $confidence when primaryId is omitted; ties take the first) is stamped with $mergedInto and drops out of listings and reports (nothing is deleted — unmergeFinding restores it). The survivor's fields are left untouched: automatically merging values risks 'the numbers in the report silently changing' (fix them separately with updateFinding if needed).
| Argument | Type | Required | Constraint |
|---|---|---|---|
ids | string[] | ✔ | — |
primaryId | string | — | |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
unmergeFinding
Undo a merge ($mergedInto) and return the finding to listings and reports. Does nothing if it was not merged.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
confirmFinding
Confirm an AI detection (a finding created by importDetections) as accepted in review (review for the E2 detection import). The values themselves are unchanged (correct fields separately with updateFinding). Cannot be used on replies or merged findings. Callable only by a human issuer (if an AI could accept its own detections, review would stop meaning anything — the same reason as acceptBatch).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
rejectFinding
Reject an AI detection (a finding created by importDetections) in review (this is not deletion — it drops out of listings and merge candidates but the record remains, and restoreFinding will not bring it back; undo it by fixing review with updateFinding). To withdraw a human finding use deleteFinding instead (deletion and rejection are structurally different). Cannot be used on replies or merged findings. Callable only by a human issuer (consistency with confirmFinding; if first-pass rejection by AI is ever allowed, only this is relaxed).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
Query
Queries the scene for numbers. Unless noted otherwise, counts are resident-based (the LOD sample currently on screen), not a full scan. All of these are on the read-only surface.
queryElevation
read-only
Get the elevation (real Z, m) distribution: {min,max,mean,count,bins[]}. bins is the number of histogram buckets (default 16).
| Argument | Type | Required | Constraint |
|---|---|---|---|
bins | number | 2 – 128 |
queryClasses
read-only
Get the classification histogram: {total, counts:{class:count}}. Reflects classification overrides from edits.
No arguments.
queryLayers
read-only
Per-layer (source) information: [{id,name,visible,residentPoints,alignedBounds[6]}] (bounds are in the aligned frame).
No arguments.
querySelection
read-only
Get the point count and aligned-frame AABB of the current selection: {count, alignedBounds[6]|null}.
No arguments.
queryBoxCount
read-only
Get the number of points inside an aligned-frame AABB (min/max must be inside alignedBounds): {count}.
| Argument | Type | Required | Constraint |
|---|---|---|---|
min | number[] | ✔ | 3 items |
max | number[] | ✔ | 3 items |
queryCrs
read-only
Get the coordinate reference system and coordinate frame (EPSG / axis order=east-north|north-east, omitted when the file does not declare it / vertical datum=orthometric|ellipsoidal / offset and alignYaw). For checking what measurements and exports are relative to. No reprojection is performed.
No arguments.
setAlignYaw
confirmation gate
Manually adjust the alignment angle (yaw) (degrees, added to the current value). A display-only rotation — real coordinates (m) do not change. Because every source is reloaded, existing edits, selections and reference surfaces are lost (visibility is carried over).
| Argument | Type | Required | Constraint |
|---|---|---|---|
deltaDeg | number | ✔ | — |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
Export
Triggers a browser download while also putting the content in the return value — an AI can't see the file dialog, so it can't confirm the result unless it comes back in the response.
exportSelection
Export the selected points (real coordinates m, class, RGB). Triggers a file download and returns a summary. format='csv'(default)|'geojson'. resident=based on the sample currently displayed. Deleted points are excluded and counted in excludedDeleted.
| Argument | Type | Required | Constraint |
|---|---|---|---|
format | string | 'csv' | 'geojson' |
exportCloud
Export the whole point cloud with edits applied (not limited to the selection — the entire octree of every visible source) as LAS 1.4. Triggers a file download. The default is uncompressed (.las); compress:true gives LAZ (.laz) — a fraction of the size for the same content, but whether other software can read it depends on the tool, so the default is left alone. Deleted points are excluded (counted in excludedDeleted) and hidden points are included. A large point count returns confirm-required (re-run with force:true).
| Argument | Type | Required | Constraint |
|---|---|---|---|
force | boolean | Override the point-count threshold gate | |
compress | boolean | Default false. True exports LAZ (compressed) |
cropSelectionToCopc
Crop the current selection into a standalone COPC (server-side job cropToCopc). The selection's AABB is converted to real coordinates and passed in. Because the original raw file is cropped directly, non-destructive edits (deletion, reclassification and so on) are not reflected. The job can take a few seconds or more.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the cropped COPC (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the point cloud to crop (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one |
convertToCopc
Convert raw LAS/LAZ to COPC (the server-side job cropToCopc with whole-world bounds). A large compressed LAZ cannot be opened directly by the viewer, so it goes through this. By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the converted result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites). A .copc.laz extension is recommended | |
inputUri | string | uri of the point cloud to convert (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene |
classifyGroundToSource
Ground classification (the server-side job classifyGround, PDAL's ground command). By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the classified result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the point cloud to classify (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene | |
slope | number | 0-90. The job-side default when omitted | |
cellSize | number | 0.1-100, default 1.0. How fine you can go depends on the extent - the SMRF grid grows with (extent / cellSize) squared, so the server rejects an input that would not fit before running it and tells you which cellSize does | |
maxWindowSize | number | 1-200 |
removeOutliersToSource
Noise point removal (the server-side job removeOutliers, PDAL filters.outlier statistical method). By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the filtered result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene | |
meanK | number | 2-50. The job-side default when omitted | |
multiplier | number | 0.1-10 |
decimateToSource
Point decimation (the server-side job decimate, PDAL filters.decimation). Keeps one point every step (decimated to 1/step — the opposite of what the official documentation says, matching the actual behavior). By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the decimated result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene | |
step | number | ✔ | 2-1000. Keeps one point every step |
removeDuplicatesToSource
Duplicate point removal (the server-side job removeDuplicates, PDAL filters.voxelcenternearestneighbor). Keeps only the real point nearest each voxel center. By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the deduplicated result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene | |
cellSize | number | 0.0001-10 (m). The job-side default when omitted (0.01) |
colorizeByElevationToSource
Colorize by mapping elevation (Z) to color (the server-side job colorizeByElevation, PDAL filters.colorinterp). Existing RGB is overwritten. By default the result is added to the scene.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the colorized result (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without adding the result to the scene |
generateTinSurface
TIN generation plus LandXML conversion (the server-side job generateTin). Triangulates a ground point cloud with greedy projection triangulation and writes it out as the LandXML that oniyanma can read. By default it is added as a reference surface.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the LandXML (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
load | boolean | Default true. False runs the job without loading the result | |
multiplier | number | 0.1-20. The job-side default when omitted (2) | |
radius | number | 0.01-1000. The job-side default when omitted (5) |
generateContoursJob
Contour generation (the server-side job generateContours). Generates a DTM temporarily and writes GeoJSON contours. There is no path to load these into the oniyanma client — it only writes to the output URL.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the GeoJSON (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
interval | number | 0.01-1000 (m). The job-side default when omitted (1.0) | |
resolution | number | 0.1-100 (the raster resolution used while generating the DTM) |
generateDtmJob
DTM (GeoTIFF) generation (the server-side job generateDtm). Ground classification then IDW interpolation into a raster. There is no path to load this into the oniyanma client — it only writes to the output URL.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the GeoTIFF (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
resolution | number | 0.1-100. The job-side default when omitted (1.0) |
generateDsmJob
DSM (GeoTIFF) generation (the server-side job generateDsm). Rasterizes every point without classifying or extracting the ground. There is no path to load this into the oniyanma client — it only writes to the output URL.
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the GeoTIFF (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
resolution | number | 0.1-100. The job-side default when omitted (1.0) |
generateMeshJob
TIN / mesh generation (the server-side job generateMesh). Triangulates a ground point cloud with greedy projection triangulation and writes it out as PLY. There is no path to read PLY into the oniyanma client — it only writes to the output URL (use generateTinSurface to load the result as LandXML).
| Argument | Type | Required | Constraint |
|---|---|---|---|
outputUri | string | Output uri for the PLY (oniyanma://projects/{projectId}/…). Derived automatically when omitted (running the same job twice never overwrites) | |
inputUri | string | uri of the target point cloud (must be registered in this Project's Asset ledger; an external URL is used as-is). When omitted, the single URL-backed source is used if there is exactly one | |
multiplier | number | 0.1-20. The job-side default when omitted (2) | |
radius | number | 0.01-1000. The job-side default when omitted (5) |
Findings
Holds inspection-form item definitions as data, and files findings from them. Define a type and it becomes a JSON Schema directly, showing up in the AI's tool definitions.
defineFindingType
Create or update a finding type (the item definitions of an inspection standard). def = {id, label, standard?, fields:[{id,label,type:text|number|enum|boolean|date|link|measurement, required?, unit?, options?, min?, max?, maxLength?, linkTo?, description?}]}. An existing id is updated as a new version.
| Argument | Type | Required | Constraint |
|---|---|---|---|
def | object | ✔ | — |
listFindingTypes
read-only
List the finding types: [{id,label,standard,entryId,version,published,fields:[{id,label,type,required,unit,options}]}].
No arguments.
getFindingTypeSchema
read-only
Get a finding type as a JSON Schema (the shape you can pass to createFinding's fields; a customer-defined type becomes a tool definition as-is).
| Argument | Type | Required | Constraint |
|---|---|---|---|
typeId | string | ✔ | — |
createFinding
Raise a finding (a draft; the client does not see it until publishFinding). fields are values following the type definition, and pin is the position (real coordinates m, optional). Passing sourcePhoto/sourceBbox stamps $provenance with observation provenance, for a finding raised by pointing at a photo (design 0020 M2a, ADR 0021). Pass both together (either alone is invalid-argument). sourcePhoto is a pair of the PhotoSet's stable id (the asset-ledger id for a managed set, the manifest url for a URL-loaded one) and the photo id within that set — this is not the runtime id (photoset-N::fileId) that getPhoto/listPhotos return, so do not pass that as-is. The actor is recorded as human and no $review is attached (it does not enter the triage queue).
| Argument | Type | Required | Constraint |
|---|---|---|---|
typeId | string | ✔ | — |
fields | object | ✔ | — |
pin | number[] | 3 items | |
pinAccuracy | object | How certain the position is (only when the spot was picked by clicking on screen). distance=distance from the camera (m), tolerance=the world radius (m) of the tolerance circle at that moment, i.e. the returned point is somewhere within that width. Stamped at creation so that 'how certain is this position' can be read later | |
sourcePhoto | object | — | |
sourceBbox | object | — |
updateFinding
Update part of a finding (pass only the fields you want to change; a null value clears that field). If it was published, the client keeps seeing the old version until publishFinding is called again.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
fields | object | ✔ | — |
queryFindings
read-only
Filter findings by type (typeId), by the detector's raw label (sourceLabel, substring match) or by 3D proximity (near+maxDistance). A read-only query that lets an AI refer to unnamed detections such as 'that crack on the main girder' (listFindings only switches view and has no filtering). With near, results come back nearest first, and findings without a $pin (detections that could not be projected) are excluded because proximity cannot be judged (without near they stay regardless of $pin). Replies, merged findings and rejected findings are out of scope.
| Argument | Type | Required | Constraint |
|---|---|---|---|
typeId | string | — | |
sourceLabel | string | Substring match (case-insensitive) against the detector's raw label | |
near | number[] | 3 items / Real coordinates (m) [x,y,z]. When given, results come back nearest first | |
maxDistance | number | Only meaningful together with near. In meters | |
limit | number | — |
listFindings
read-only
List findings. view='draft'(everything including drafts, the default) | 'published'(only the published version the client sees) | 'deleted'(including withdrawn findings).
| Argument | Type | Required | Constraint |
|---|---|---|---|
view | string | 'draft' | 'published' | 'deleted' |
getFinding
read-only
Details of one finding. The type definition and references (such as the previous inspection's finding) are resolved one level deep. links[].exists=false means the referenced entry is gone.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
publishFinding
Publish a finding (fixed as the version the client sees. An explicit operation, not a side effect of saving).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
unpublishFinding
Withdraw a finding from publication (back to draft. The content does not change, so the version does not advance).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
deleteFinding
confirmation gate
Withdraw a finding (the record remains but it drops out of listings and the published surface. restoreFinding brings it back).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
restoreFinding
Restore a withdrawn finding (edits made while it was withdrawn come back too).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
commentFinding
Reply to a finding (a thread). id is the parent finding and text is the body. Replies do not appear in finding listings or exports.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
text | string | ✔ | — |
editComment
Edit the body of a reply (id is the reply itself; use updateFinding to edit a finding's body).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
text | string | ✔ | — |
listComments
read-only
Return the replies to a finding, oldest first: [{id,text,actor,createdAt,editedAt,editedBy}]. actor is the author (unchanged no matter who edits it later). editedAt / editedBy appear only when it was edited afterwards.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
exportFindings
Export findings (by default only the published version, i.e. the form you hand to the client). format='csv'(default)|'geojson', view='published'(default)|'draft'(including drafts, for internal use). Triggers a file download and returns a summary.
| Argument | Type | Required | Constraint |
|---|---|---|---|
format | string | 'csv' | 'geojson' | |
view | string | 'published' | 'draft' |
exportFindingsForm23
Export findings to CSV in the item order of the bridge_form23 type (compliant with Forms 2/3; the type must already be registered with defineFindingType) (the E3 standards-compliant export). Unlike exportFindings' generic CSV, the columns are fixed in the form's entry order. This is neither MLIT's electronic delivery standard (XML) nor the form itself (.xlsx) but a CSV matching the items of Forms 2/3 — meant to be pasted in. Findings that do not use the bridge_form23 type come out with every column empty. Published version only by default.
| Argument | Type | Required | Constraint |
|---|---|---|---|
view | string | 'published' | 'draft' |
Batches
Treats one continuous run of operations as a unit, revertible as a whole. One AI turn is one batch, and batches from the same instruction are grouped by runId (using "one instruction" as the revert unit would sweep in operations a human interleaved mid-way, so the finer-grained unit is used instead).
Accepting/rejecting a proposal (acceptBatch / rejectBatch) does not exist yet — the open question of "the AI accepting its own proposal" remains unresolved.
listBatches
read-only
List batches (one continuous operation = a human's run of actions / one AI turn), newest first. status='applied'|'proposed'(proposed, not applied)|'reverted' narrows it. limit defaults to 50 and is capped at 200 (out-of-range values are clamped and the actual value comes back in limit). intent is only the first 200 characters (get the full text with getBatch). Fewer items than total means the list is truncated.
| Argument | Type | Required | Constraint |
|---|---|---|---|
status | string | 'applied' | 'proposed' | 'reverted' | |
limit | number | 1 – 200 |
revertBatch
confirmation gate
Revert a whole batch (one continuous operation). What is reverted is the edit ops and the findings (Entries) created by a kind:'import' batch — import only ever creates, so it can be withdrawn safely. Other batches (human/aiTurn/macro) do not keep the pre-update values of Entries, so Entries are not reverted (the number that was not reverted comes back so you can check). Batches created by other people cannot be reverted. Calling this on a status:'proposed' batch (an AI proposal a human has not accepted yet) rejects it — its ops were never applied, so it simply disappears, which is the faithful way to undo it (call it before acceptBatch).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.
Note
Only edit ops (hide / delete / reclassify / color) are reverted. Changes to Entries such as findings are not — no intermediate version is stored anywhere, so calling this "revert" while leaving those unreverted would be misleading if left unstated. The count that could not be reverted comes back as entriesNotReverted, so a human can judge.
Note
While collaborating this removes it from the shared log, so it reverts on every participant's screen. Conversely, you cannot revert a batch another participant made (not-owner) — without authentication yet, this keeps the current discipline of "you can only revert your own work" from loosening.
acceptBatch
Accept a status:'proposed' batch (an AI proposal a human has not accepted yet). No op moves; only the batch's status becomes 'applied' — that alone takes it out of evaluate()'s exclusions, and from then on it looks like any other batch. Not usable on batches other than proposed (use revertBatch to reject). Callable only by a human issuer (if an AI could accept its own proposals, the proposal mechanism would stop meaning anything).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
queryBatchImpact
read-only
Return the number of points a batch touches, the kinds of ops, the center position (real coordinates m, ready to pass to frameRealPoint) and alignedBounds (the aligned-frame AABB, for reference) (resident-based; the display is unchanged). For checking the impact by the numbers before accepting or rejecting a HIST proposal batch, and for moving the camera to the center before deciding.
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
getBatch
read-only
Details of one batch (intent in full). Field references (Links) are resolved one level deep into links. Withdrawn batches can be read too (the record remains).
| Argument | Type | Required | Constraint |
|---|---|---|---|
id | string | ✔ | — |
Persistence
Saves to a sidecar (<dataset>.oniyanma.json). The original data is never changed.
saveEdits
Download the current non-destructive edits as a sidecar (.oniyanma.json) (the original data is not modified).
No arguments.
Project folders
Nestable folders for classifying data within a Project. A persistent structure on the D1 ledger, separate from design 0007's room sync (the ephemeral state of what is currently open). Available only while launched with ?project=.
createFolder
Create a folder to classify data within the Project (design 0024, nestable). The name is a free string. Omit parentFolderId to create it at the root.
| Argument | Type | Required | Constraint |
|---|---|---|---|
name | string | ✔ | — |
parentFolderId | string | — |
moveFolder
Move a folder itself into another folder (design 0024 M2). Omit parentFolderId to move it to the root. A folder cannot be moved into itself or its own descendants.
| Argument | Type | Required | Constraint |
|---|---|---|---|
folderId | string | ✔ | — |
parentFolderId | string | — |
moveAssetToFolder
Change an Asset's folder (by the ids from getState / the folder list). Omit folderId to move it back to the root.
| Argument | Type | Required | Constraint |
|---|---|---|---|
assetId | string | ✔ | — |
folderId | string | — |
deleteFolder
confirmation gate
Delete a folder. Its contents (assets and subfolders) move up one level (the assets themselves are not deleted).
| Argument | Type | Required | Constraint |
|---|---|---|---|
folderId | string | ✔ | — |
confirm | boolean | Execute as confirmed. Omitted/false does not execute and returns only the number of affected points (dry run) |
Confirmation gate
When a machine (ai / api) calls this without confirm, it does not execute — only the affected count comes back. Reviewing the count and calling again with confirm: true applies it. A human's UI action passes through directly. Details: Confirmation gate.