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
.txtor.csvoutside the recordings, or directly in a recording's folder, whose lines read as points. - Only each recording's
.xbinandproject_data/are processed. Anything else, such as the device's ownmap.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.csvthat the maker's software exports have no.xbinand 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/andtrajectories/.
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:
- Three or more control points marked while recording, surveyed in the GCP files.
- Otherwise its RTK-fixed GNSS, as a Lixel K2 with an RTK module records it.
- 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#
| Key | Required | Type | Meaning |
|---|---|---|---|
anonymisation | yes | string — recognised: already_anonymised, auto_anonymise | Compared exactly: auto_anonymise queues the panoramas for blurring, already_anonymised marks them as already blurred, any other value (ignore) does neither. |
height_above_ground | no | number | Height 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 itsproject_data/log/project.jsonnames 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
.xbinandproject_data/, such as the device's ownmap.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 bypanorama/pano_georizon.csv. The part of the view the operator stands in is filled. They are blurred whenanonymisationisauto_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.pdfin 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, inground_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#
| Symptom | Cause |
|---|---|
| "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 |