PyOpenCRG

Unofficial implementation of the OpenCRG file format. Not affiliated with, endorsed by or supported by ASAM e.V. OpenCRG® is a registered trademark of ASAM e.V.

_{Belgian block sample road of the ASAM OpenCRG project, drawn with road.view3d(color="grid", cmap="jet", z_scale=2.5) (relief exaggerated 2.5 times).}

PyOpenCRG (import pyopencrg) reads, analyses, edits, shows and writes OpenCRG road surface files (.crg) in pure Python. You do not need to compile anything, and it runs on Windows, Linux and macOS.

• All OpenCRG formats: binary KRBI / KDBI and text LRFI / LDFI, with full header support (comments, options, modifiers, map projection, WGS84).
• Fast: everything is vectorised with numpy. A file of 10 million values is read in 0.1 s (binary) or about 4 s (text).
• Accurate: data stays in double precision (float64). The algorithms follow the OpenCRG reference tools.
• Simple: one object, CrgRoad, with plain-named methods. Every editing method returns a new road.
• Complete: everything in the OpenCRG MATLAB tools, plus tools to clean laser scans, convert STL meshes and export to OBJ / STL / CSV / images / Simpack.

French guide: docs/guide_fr.md. Equivalence with the MATLAB tools: docs/matlab_equivalence.md.

Installation

pip install pyopencrg            # numpy, scipy and matplotlib are installed automatically
pip install "pyopencrg[image]"   # adds Pillow, needed only for engrave_image()
pip install "pyopencrg[viewer]"  # adds PyVista, for the fast interactive 3D viewer road.view3d()

In 10 lines

import pyopencrg as crg

road = crg.read("my_road.crg")          # any OpenCRG file
print(road)                              # summary: length, width, grid, slope...
print(road.check())                      # consistency checks

z = road.uv_to_z(120.0, 0.5)             # height 120 m along the road, 0.5 m left of the reference line
x, y = road.uv_to_xy(120.0, 0.5)         # where this point is in the world

part = road.crop(u=(100, 200))           # keep 100 m of road (a NEW road, `road` is unchanged)
part.save("part.crg", fmt="LDFI")        # save as a text file
road.show()                              # overview figures
road.view3d()                            # interactive 3D view (PyVista)

Files are checked when they are read: a truncated, unreadable or badly defined file raises a CrgCheckError explaining the problem, and minor problems are shown once as a warning. Use crg.read(path, check=False) to open a damaged file anyway (to repair it), or check="strict" to refuse files with warnings too.

Files larger than the memory: only what you ask for is loaded.

preview = crg.read("scan.crg", step=4)        # one point out of 4 in both directions (16 x less memory)
detail = crg.read("scan.crg", u=(500, 520))   # 20 m at full resolution

Gallery

Height map of the whole road, and a zoom where every 1 cm grid point is visible (road.plot.heightmap(cmap="jet"); zooming in a figure re-samples the image automatically):

Reference line, valid data limits, cross sections and long sections (road.plot.show_cuts_and_limits()):

_{Pictures rendered from the sample belgian_block.crg of the ASAM OpenCRG project (data provided by DaimlerChrysler, 2005; Apache License 2.0). The sample file is not distributed with PyOpenCRG; the pictures are made with docs/make_images.py.}

Coordinates in one picture

OpenCRG describes a road along a reference line (usually the road centre):

• u = distance along the reference line (m), v = lateral distance to it (m, positive to the left);
• x, y, z = position in the world.

The data is a grid road.z of shape (nu, nv): road.z[i, j] is the height at u = road.u[i], v = road.v[j], relative to the reference line. The absolute height of the road is

z_absolute = road.z  +  road.zr (reference line elevation)  +  road.banking * v

road.uv_to_z(u, v) always returns the absolute height.

What you can do

Every function has a detailed docstring: type help(road.crop) in Python.

Command line

pyopencrg info  road.crg
pyopencrg check road.crg
pyopencrg show  road.crg
pyopencrg view  road.crg                          # 3D viewer (PyVista)
pyopencrg convert road.crg road_text.crg --fmt LDFI
pyopencrg export road.crg road.obj --step 2       # .obj .stl .csv .png .html .trm

Examples

See the examples folder: reading and plotting, editing, synthetic roads, cleaning a laser scan, STL to CRG conversion, an obstacle test track.

Modifiers: a word of warning

The $ROAD_CRG_MODS block of a file tells a simulator how to modify the road when it loads it (scale it, fill NaN values, move it). crg.read() returns the road as stored in the file; call road.apply_mods() (or crg.read(path, apply_mods=True)) to get what a simulator sees. If a file has no modifier block, OpenCRG applies default modifiers: NaN values are replaced by the last valid value of the cross section and the road start is moved to x = y = z = 0 with heading 0.

Development

pip install -e ".[test,image]"
pytest

Citing

If you use pyopencrg in a report, a publication or another software, please cite it (see CITATION.cff):

Hardy, T. PyOpenCRG: OpenCRG road surface files in pure Python, version 0.1.0, 2026.

License

Apache License 2.0, see LICENSE and NOTICE. Parts of the algorithms are derived from the ASAM OpenCRG MATLAB tools (Apache 2.0).