Documentation menu

XGRIDS handheld

Raw XGRIDS recordings, each capture folder exactly as the device wrote it: the .xbin file and its project_data folder, with the project's surveyed GCPs if it has any. Upload them anywhere in the dataset's bucket. Each recording is placed by three surveyed control points, by its RTK GNSS, or, to metres only, by its uncorrected GNSS. The device's processed export is not accepted.

Where to upload#

Anywhere in the dataset's bucket, in whatever folders suit you. Recordings and GCP files are found by what they are, at any depth:

<dataset bucket>/
├── Uden-kabels_2026-09-29/       an XGRIDS recording
│   ├── 2026-09-29-184907.xbin
│   └── project_data/
│       ├── control_points.csv
│       ├── gnss.csv
│       └── …
├── Thursday/
│   └── Arnhem-brug_2026-04-30/   another, in a folder of its own
└── survey.txt                    a GCP file
  • A recording is a folder with the device's .xbin.
  • A GCP file is a .txt or .csv outside the recordings, or directly in a recording's folder, whose lines read as points.
  • Only each recording's .xbin and project_data/ are processed. Anything else, such as the device's own map.las, is named in a warning and not read; you can leave it out of the upload. The ._ files a Mac leaves beside every file it copies are ignored.
  • The processed export is not a delivery of this type. The coloured point cloud, panoramas and panoramicPoses.csv that the maker's software exports have no .xbin and cannot be processed here.
  • The folders Georizon writes results to at the top of the bucket are not read: copc/, derived/, extra-reports/, panorama/, pointcloud/, pointcloud_tiles/, Reports/ and trajectories/.

Recordings#

Upload each capture folder whole and unchanged, as the device wrote it: the .xbin and the project_data/ folder beside it. Do not process, register or split it first. One folder holds one recording.

Recordings of a Lixel K2, a LixelKity K1 and a PortalCam are processed. Another XGRIDS model's recording is refused until that model has been measured: contact support to have it added.

The control points marked while recording (project_data/control_points.csv) are how a recording is tied to the GCPs: name each one on the device as its target is named in the GCP file. Names are compared exactly, upper and lower case included.

Ground control points#

Deliver the surveyed GCPs as text (.txt) or CSV (.csv), one point per line:

name  X  Y  Z  [code]
HDE_1  191120.3140  443150.6857  13.7377
HDE_2  191131.2955  443161.9406  13.4342
  • Columns are separated by spaces, tabs, commas or semicolons; decimals use a point.
  • X, Y and Z are in the dataset's CRS, X (easting) first. Nothing is reprojected; see Coordinates are not reprojected.
  • A header line before the first point is allowed, and # starts a comment.
  • Several files are fine, but a name is one point: the same name with two positions is refused.

How a recording is placed#

Each recording is placed in the dataset's CRS by the best of what it has:

  1. Three or more control points marked while recording, surveyed in the GCP files.
  2. Otherwise its RTK-fixed GNSS, as a Lixel K2 with an RTK module records it.
  3. Otherwise its uncorrected GNSS, as a PortalCam without corrections records it. That places the recording to metres, not centimetres: the point cloud's shape is as good as with the others, but it will not line up with other data of the site. Validation gives a warning naming the recording.

A recording with none of these, fewer than three surveyed control points and no GNSS, is refused.

Ingest parameters#

KeyRequiredTypeMeaning
anonymisationyesstring — recognised: already_anonymised, auto_anonymiseCompared exactly: auto_anonymise queues the panoramas for blurring, already_anonymised marks them as already blurred, any other value (ignore) does neither.
height_above_groundnonumberHeight of the panorama centre above the floor, in metres. 1.45 — a handheld carried by a walking operator — when not set. Default: 1.45.

1.45 m is the height of a handheld's panoramas carried by a walking operator; set height_above_ground for any other camera height.

Checks#

Every delivery is checked before anything is processed:

  • The delivery holds at least one XGRIDS recording: a folder with the device's .xbin, anywhere in the bucket. A processed export (a LAS or LAZ, panoramas, panoramicPoses.csv) is not one.
  • Each recording folder holds one .xbin, and it is an XGRIDS recording: an upload cut short to nothing, or another file renamed, is refused. The device is a model processed here (a Lixel K2, a LixelKity K1, a PortalCam), as its project_data/log/project.json names it.
  • Files that are not processed are named: anything outside the recordings that is no GCP file, and whatever sits in a recording folder beside its .xbin and project_data/, such as the device's own map.las. (a warning, not an error)
  • Every GCP file reads: after an optional header, each line is name X Y Z, optionally followed by a code, with a decimal point. A name is one point across all files. Each GCP lies within the area of use of the dataset's CRS.
  • Each recording can be placed: at least three of its control points are in the GCP files, or it has GNSS (300 fixes, half a minute's worth).
  • A recording with neither RTK-fixed GNSS nor three surveyed control points is placed on its uncorrected GNSS: good to metres, not centimetres. Its shape is not affected. (a warning, not an error)

What you get back#

  • One point cloud, placed as above, cleaned of moving objects, smoothed and coloured from the panoramas: as LAZ files under pointcloud/, one per recording (<recording>.laz), in the dataset's CRS. Points no panorama sees are black.
  • A single merged COPC at copc/pointcloud.copc.laz.
  • The panoramas, stitched from the device's camera frames every 5 m along the walk: level, with north at the centre, under panorama/jpg/, placed by panorama/pano_georizon.csv. The part of the view the operator stands in is filled. They are blurred when anonymisation is auto_anonymise, and carry depth from the point cloud for measuring in the viewer.
  • Each recording's trajectory, trajectories/<recording>.tum: one line per pose, time X Y Z qx qy qz qw, with the time in Unix seconds and the position in the dataset's CRS.
  • A QC report, under Documents on the dataset's page (Reports/processing/xgrids_qc_report.pdf in the bucket): the point cloud from above with the walked route, the area covered, how well the passes agree where the walk covers the same ground twice, and the fit to the GCPs where there are any. Stretches where the ground surface looked doubtful are listed beside it, in ground_check_auto_accepted.txt; check those during checkup.

A device's first recording processed here calibrates the timing of its motion sensor against its laser scanner, which takes a few minutes more; its later recordings reuse that calibration and refine it once.

People who stand near the operator while recording are removed from the point cloud as moving objects, but they are in the panoramas: the ground behind them can take the colour of their clothes. Keep bystanders away from the device while recording.

Common failures#

SymptomCause
"No XGRIDS recording found"No folder holds an .xbin: upload the capture folders as the device wrote them, not the processed export
"holds 2 recordings"Two capture folders were merged into one; upload each separately
"is not an XGRIDS recording"The .xbin is incomplete or another file; upload it again from the device
"which is not processed yet"The recording is from an XGRIDS model other than the Lixel K2, LixelKity K1 and PortalCam; contact support to have it added
"cannot be placed"Fewer than three of the recording's control points are in the GCP files and it has no GNSS: deliver the survey of its control points, named as on the device
"placed on its uncorrected GNSS" (warning)No RTK and no surveyed control points: the results are good to metres. Deliver the survey of its control points for centimetres
GCPs "are not positions in the dataset's CRS"The file is in another CRS, or X and Y are swapped