DigitalTwinClient API | AODT Documentation

This page is generated from the imported Python-visible client bindings exposed by the dt_client module, including the main client class, PrepareMap task helpers, and temporal index helper types used by its APIs.

DigitalTwinClient

Import path: dt_client.DigitalTwinClient

class dt_client.DigitalTwinClient(
    server_address: str = 'localhost:50051',
    force: bool = False,
)

Client for interacting with the Digital Twin server.

Use this class to load scenarios from YAML, inspect scenario metadata, query infrastructure and mobility positions, allocate CIR result buffers, compute channel responses, fetch data into NumPy arrays, and export server-side results.

Typical workflow:

Construct the client and verify is_connected.
Call start() with the full scenario YAML string.
Inspect get_status() or the position query helpers.
Allocate CIR memory with allocate_cirs_memory().
Compute results with get_cirs() and fetch them with to_numpy() or to_numpy_all_cir().

The constructor negotiates the transport mode exposed by transport_mode.

Create a Digital Twin client connected to the specified server.

Parameters: •server_address (str) - gRPC endpoint for the Digital Twin server.
•force (bool) - If true, replace an existing connected client and cancel its ongoing work on the server.

Returns: None

Construction acquires the single-client lock on the server and negotiates the available data transport. If force is true, any existing client session is disconnected and any ongoing server work for that session is canceled so this client can take ownership.

Properties

has_gpu

property dt_client.DigitalTwinClient.has_gpu

Whether the client has a GPU

is_connected

property dt_client.DigitalTwinClient.is_connected

Whether the client has an active session with the server

transport_mode

property dt_client.DigitalTwinClient.transport_mode

Negotiated transport mode: ‘LOCAL_IPC’ or ‘REMOTE’

Methods

allocate_cirs_memory

dt_client.DigitalTwinClient.allocate_cirs_memory(
    ru_indices: object,
    ue_indices_per_ru: object,
    is_full_antenna_pair: bool = False,
    num_time_steps: object = None,
) -> dt_client.CIRAllocation

Allocate result buffers for later CIR computation.

The returned CIRAllocation captures the buffer layout and is reused by get_cirs(), to_numpy(), and to_numpy_all_cir().

Supports two input styles:

Broadcast style Use this when every time step uses the same RU list and the same UE-per-RU layout.

ru_indices: list[int]
ue_indices_per_ru: list[list[int]]
num_time_steps: optional, defaults to 1 and repeats the same layout for each time step

Per-time-step style Use this when different time steps need different RU or UE sets.

ru_indices: list[list[int]]
ue_indices_per_ru: list[list[list[int]]]
num_time_steps: optional; if omitted, it is inferred from the length of ru_indices. If provided, it must match that length.

Parameters: •ru_indices - RU indices (1D for broadcast, 2D for per-time-step)
•ue_indices_per_ru - UE indices per RU (2D for broadcast, 3D for per-time-step)
•is_full_antenna_pair (bool) - True for full antenna-pair outputs, false for single antenna-pair outputs.
•num_time_steps (int, optional) - Number of repeated time steps in broadcast mode, or an optional consistency check in per-time-step mode.

Raises: RuntimeError - If the RU and UE index layouts are invalid, num_time_steps is inconsistent, or the server cannot allocate CIR buffers.

Returns: Allocation object containing metadata, offsets, shapes, and lazy-fetch state.
Return type: CIRAllocation

ru_indices and ue_indices_per_ru must use matching dimensionality. Mixing broadcast and per-time-step layouts is rejected.

Examples

1 # Broadcast style: same RU/UE layout replicated for 3 time steps
2 # RU 0 serves UEs [0,1,2], RU 1 serves UEs [0,1,2] -- at every time step
3 alloc = client.allocate_cirs_memory(
4     [0, 1],                       # ru_indices (1D = same for all time steps)
5     [[0, 1, 2], [0, 1, 2]],       # UEs for RU 0, UEs for RU 1
6     is_full_antenna_pair=False,
7     num_time_steps=3,              # replicate this layout for 3 time steps
8 )
9 # Per-time-step style: different RU/UE layout at each time step
10 # 3 time steps (inferred from the outer list length):
11 #   t=0: RU 0 serves UEs [0,1,2], RU 1 serves UEs [3,4]
12 #   t=1: RU 0 serves UEs [0,1]
13 #   t=2: RU 1 serves UEs [2,3,4]
14 alloc = client.allocate_cirs_memory(
15     [[0, 1], [0], [1]],          # ru_indices per time step
16     [[[0, 1, 2], [3, 4]],         # t=0: UEs for RU 0, UEs for RU 1
17      [[0, 1]],                    # t=1: UEs for RU 0
18      [[2, 3, 4]]],                # t=2: UEs for RU 1
19     is_full_antenna_pair=True,
20 )

cancel_simulation

dt_client.DigitalTwinClient.cancel_simulation(
    reason: str = '',
) -> None

Cancel an in-progress streaming operation on the server.

This is typically used to stop run_full_simulation() or get_cirs() from another thread while the blocking RPC is still running.

Parameters: •reason (str, optional) - Human-readable reason for the cancellation request.

Raises: RuntimeError - If the cancellation request cannot be delivered or the server reports failure.

To cancel a blocking streaming RPC from the same Python process, start that RPC on a worker thread and call cancel_simulation() from another thread. If that is not possible, another process can construct DigitalTwinClient(..., force=True) to take over the session and trigger cancellation.

clear_exported_results

dt_client.DigitalTwinClient.clear_exported_results(
    clear_database: bool = True,
    clear_exported_files: bool = True,
) -> dict

Clear result data from ClickHouse and/or S3

Parameters: •clear_database (bool) - Clear result tables in ClickHouse (default True)
•clear_exported_files (bool) - Delete Parquet files from S3 (default True)

Raises: RuntimeError - If the server cannot clear the requested result data.

Returns: Dictionary containing a success flag and a human-readable status message from the server.
Return type: dict

Examples

1 client.clear_exported_results()  # clear both DB and S3
2 client.clear_exported_results(clear_database=False)  # S3 only

deallocate_cirs_memory

dt_client.DigitalTwinClient.deallocate_cirs_memory(
    allocation: dt_client.CIRAllocation,
) -> None

Release the resources associated with a CIR allocation on both the client and server.

Parameters: •allocation (CIRAllocation) - The allocation returned by allocate_cirs_memory

Raises: RuntimeError - If the allocation cannot be released on the client or server.

export_results

dt_client.DigitalTwinClient.export_results(
    tables: list[str] = [],
    temporal_index: object = None,
    batch_index: int = 0,
) -> dict

Export result data to Parquet files on S3

Parameters: •tables (list[str]) - Tables to export (e.g. [‘cirs’, ‘raypaths’]). Empty list uses scenario defaults from opt_in_db_tables.
•temporal_index (SlotIndices|TimeStepIndices|None) - Temporal index. None = export all.
•batch_index (int) - Batch index (only used with temporal filter, default 0)

Raises: RuntimeError - If temporal_index has the wrong type or the server cannot export the requested results.

Returns: files_exported, total_rows, elapsed_seconds
Return type: dict

Examples

1 result = client.export_results()  # export all configured tables
2 # and all time steps
3 result = client.export_results(['cirs', 'raypaths'])
4 # export only the selected tables
5 result = client.export_results(temporal_index=SlotIndices([0, 1, 2]))
6 # export only the selected time steps

get_cirs

dt_client.DigitalTwinClient.get_cirs(
    allocation: dt_client.CIRAllocation,
    batch_index: int,
    temporal_index: object,
) -> None

Compute channel impulse responses into an existing allocation.

This method requires a loaded scenario and an allocation previously returned by allocate_cirs_memory(). While this blocking streaming RPC is running, other Python threads in the same process can still run.

After a successful call, allocation.temporal_indices is updated so the fetched tensors can be addressed by actual slot or time step index.

Parameters: •allocation (CIRAllocation) - The allocation from allocate_cirs_memory
•batch_index (int) - Batch index
•temporal_index - SlotIndex(n), TimeStepIndex(n), SlotIndices([…]), or TimeStepIndices([…])

Raises: RuntimeError - If temporal_index has the wrong type or the server cannot compute CIR data for the requested batch and temporal indices.

Examples

1 client.get_cirs(alloc, 0, SlotIndices([3, 7]))
2 print(alloc.temporal_indices)  # [3, 7]

get_ru_positions

dt_client.DigitalTwinClient.get_ru_positions() -> list

Return the static infrastructure positions for every RU in the loaded scenario.

Raises: RuntimeError - If RU positions cannot be retrieved from the server.

Returns: List of [x, y, z] positions ordered by RU index.
Return type: list

get_status

dt_client.DigitalTwinClient.get_status() -> dict

Return summary metadata for the currently loaded scenario.

Raises: RuntimeError - If the scenario status cannot be retrieved from the server.

Returns: Dictionary with the keys scenario_loaded, num_rus, num_ues, total_batches, is_slot_symbol_mode, and num_slots_or_timesteps_per_batch. The final field is interpreted as slots per batch in slot/symbol mode and time steps per batch in duration/interval mode.
Return type: dict

get_ue_positions

dt_client.DigitalTwinClient.get_ue_positions(
    batch_index: int,
    temporal_index: object,
) -> list

Return UE positions for one slot or time step in a specific batch.

Use SlotIndex when the scenario is configured in slot/symbol mode and TimeStepIndex when the scenario uses duration/interval mode.

Parameters: •batch_index (int) - Batch index within the loaded scenario.
•temporal_index (SlotIndex|TimeStepIndex) - Temporal location to sample.

Raises: RuntimeError - If temporal_index has the wrong type or UE positions cannot be retrieved from the server.

Returns: UE positions as [[x, y, z], …].
Return type: list

prepare_map

dt_client.DigitalTwinClient.prepare_map(
    task: object,
    s3_config: object,
) -> dict

Prepare a GIS map from OSM or GML data

Does not require a loaded scenario. The server proxies this request to a Temporal workflow internally.

Parameters: •task (OSMTask|GMLTask) - Task configuration
•s3_config (S3Config) - S3 connection credentials

Raises: RuntimeError - If task is not an OSMTask or GMLTask instance.

Returns: success, s3_url, message, request_id
Return type: dict

Examples

1 from _config import S3Config
2 from dt_client import OSMTask
3 s3 = S3Config(bucket='warehouse', provider='minio', endpoint_url='http://...')
4 task = OSMTask(output_folder_key='test', coords=(-122.34, 47.60, -122.33, 47.61), include_elevation=True)
5 result = client.prepare_map(task, s3)

run_calibration

dt_client.DigitalTwinClient.run_calibration() -> dict

Run calibration for the loaded calibration scenario.

This is a blocking streaming RPC that reports coarse progress stages: started, building_edges, running, and completed.

Raises: RuntimeError - If calibration is rejected by the server or the stream cannot be completed.

Returns: Dictionary with total_time_seconds, stage, and message.
Return type: dict

run_full_simulation

dt_client.DigitalTwinClient.run_full_simulation() -> dict

Run the full server-side simulation loop for all remaining batches and time steps.

This is a blocking streaming RPC. While it is running, other Python threads in the same process can still run, so one of them can call cancel_simulation().

Start this call on a worker thread if you want to cancel it from the same Python process. If the simulation was started on the main thread and you cannot issue a cancellation call from that process, a second process can construct DigitalTwinClient(..., force=True) to take over the single- client session. The server cancels in-flight streaming RPCs before transferring ownership.

Raises: RuntimeError - If the simulation stream cannot be completed or is rejected by the server.

Returns: Dictionary with time_steps_completed and total_time_seconds.
Return type: dict

start

dt_client.DigitalTwinClient.start(yaml_content: str) -> bool

Load or replace the active scenario on the server from a YAML string.

Parameters: •yaml_content (str) - Complete scenario configuration serialized as YAML.

Returns: True if the server accepted and loaded the scenario.
Return type: bool

start_server_log_streaming

dt_client.DigitalTwinClient.start_server_log_streaming(
    log_file_path: str = 'dt_server.log',
    min_level: str = 'INFO',
) -> bool

Start streaming server logs to a local file on a background thread

Non-blocking: returns immediately. Server log lines are written to the specified file as they arrive.

Parameters: •log_file_path (str) - Local file path (default ‘dt_server.log’)
•min_level (str) - Minimum level filter: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’ (default ‘INFO’)

Returns: True if streaming thread started successfully
Return type: bool

Examples

1 client.start_server_log_streaming('server.log', 'DEBUG')

stop_server_log_streaming

dt_client.DigitalTwinClient.stop_server_log_streaming() -> None

Stop the server log streaming background thread

Cancels the gRPC stream and waits for the thread to finish. Safe to call even if streaming was never started.

to_numpy

dt_client.DigitalTwinClient.to_numpy(
    allocation: dt_client.CIRAllocation,
    temporal_idx: int,
    ru_idx: int,
    data_type: str = 'values',
) -> object

Copy one CIR tensor into a NumPy array for a specific temporal index and RU.

Transparently handles all transport modes. On first access for a given buffer type, pulls data from the server via gRPC in REMOTE mode. Always fetches to CPU since the output is a numpy array.

Parameters: •allocation (CIRAllocation) - The allocation (must have called get_cirs first)
•temporal_idx (int) - Actual slot or timestep index
•ru_idx (int) - Actual RU index
•data_type (str) - ‘values’, ‘delays’, ‘angles_of_departure’, or ‘angles_of_arrival’

Raises: RuntimeError - If the requested temporal index or RU is not present in the allocation, data_type is unsupported, or the buffer cannot be fetched.

Returns: CIR data for that (temporal, RU) pair. Angle outputs use a trailing size-2 axis for (azimuth, zenith).
Return type: numpy.ndarray

Examples

1 values = client.to_numpy(alloc, 3, 40)
2 delays = client.to_numpy(alloc, 3, 40, data_type='delays')
3 aod = client.to_numpy(alloc, 3, 40, data_type='angles_of_departure')
4 aoa = client.to_numpy(alloc, 3, 40, data_type='angles_of_arrival')

to_numpy_all_cir

dt_client.DigitalTwinClient.to_numpy_all_cir(
    allocation: dt_client.CIRAllocation,
) -> dict

Copy every computed CIR tensor into nested NumPy dictionaries.

Transparently handles all transport modes. Pulls data from server via gRPC in REMOTE mode. Always fetches to CPU since the output is numpy arrays.

Parameters: •allocation (CIRAllocation) - The allocation (must have called get_cirs first)

Raises: RuntimeError - If get_cirs() has not populated the allocation yet or the CIR buffers cannot be fetched.

Returns: Nested dictionaries keyed by actual temporal index and RU index. The top-level keys are values, delays, angles_of_departure, and angles_of_arrival.
Return type: dict

Examples

1 cir = client.to_numpy_all_cir(alloc)
2 values = cir['values'][3][40]  # CIR values for slot 3, RU 40
3 aod = cir['angles_of_departure'][3][40]
4 aoa = cir['angles_of_arrival'][3][40]

CIRAllocation

Import path: dt_client.CIRAllocation

class dt_client.CIRAllocation()

CIR batch allocation returned by DigitalTwinClient.allocate_cirs_memory().

The primary payload is four CIR result buffers: values, delays, angles_of_departure, and angles_of_arrival. The allocation also stores the transport handles, per-time-step/per-RU shapes and offsets, the RU/UE configuration used for allocation, and lazy-fetch state for those buffers.

The allocation is reused by get_cirs(), to_numpy(), to_numpy_all_cir(), and deallocate_cirs_memory(). Users normally do not construct this class directly.

Buffer layout: Shapes and offsets are organized as [time_step_position][ru_position]. After get_cirs() succeeds, temporal_indices maps each time-step position to the actual slot or time-step index requested by SlotIndex, TimeStepIndex, SlotIndices, or TimeStepIndices.

Absolute buffer offsets are formed as *_time_step_offsets[ts_pos] + *_ru_offsets_per_ts[ts_pos][ru_pos]. Angle offsets are measured in float32 scalar elements because solver float2 entries are exposed as float32[..., 2] arrays.

NumPy tensor layouts are:

values: [rx][sample][rx_h][rx_v][rx_p][tx_h][tx_v][tx_p][tap]
delays: [rx][sample][rx_h][rx_v][tx_h][tx_v][tap]
angles_of_departure and angles_of_arrival: [rx][sample][rx_h][rx_v][tx_h][tx_v][tap][angle_component]

angle_component has size 2: index 0 is azimuth and index 1 is zenith, both in radians. angles_of_departure is defined in the TX panel’s local coordinate system; angles_of_arrival is defined in the RX panel’s local coordinate system. These layouts match the EM Solver API CIRResult indexing; the Python client exposes solver float2 angle entries as float32[..., 2] arrays and uses float32 scalar offsets for angle buffers.

Use get_values_shape(), get_delays_shape(), get_angles_of_departure_shape(), and get_angles_of_arrival_shape() to inspect the concrete shape for an actual (temporal, RU) pair. Shape dictionaries contain dimensions, total_elements, and dtype. The dtype is complex64 for values and float32 for delays and angle buffers.

Advanced helpers: use slot_to_pos(actual_temporal_index) and ru_to_pos(time_step_position, actual_ru_index) only when manually indexing the per-time-step, per-RU metadata arrays.

Properties

allocation_key

property dt_client.CIRAllocation.allocation_key

Server-side allocation key (for pull-based transfer)

angles_of_arrival_fetched

property dt_client.CIRAllocation.angles_of_arrival_fetched

Whether the AOA buffer has been fetched locally

angles_of_arrival_handle

property dt_client.CIRAllocation.angles_of_arrival_handle

IPC handle for AOA buffer (bytes)

angles_of_arrival_ru_offsets_per_ts

property dt_client.CIRAllocation.angles_of_arrival_ru_offsets_per_ts

Per-time-step, per-RU float32 element offsets (AOA)

angles_of_arrival_shapes_per_ts

property dt_client.CIRAllocation.angles_of_arrival_shapes_per_ts

Per-time-step, per-RU AOA shapes: list[list[dict]]

angles_of_arrival_time_step_offsets

property dt_client.CIRAllocation.angles_of_arrival_time_step_offsets

Cumulative float32 element offsets for each time step from buffer start (AOA)

angles_of_departure_fetched

property dt_client.CIRAllocation.angles_of_departure_fetched

Whether the AOD buffer has been fetched locally

angles_of_departure_handle

property dt_client.CIRAllocation.angles_of_departure_handle

IPC handle for AOD buffer (bytes)

angles_of_departure_ru_offsets_per_ts

property dt_client.CIRAllocation.angles_of_departure_ru_offsets_per_ts

Per-time-step, per-RU float32 element offsets (AOD)

angles_of_departure_shapes_per_ts

property dt_client.CIRAllocation.angles_of_departure_shapes_per_ts

Per-time-step, per-RU AOD shapes: list[list[dict]]

angles_of_departure_time_step_offsets

property dt_client.CIRAllocation.angles_of_departure_time_step_offsets

Cumulative float32 element offsets for each time step from buffer start (AOD)

delays_fetched

property dt_client.CIRAllocation.delays_fetched

Whether the delays buffer has been fetched locally

delays_handle

property dt_client.CIRAllocation.delays_handle

IPC handle for delays buffer (bytes)

delays_ru_offsets_per_ts

property dt_client.CIRAllocation.delays_ru_offsets_per_ts

Per-time-step, per-RU element offsets (delays)

delays_shapes_per_ts

property dt_client.CIRAllocation.delays_shapes_per_ts

Per-time-step, per-RU delay shapes: list[list[dict]]

delays_time_step_offsets

property dt_client.CIRAllocation.delays_time_step_offsets

Cumulative element offset for each time step from buffer start (delays)

is_full_antenna_pair

property dt_client.CIRAllocation.is_full_antenna_pair

Whether the allocation stores full antenna-pair outputs

num_time_steps

property dt_client.CIRAllocation.num_time_steps

Number of time-step positions in the allocation

ru_indices_per_ts

property dt_client.CIRAllocation.ru_indices_per_ts

RU indices for each time step position: list[list[int]]

temporal_indices

property dt_client.CIRAllocation.temporal_indices

Actual slot/timestep indices (set after get_cirs)

total_angles_of_arrival_bytes

property dt_client.CIRAllocation.total_angles_of_arrival_bytes

Total byte size of the AOA buffer

total_angles_of_departure_bytes

property dt_client.CIRAllocation.total_angles_of_departure_bytes

Total byte size of the AOD buffer

total_delays_bytes

property dt_client.CIRAllocation.total_delays_bytes

Total byte size of the delays buffer

total_values_bytes

property dt_client.CIRAllocation.total_values_bytes

Total byte size of the values buffer

transport_mode

property dt_client.CIRAllocation.transport_mode

Transport mode: ‘LOCAL_IPC’ or ‘REMOTE’

ue_indices_per_ts

property dt_client.CIRAllocation.ue_indices_per_ts

UE indices per RU for each time step: list[list[list[int]]]

values_fetched

property dt_client.CIRAllocation.values_fetched

Whether the values buffer has been fetched locally

values_handle

property dt_client.CIRAllocation.values_handle

IPC handle for values buffer (bytes)

values_ru_offsets_per_ts

property dt_client.CIRAllocation.values_ru_offsets_per_ts

Per-time-step, per-RU element offsets (values)

values_shapes_per_ts

property dt_client.CIRAllocation.values_shapes_per_ts

Per-time-step, per-RU value shapes: list[list[dict]]

values_time_step_offsets

property dt_client.CIRAllocation.values_time_step_offsets

Cumulative element offset for each time step from buffer start (values)

Methods

get_angles_of_arrival_offset

dt_client.CIRAllocation.get_angles_of_arrival_offset(
    slot_idx: int,
    ru_idx: int,
) -> int

Get per-RU float32 element offset for AOA within the time step

get_angles_of_arrival_shape

dt_client.CIRAllocation.get_angles_of_arrival_shape(
    slot_idx: int,
    ru_idx: int,
) -> dict

Get shape dict for AOA at (slot, ru)

get_angles_of_departure_offset

dt_client.CIRAllocation.get_angles_of_departure_offset(
    slot_idx: int,
    ru_idx: int,
) -> int

Get per-RU float32 element offset for AOD within the time step

get_angles_of_departure_shape

dt_client.CIRAllocation.get_angles_of_departure_shape(
    slot_idx: int,
    ru_idx: int,
) -> dict

Get shape dict for AOD at (slot, ru)

get_delays_offset

dt_client.CIRAllocation.get_delays_offset(
    slot_idx: int,
    ru_idx: int,
) -> int

Get per-RU element offset for delays within the time step

get_delays_shape

dt_client.CIRAllocation.get_delays_shape(
    slot_idx: int,
    ru_idx: int,
) -> dict

Get shape dict for delays at (slot, ru)

get_ru_indices_for_slot

dt_client.CIRAllocation.get_ru_indices_for_slot(
    slot_idx: int,
) -> list[int]

Get RU indices for a specific slot

get_values_offset

dt_client.CIRAllocation.get_values_offset(
    slot_idx: int,
    ru_idx: int,
) -> int

Get per-RU element offset for values within the time step

get_values_shape

dt_client.CIRAllocation.get_values_shape(
    slot_idx: int,
    ru_idx: int,
) -> dict

Get shape dict for values at (slot, ru)

has_ru

dt_client.CIRAllocation.has_ru(
    slot_idx: int,
    ru_idx: int,
) -> bool

Check if an RU exists for a given slot

has_slot

dt_client.CIRAllocation.has_slot(slot_idx: int) -> bool

Check if a slot/timestep index exists in the allocation

ru_to_pos

dt_client.CIRAllocation.ru_to_pos(
    ts_pos: int,
    ru_idx: int,
) -> int

Convert RU index to position within a time step

slot_to_pos

dt_client.CIRAllocation.slot_to_pos(slot_idx: int) -> int

Convert actual slot/timestep index to position

OSMTask

Import path: dt_client.OSMTask

class dt_client.OSMTask(
    output_folder_key: str,
    coords: tuple[float, float, float, float],
    include_elevation: bool,
    ground_source: str | None = 'terrarium',
    vegetation_source: str = 'procedural',
    vegetation_density: float = 50.0,
    vegetation_scale_min: float = 0.8,
    vegetation_scale_max: float = 1.2,
    cesium3dtiles_b3dm: bool | None = None,
    cesium3dtiles_draco: bool | None = None,
    cesium3dtiles_gzip: bool | None = None,
    cesium3dtiles_chunk_size: int | None = None,
    cesium3dtiles_veg_instanced: bool = True,
    rough: bool = True,
    disable_interiors: bool = False,
    terrain_clip_margin: float | None = None,
    terraform_config: dt_client.TerraformConfig | None = None,
)

PrepareMap task configuration for generating map assets from OSM data.

Use this class with DigitalTwinClient.prepare_map(). The coords argument is a bounding box in (min_lon, min_lat, max_lon, max_lat) order.

Examples

1 task = OSMTask(output_folder_key='maps/seattle', coords=(-122.34, 47.60, -122.33, 47.61), include_elevation=True)
2 result = client.prepare_map(task, s3_config)

Properties

cesium3dtiles_b3dm

property dt_client.OSMTask.cesium3dtiles_b3dm

Emit B3DM tiles instead of GLB.

cesium3dtiles_chunk_size

property dt_client.OSMTask.cesium3dtiles_chunk_size

Chunk size in meters for spatial partitioning (omit/None to disable).

cesium3dtiles_draco

property dt_client.OSMTask.cesium3dtiles_draco

Apply Draco mesh compression to GLB tiles. Requires cesium3dtiles_b3dm=false; auto-enabled when b3dm=false and this flag is not set explicitly.

cesium3dtiles_gzip

property dt_client.OSMTask.cesium3dtiles_gzip

Gzip-compress tile payloads. The hosting layer must set Content-Encoding: gzip.

cesium3dtiles_veg_instanced

property dt_client.OSMTask.cesium3dtiles_veg_instanced

Use GPU instancing for vegetation tiles (faster, smaller). Set false to fall back to baked mesh tiles.

coords

property dt_client.OSMTask.coords

Bounding box in degrees as (min_lon, min_lat, max_lon, max_lat).

disable_interiors

property dt_client.OSMTask.disable_interiors

Skip interior floor-slice generation for buildings.

ground_source

property dt_client.OSMTask.ground_source

Terrain source: ‘terrarium’ (default) or ‘srtm’. None lets asim_gis choose; for GML jobs the input CityGML’s TINRelief is used when present, with terrarium as a fallback.

include_elevation

property dt_client.OSMTask.include_elevation

Whether generated output includes elevation data.

output_folder_key

property dt_client.OSMTask.output_folder_key

S3 key prefix under the bucket; pipeline writes /sim and /viz subfolders here.

rough

property dt_client.OSMTask.rough

Legacy option. If creating a mobility mesh, make cuts inexact for better performance in some cases.

terraform_config

property dt_client.OSMTask.terraform_config

Optional TerraformConfig overrides. None lets asim_gis use its terrain-shaping defaults.

terrain_clip_margin

property dt_client.OSMTask.terrain_clip_margin

Clipping margin in meters beyond the building extent. None uses the asim_gis job default (200 m).

vegetation_density

property dt_client.OSMTask.vegetation_density

Trees per hectare for procedural vegetation.

vegetation_scale_max

property dt_client.OSMTask.vegetation_scale_max

Maximum random scale for procedural vegetation.

vegetation_scale_min

property dt_client.OSMTask.vegetation_scale_min

Minimum random scale for procedural vegetation.

vegetation_source

property dt_client.OSMTask.vegetation_source

Vegetation source method. Only ‘procedural’ is currently supported via the client; other values are accepted but produce no vegetation.

GMLTask

Import path: dt_client.GMLTask

class dt_client.GMLTask(
    output_folder_key: str,
    input_files: list[str],
    epsg_in: str,
    include_elevation: bool,
    epsg_out: str | None = None,
    ground_source: str | None = 'terrarium',
    vegetation_source: str = 'procedural',
    vegetation_density: float = 50.0,
    vegetation_scale_min: float = 0.8,
    vegetation_scale_max: float = 1.2,
    cesium3dtiles_b3dm: bool | None = None,
    cesium3dtiles_draco: bool | None = None,
    cesium3dtiles_gzip: bool | None = None,
    cesium3dtiles_chunk_size: int | None = None,
    cesium3dtiles_veg_instanced: bool = True,
    rough: bool = True,
    disable_interiors: bool = False,
    terrain_clip_margin: float | None = None,
    terraform_config: dt_client.TerraformConfig | None = None,
)

PrepareMap task configuration for generating map assets from GML files.

Use this class with DigitalTwinClient.prepare_map(). The input_files argument contains server-accessible GML input file paths. epsg_in is the input coordinate reference system, and epsg_out optionally requests a different output coordinate reference system.

Examples

1 task = GMLTask(output_folder_key='maps/city', input_files=['/data/city.gml'], epsg_in='4326', include_elevation=True)
2 result = client.prepare_map(task, s3_config)

Properties

cesium3dtiles_b3dm

property dt_client.GMLTask.cesium3dtiles_b3dm

Emit B3DM tiles instead of GLB.

cesium3dtiles_chunk_size

property dt_client.GMLTask.cesium3dtiles_chunk_size

Chunk size in meters for spatial partitioning (omit/None to disable).

cesium3dtiles_draco

property dt_client.GMLTask.cesium3dtiles_draco

Apply Draco mesh compression to GLB tiles. Requires cesium3dtiles_b3dm=false; auto-enabled when b3dm=false and this flag is not set explicitly.

cesium3dtiles_gzip

property dt_client.GMLTask.cesium3dtiles_gzip

Gzip-compress tile payloads. The hosting layer must set Content-Encoding: gzip.

cesium3dtiles_veg_instanced

property dt_client.GMLTask.cesium3dtiles_veg_instanced

Use GPU instancing for vegetation tiles (faster, smaller). Set false to fall back to baked mesh tiles.

disable_interiors

property dt_client.GMLTask.disable_interiors

Skip interior floor-slice generation for buildings.

epsg_in

property dt_client.GMLTask.epsg_in

Input EPSG code.

epsg_out

property dt_client.GMLTask.epsg_out

Optional output EPSG code.

ground_source

property dt_client.GMLTask.ground_source

Terrain source: ‘terrarium’ (default) or ‘srtm’. None lets asim_gis choose; for GML jobs the input CityGML’s TINRelief is used when present, with terrarium as a fallback.

include_elevation

property dt_client.GMLTask.include_elevation

Whether generated output includes elevation data.

input_files

property dt_client.GMLTask.input_files

Server-accessible GML input file paths.

output_folder_key

property dt_client.GMLTask.output_folder_key

S3 key prefix under the bucket; pipeline writes /sim and /viz subfolders here.

rough

property dt_client.GMLTask.rough

Legacy option. If creating a mobility mesh, make cuts inexact for better performance in some cases.

terraform_config

property dt_client.GMLTask.terraform_config

Optional TerraformConfig overrides. None lets asim_gis use its terrain-shaping defaults.

terrain_clip_margin

property dt_client.GMLTask.terrain_clip_margin

Clipping margin in meters beyond the building extent. None uses the asim_gis job default (200 m).

vegetation_density

property dt_client.GMLTask.vegetation_density

Trees per hectare for procedural vegetation.

vegetation_scale_max

property dt_client.GMLTask.vegetation_scale_max

Maximum random scale for procedural vegetation.

vegetation_scale_min

property dt_client.GMLTask.vegetation_scale_min

Minimum random scale for procedural vegetation.

vegetation_source

property dt_client.GMLTask.vegetation_source

Vegetation source method. Only ‘procedural’ is currently supported via the client; other values are accepted but produce no vegetation.

TerraformConfig

Import path: dt_client.TerraformConfig

class dt_client.TerraformConfig(
    terraform: bool | None = None,
    pad_radius: float | None = None,
    pre_tessellation_length: float | None = None,
    pre_smooth_terrain: bool | None = None,
    pre_smooth_iters: int | None = None,
    pre_smooth_lambda: float | None = None,
    terraform_smooth: bool | None = None,
    terraform_smooth_iters: int | None = None,
    terraform_smooth_lambda: float | None = None,
    terraform_smooth_radius: float | None = None,
    building_base_method: str | None = None,
    base_merge_distance: float | None = None,
    base_influence_radius: float | None = None,
    base_influence_sigma: float | None = None,
    base_smooth_iters: int | None = None,
    adaptive_bands: bool | None = None,
    near_radius: float | None = None,
    near_tessellation_threshold: float | None = None,
    far_tessellation_threshold: float | None = None,
)

Terrain shaping / building-base harmonization parameters. All fields are optional; None means ‘use the asim_gis default’.

Properties

adaptive_bands

property dt_client.TerraformConfig.adaptive_bands

Use adaptive near/far tessellation bands.

base_influence_radius

property dt_client.TerraformConfig.base_influence_radius

Radius of influence (m) for base-height blending.

base_influence_sigma

property dt_client.TerraformConfig.base_influence_sigma

Gaussian sigma (m) for base-height blending.

base_merge_distance

property dt_client.TerraformConfig.base_merge_distance

Distance threshold (m) for merging nearby building bases.

base_smooth_iters

property dt_client.TerraformConfig.base_smooth_iters

Number of base-height smoothing iterations.

building_base_method

property dt_client.TerraformConfig.building_base_method

How to set building base height: ‘min’ | ‘max’ | ‘average’ | ‘top10’ | ‘bottom10’.

far_tessellation_threshold

property dt_client.TerraformConfig.far_tessellation_threshold

Edge-length threshold (m) for far-band tessellation.

near_radius

property dt_client.TerraformConfig.near_radius

Near-band radius in meters.

near_tessellation_threshold

property dt_client.TerraformConfig.near_tessellation_threshold

Edge-length threshold (m) for near-band tessellation.

pad_radius

property dt_client.TerraformConfig.pad_radius

Building footprint padding radius in meters.

pre_smooth_iters

property dt_client.TerraformConfig.pre_smooth_iters

Number of pre-smooth iterations.

pre_smooth_lambda

property dt_client.TerraformConfig.pre_smooth_lambda

Smoothing lambda for the pre-smooth pass.

pre_smooth_terrain

property dt_client.TerraformConfig.pre_smooth_terrain

Smooth the terrain before terraforming.

pre_tessellation_length

property dt_client.TerraformConfig.pre_tessellation_length

Target edge length (m) for pre-terraform tessellation.

terraform

property dt_client.TerraformConfig.terraform

Change the shape of the terrain.

terraform_smooth

property dt_client.TerraformConfig.terraform_smooth

Smooth the terrain after terraforming.

terraform_smooth_iters

property dt_client.TerraformConfig.terraform_smooth_iters

Number of post-terraform smooth iterations.

terraform_smooth_lambda

property dt_client.TerraformConfig.terraform_smooth_lambda

Smoothing lambda for the post-terraform pass.

terraform_smooth_radius

property dt_client.TerraformConfig.terraform_smooth_radius

Smooth radius in meters (0 = global).

SlotIndex

Import path: dt_client.SlotIndex

class dt_client.SlotIndex(value: int)

Single temporal index for Slot/Symbols mode.

Use this wrapper when a client API expects one slot in a scenario that uses slot-based timing.

Examples

1 SlotIndex(5)

Properties

value

property dt_client.SlotIndex.value

Underlying slot index value.

TimeStepIndex

Import path: dt_client.TimeStepIndex

class dt_client.TimeStepIndex(value: int)

Single temporal index for Duration/Interval mode.

Use this wrapper when a client API expects one time step in a scenario that uses duration/interval timing.

Examples

1 TimeStepIndex(12)

Properties

value

property dt_client.TimeStepIndex.value

Underlying time-step index value.

SlotIndices

Import path: dt_client.SlotIndices

class dt_client.SlotIndices(values: list[int])

Multiple temporal indices for Slot/Symbols mode.

Use this wrapper when a client API accepts multiple slots in one call, such as batched CIR computation.

Examples

1 SlotIndices([0, 1, 2])

Properties

values

property dt_client.SlotIndices.values

Underlying slot index values.

TimeStepIndices

Import path: dt_client.TimeStepIndices

class dt_client.TimeStepIndices(values: list[int])

Multiple temporal indices for Duration/Interval mode.

Use this wrapper when a client API accepts multiple time steps in one call, such as batched CIR computation.

Examples

1 TimeStepIndices([0, 1, 2])

Properties

values

property dt_client.TimeStepIndices.values

Underlying time-step index values.