cjio (CityJSON/io)

One of the core features of cjio is the ability to chain multiple operators together in a single command. The CityJSON model is passed through each operator sequentially, being modified along the way. Operators like info or validate output information to the console but pass the model to the next step in the pipeline.

Examples:

# Subset, remove materials, and save
cjio example.city.json subset --id house12 remove_materials save out.city.json

# Remove textures and show info
cjio example.city.json remove_textures info

# Upgrade, validate, and save
cjio example.city.json upgrade validate save new.city.json

# Merge multiple files into one
cjio myfile.city.json merge '/home/elvis/temp/*.city.json' save all_merged.city.json

To run cjio in a containerized environment, use the tudelft3d/cjio:latest image. You must mount your local data directory to a path inside the container (e.g., /data).

Run cjio help via Docker:

docker run --rm -v <local_path_to_files>:/data tudelft3d/cjio:latest cjio --help

Run a Python script via Docker: If you have a Python script (e.g., gridder.py) that uses the cjio library, you can execute it within the Docker environment by mounting the script and data:

docker run --rm -v <local_path_to_files>:/data tudelft3d/cjio:latest python gridder.py

docker run --rm -v <local path where your files are>:/data tudelft3d/cjio:latest cjio --help

While cjio supports CityJSON v2.0, it can automatically upgrade older files (v1.0 and v1.1) using the upgrade operator.

To upgrade a file to the latest schema version, use the following syntax:

cjio old.json upgrade save newfile.city.json

Install the latest release of cjio using pip. Note that cjio requires Python 3.7+.

To install the core package:

pip install cjio

Some commands like export, triangulate, reproject, and validate require extra dependencies. To install them, use:

pip install 'cjio[export,reproject,validate]'

Windows Users: If you encounter errors related to pyproj or pyrsistent, you may need to manually download and install wheels (binary packages) for these libraries (e.g., from Gohlke's website) before running pip install cjio.

Semantic Surfaces are stored in the .surfaces attribute of a Geometry object. They are primarily available in models with LoD >= 2.

• Filtering: Use geom.get_surfaces(type='...') to retrieve specific surface types (e.g., 'roofsurface').
• Extracting Boundaries: Use geom.get_surface_boundaries(surface_dict) to efficiently extract the geometric boundaries for a specific surface. This method utilizes the surface_idx property within the surface dictionary.

# Get all roof surfaces
roofs = geom.get_surfaces(type='roofsurface')

# Extract boundaries for each roof surface
roof_boundaries = []
for r in roofs.values():
    roof_boundaries.append(geom.get_surface_boundaries(r))

Semantic surfaces allow you to assign types (like WallSurface, GroundSurface, or RoofSurface) to specific parts of a geometry's boundary.

To define them, you populate the geom.surfaces dictionary. Each entry requires a type and a surface_idx list. The structure of the indices in surface_idx depends on the boundary type:

• Solid boundary type: The index is composed of [Shell index, Surface index]. (Note: The tutorial example uses [0, 0] style for a single solid).
• CompositeSolid boundary type: The index is composed of [Solid index, Shell index, Surface index].
• MultiSurface boundary type: Both the Solid index and Shell index are omitted, leaving only the Surface index.

Example mapping for a Solid geometry:

geom.surfaces[0] = {'surface_idx': [[0,0], [0,1]], 'type': 'WallSurface'}

The cjio API uses two primary classes to handle 3D data:

1. Geometry: Represents the high-level geometry object. It contains metadata like type, lod (Level of Detail), and a semantics_obj which holds semantic surface information. It provides the get_surfaces() method.
2. Boundary: Represents the geometric boundary. It holds the vertices and the geometry (a nested array of vertex indices).

When accessing a CityObject, the .geometry attribute returns a Geometry instance, which in turn provides access to its .boundaries (a Boundary instance).

When building a CityJSON model programmatically, simply adding objects to the model is not enough to make it valid for file export. You must perform a reference geometry pass to index boundaries and create the vertex list, then add these to the internal JSON store.

Use the following sequence:

1. cityobjects, vertex_lookup = cm.reference_geometry(): Generates the necessary geometry references and vertex lookups.
2. cm.add_to_j(cityobjects, vertex_lookup): Adds the processed objects and vertices to the model's internal JSON structure.
3. cm.update_bbox(): Recalculates the bounding box.
4. cityjson.save(cm, outfile): Writes the model to disk.

CityJSON models are hierarchical. You can traverse from a parent CityObject to its children or from a child back to its parents using the following methods on a CityObject instance:

• get_children(): Returns a list of child CityObjects.
• get_parents(): Returns a list of parent CityObjects.

Example of recursive traversal:

cm = cjio.load("some_model.json")
buildings = cm.get_cityobjects("building")

for building in buildings:
    # Access immediate children
    children = building.get_children()
    for child in children:
        # Access children of children (recursive)
        grand_children = child.get_children()