Skip to content

Basic use

One of the main differences between a single IMX file and a containerized IMX is that a single file can represent multiple situations. A containerized IMX, on the other hand, is a snapshot in time and can be seen as a single situation.

To maintain consistency and ease of use, the APIs for handling both single and containerized IMX files are designed to be as similar as possible. This allows end users to switch between single and containerized IMX files with minimal changes to their code.

Single file IMX

In this case, the IMX is a single XML file containing a situation or a project with an initial situation and optional a new situation. You need to define the situation of interest.

Containerized IMX

In this case, the IMX is a container holding multiple XML files that represent a snapshot in time. You do not need to define a situation.

The basic examples below can be switched using the tabs, making the differences clear.

Load file

The imxInsights package provides two main ways to load IMX files, depending on the IMX version and file structure:

  • For versions up to 12: IMX data is stored as a single XML file containing two situations (scenarios). The ImxSingleFile class handles loading and managing these individual XML files.

  • From version 12 onwards: IMX data is packaged in a container format (e.g., ZIP archive or directory structure) that holds multiple files, allowing more flexibility. The ImxContainer class is used to handle and load these containers.

from imxInsights import ImxSingleFile

imx = ImxSingleFile(r"path to xml file")

from imxInsights import ImxContainer

imx = ImxContainer(r"path to xml zip container or folder")

Get file metadata

To retrieve metadata from IMX files, there are distinct approaches depending on the file type:

  • For ImxSingleFile you can obtain all necessary metadata in a single call.

  • For ImxContainer retrieving metadata from containers requires individual calls for each file within the container.

print(imx.file.imx_version)
print(imx.file.file_hash)

print(imx.files.signaling_design.imx_version)
print(imx.files.signaling_design.file_hash)

print(imx.files.observations.imx_version)
print(imx.files.observations.file_hash)

Get build exceptions

When loading an IMX file, various errors may occur. These errors are listed and logged, allowing you to review them after the loading process. You can look up build exceptions for both single files and container files.

For example, you can retrieve exceptions using the following code:

# print build exceptions
for puic, exceptions in imx.situation.get_build_exceptions():
    print(puic, [exception.msg for exception in exceptions])

# print build exceptions
for puic, exceptions in imx.get_build_exceptions():
    print(puic, [exception.msg for exception in exceptions])

Query Objects

After loading an IMX file, you can effortlessly extract valuable information from it. For a detailed list of available options, please consult the API reference. Below are the key concepts for querying both single and container files, which utilize a consistent API for seamless interaction.

When working with ImxSingleFile, remember to interact with specific instances to retrieve information. With ImxContainer, you can directly access the object for your queries.

# get all from a situation
all_objects = imx.situation.get_all()

# get from init situation in a project
imx_object = imx.initial_situation.find("puic_uuid4")

# get all types new situation in a project
object_types = imx.new_situation.get_types()

# get by type new situation in a project
object_subset = imx.new_situation.get_by_types([object_types[0], imx_object.tag])

# get all
all_objects = imx.get_all()

# get from situation
imx_object = imx.find("puic_uuid4")

# get all types
object_types = imx.get_types()

# get by type
object_subset = imx.get_by_types([object_types[0], imx_object.tag])

GeoJson

GeoJSON is a open format for representing geographical data. Below are code snippets demonstrating how to work with GeoJSON.

# get a feature collection by giving it a path
feature_collection = imx.initial_situation.get_geojson(["Signal"])

# keep coordinates as RD + NAP and add extension object properties
feature_collection_rd = imx.initial_situation.get_geojson(
    object_path=["Signal"],
    to_wgs=False, extension_properties=True
)

# get a string representation of the geojson
geojson_str = feature_collection_rd.geojson_str()

# write to file
feature_collection.to_geojson_file(file_path="Signals.geojson")

# write all to file
imx.new_situation.create_geojson_files(directory_path="geojson")

# get a feature collection by giving it a path
feature_collection = imx.get_geojson(["Signal"])

# keep coordinates as RD + NAP and add extension object properties
feature_collection_rd = imx.get_geojson(
    object_path=["SingleSwitch"],
    to_wgs=False, extension_properties=True
)

# get a string representation of the geojson
geojson_str = feature_collection_rd.geojson_str()

# write to file
feature_collection.to_geojson_file(file_path="Signals.geojson")

# write all to file
imx.create_geojson_files(directory_path="geojson")