Camera Settings

The cameras section defines the physical LumiScan cameras used by the project and the settings required to acquire calibrated image and depth information.

These settings include camera identification, exposure control, depth estimation, and corrections applied to the camera data.

Camera Parameters

Point-Cloud Unit

From v2.0.0.

The coordinates of a camera’s point cloud carry no unit of their own, so LumiScan VGR resolves the unit in this order; the first match wins:

  1. A recording that is replayed (a file-backed camera, for example with --simulate-camera) states its own unit in the dataset.unit.json file of its folder. A folder without one is judged from its first point cloud: a median depth below 20 is read as metres, above as millimetres, with a warning that names the file to write. Centimetres cannot be told by the depth, so they need the file. The distanceUnit of the live camera is not used for a replayed camera.

  2. cameraParameters[].distanceUnit in the project settings, keyed by cameraId: the live camera.

  3. The camera’s HDVPointcloudUnit feature: the unit of the point cloud that the camera library delivers. The Ensenso, RealSense, Pepperl+Fuchs and LumiScan camera plugins state it, and so does the camera library for the GenTL cameras it knows by vendor and model (Teledyne e2v Camera5d: centimetres, Ensenso: millimetres). A known camera therefore needs no setting.

  4. The camera’s own Scan3dDistanceUnit GenICam feature. It is not trusted over the one above: a Teledyne camera declares millimetres and delivers centimetres.

  5. Metres, as a last resort, with a warning that names the camera.

LumiScan VGR saves a point cloud in the unit that its camera delivers and scales it to metres only internally. When it saves the first point cloud into a folder that has no dataset.unit.json, it writes one, and it never rewrites it; it warns if a later point cloud is in another unit. A recording is therefore what the camera delivered, and a replay goes through the same path as a live capture. The file looks like this:

{ "unit": "MILLIMETER" }

unit is the only required key: METER, CENTIMETER, MILLIMETER or INCH, in any case. For a scale without a unit name, metresPerUnit can be given instead.

The live unit is the only thing a project has to state, and only for a camera that cannot state it itself and that the camera library does not know, for example a plain GenICam camera of another make. An entry for a known camera is not needed. If it differs from what the camera says, the entry is used, with a warning, because that is how a commissioned system notices that its camera plugin has changed:

"cameraParameters": [
    { "cameraId": "camera-teledyne", "distanceUnit": "CENTIMETER" }
]

  • A folder is one camera’s recording, and its dataset.unit.json states the unit of the whole folder. Keep recordings in different units in separate folders.

  • For recordings that LumiScan VGR did not make, or that an older version made in metres without a unit file, put a dataset.unit.json in their folder, for example {"unit": "METER"}.

  • A tool that reads the exported point clouds and expects metres must read dataset.unit.json and multiply by the metres per unit (millimetres 0.001, centimetres 0.01, inches 0.0254).

  • A recording’s unit is only as right as the unit that LumiScan VGR resolved when it was made. The file records what was applied, so a replay reproduces the live capture, right or wrong.

A wrong unit does not produce a visibly wrong point cloud, it produces no point cloud: a metric cloud scaled as if it were centimetres collapses into a single collision voxel and disappears. In that case LumiScan VGR logs the median depth it measured and names the unit that would bring it back into range.