@page docutils OHM utilities
# OHM utilities
OHM includes a number of command line utilities supporting generating and manipulating ohm map files. This page provides
high level information about the available utilities, their primary purpose and general usage.
## ohmpop\[cpu,cuda,ocl\]
The `ohmpop` - "ohm populate" - utilities are used to generate ohm map files from a point cloud and corresponding
trajectory file. There are three versions of this utility which mostly share the same command line options. The GPU
enabled versions support some additional options to control GPU related settings.
- `ohmpopcpu` the CPU implementation of ohm map generation
- `ohmpopcuda` a CUDA enabled version of the algorithm. Only present when building with CUDA libraries.
- `ohmpopocl` an OpenCL enabled version of the algorithm. Only present when building with OpenCL libraries.
The input point cloud is expected to be the results of a SLAM scan after global optimisation and loop closure and
requires each point to be correctly timestamped in order to correlate the point against the trajectory file. The
trajectory file is used to identify the scanner position corresponding to each sample.
Supported inputs are as follows:
- Point cloud:
- Supports LAS/LAZ when ohm is built against `libLAS` and `lasZIP`.
- Supports many point cloud formats when built against PDAL. Precise formats depend on the PDAL support.
- Trajectory file:
- Supports a text file format (see below).
- Supports the same point cloud formats as the input cloud.
The text file trajectory format supports an optional "headings" line as the first line of the file after which each line
must be of the following form:
| Field | Description |
| ----------- | -------------------------------------------------------------------------- |
| Timestamp | Floating point timestamp value in the same time base as the point cloud |
| X | X coordinate for the sensor position, in the same frame as the point cloud |
| Y | Y coordinate for the sensor position, in the same frame as the point cloud |
| Z | X coordinate for the sensor position, in the same frame as the point cloud |
| q0 | Quaternion W component for the sensor rotation (unused) |
| q1 | Quaternion X component for the sensor rotation (unused) |
| q2 | Quaternion Y component for the sensor rotation (unused) |
| q3 | Quaternion Z component for the sensor rotation (unused) |
| user fields | Additional fields (optional, ignored) |
For each sample point, `ohmpop` tries to match a corresponding trajectory interval in the trajectory file and
interpolates the scanner pose between the nearest trajectory samples.
`ohmpop` generates a `.ohm` file for the map. By default it generates only the occupancy map layer, but command line
options may be used to generate the voxel mean layer and covariance (normal distribution transforms or ndt) layer. A ply
representation of the ohm map is also generated by default which contains a single point per occupied voxel.
## ohminfo
A basic utility for displaying the content of a `.ohm` map file. Most ohm algorithms add meta data about how the map was
generated which are included in the `ohminfo` display.
## ohm2ply
A conversion utility which extracts data from an ohm map into a PLY point cloud file. `ohm2ply` supports different
colourisation modes - e.g., colour by height - as well as different data extraction modes.
| ohm2ply mode | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| occupancy | (default) Extract a single point per occupied voxel preferring voxel mean over voxel centre if available |
| occupancy-centre | Same as `occupancy`, but always uses the voxel centre to position points |
| covariance | Uses the covariance/ndt layer to export polygonal ellipsoids from an ndt based map |
| clearance | Extract the `clearance` layer colouring points by proximity to an occupied voxel (experimental) |
| density | Use the voxel density mode as generated by `ohmpop[X] --traversal` |
| heightmap | Extract points from a heightmap map file (see `ohmheightmap`). Uses heights from the heightmap layer |
| heightmap-mesh | Meshes a single layer heightmap into a polygonal PLY file (experimental) |
Additionally the `--voxel-mode` modifies how voxels are exported. This has no effect when using `--mode=covariance`.
| ohm2ply voxel mode | Description |
| ------------------ | -------------------------------- |
| points | (default) extract a point cloud. |
| voxel | Extract a cube per voxel. |
## ohmheightmap
Generates a heightmap from an ohm map file. The output is another ohm map file with a heightmap data layer. Supports a
number of heightmap generation methods including generating a multi-layer heightmap.
| ohmheightmap mode | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| planar | Simple planar walk, searching for a ground voxel within a band across the map. Generates a single layer. |
| fill | A flood fill based extension of the planar technique. Generates a single layer. |
| layered | Generates a multi-layer heightmap. Columns are sorted in ascending height order. |
| layered-unordered | Generates a multi-layer heightmap. Columns are unsorted. |
## ohmfilter
Filters an input point cloud against an ohm map rejecting points which do not fall within occupied voxels in the
occupancy map.
## ohmprob
A simple utility which converts a floating point value between an occupancy probability and an occupancy value (log
space). This uses the same algorithm used in ohm map occupancy calculations.
## ohmhm2img (experimental)
Converts an ohm heightmap file into a png image. This is an experimental utility and does not support layered
heightmaps.
## ohmquery\[cuda,ocl\] (experimental)
Supports running experimental ohm query algorithms - `OhmLineQuery`, `OhmNearestNeighbours`.