Scene¶

The scene module provides classes for representing and managing physical objects in a wireless environment, including buildings, terrain, vegetation, and other structures that affect wireless propagation.

deepmimo/core/scene.py
  ├── BoundingBox (3D bounds)
  ├── Face (Surface representation)
  ├── PhysicalElement (Individual objects)
  ├── PhysicalElementGroup (Object collections)
  └── Scene (Complete environment)

The Scene class acts as a container for multiple PhysicalElement objects, each representing a distinct object in the environment. Each PhysicalElement is composed of Face objects, which define the surfaces of the element and are associated with materials. The BoundingBox class provides spatial boundaries for these elements. Together, these components allow for the representation and manipulation of complex environments, with functionalities for plotting and material management integrated into the scene.

The scene module depends on: - deepmimo.core.materials for material properties - deepmimo.utils for utility functions - NumPy for geometric computations - Matplotlib for visualization

BoundingBox¶

Dataclass for bounding boxes.

# Create a bounding box
bbox = dm.BoundingBox(x_min=0, x_max=10, y_min=0, y_max=5, z_min=0, z_max=3)

Property	Description
`x_min`	Minimum x-coordinate
`x_max`	Maximum x-coordinate
`y_min`	Minimum y-coordinate
`y_max`	Maximum y-coordinate
`z_min`	Minimum z-coordinate
`z_max`	Maximum z-coordinate
`width`	Width (X dimension) of the bounding box
`length`	Length (Y dimension) of the bounding box
`height`	Height (Z dimension) of the bounding box

Face¶

The Face class represents a single face (surface) of a physical object.

# Create a face
face = dm.Face(
    vertices=vertices,  # Array of vertex coordinates
    material_idx=1  # Material index
)

Represents a single face (surface) of a physical object.

This class implements a dual representation for faces: 1. Primary representation: Convex hull faces (stored in vertices) - More efficient for storage - Better for most geometric operations - Suitable for ray tracing and wireless simulations

Secondary representation: Triangular faces (generated on demand)
Available through triangular_faces property
Better for detailed visualization
Preserves exact geometry when needed
Generated using fan triangulation

This dual representation allows the system to be efficient while maintaining the ability to represent detailed geometry when required.

Initialize a face from its vertices.

Parameters:

Name	Type	Description	Default
`vertices`	`list[tuple[float, float, float]] \| ndarray`	List of (x, y, z) coordinates or numpy array of shape (N, 3) defining the face vertices in counter-clockwise order	required
`material_idx`	`int \| integer`	Index of the material for this face (default: 0)	`0`

vertices `instance-attribute` ¶

vertices = asarray(vertices, dtype=float32)

material_idx `instance-attribute` ¶

material_idx = int(material_idx)

normal `property` ¶

normal

Get the normal vector of the face.

triangular_faces `property` ¶

triangular_faces

Get the triangular faces that make up this face.

num_triangular_faces `property` ¶

num_triangular_faces

Get the number of triangular faces.

area `property` ¶

area

Get the area of the face.

centroid `property` ¶

centroid

Get the centroid of the face.

PhysicalElement¶

The PhysicalElement class represents individual physical objects in the scene.

There are standard categories for physical elements, used only to organize them:

Category	Description	Example Objects
`buildings`	Building structures	Houses, offices
`terrain`	Ground surfaces	Ground, hills
`vegetation`	Plant life	Trees, bushes
`floorplans`	Indoor layouts	Walls, rooms
`objects`	Other items	Cars, signs

# Create a physical object
element = dm.PhysicalElement(
    faces=faces,  # List of Face objects
    object_id=1,  # Unique identifier
    label='buildings',  # Object category
    name='Building 1'  # Optional name
)

# Access properties
height = element.height
volume = element.volume
position = element.position

Base class for physical objects in the wireless environment.

Initialize a physical object from its faces.

Parameters:

Name	Type	Description	Default
`faces`	`list[Face]`	List of Face objects defining the object	required
`object_id`	`int`	Unique identifier for the object (default: -1)	`-1`
`label`	`str`	Label identifying the type of object (default: 'objects')	`CAT_OBJECTS`
`color`	`str`	Color for visualization (default: '', which means use default color)	`''`
`name`	`str`	Optional name for the object (default: '')	`''`

DEFAULT_LABELS `class-attribute` ¶

DEFAULT_LABELS = {
    CAT_BUILDINGS,
    CAT_TERRAIN,
    CAT_VEGETATION,
    CAT_FLOORPLANS,
    CAT_OBJECTS,
}

object_id `instance-attribute` ¶

object_id = object_id

label `instance-attribute` ¶

label = label if label in DEFAULT_LABELS else CAT_OBJECTS

color `instance-attribute` ¶

color = color

name `instance-attribute` ¶

name = name

vertices `instance-attribute` ¶

vertices = all_vertices

bounding_box `instance-attribute` ¶

bounding_box

height `property` ¶

height

Get the height of the object.

faces `property` ¶

faces

Get the faces of the object.

hull `property` ¶

hull

Get the convex hull of the object.

hull_volume `property` ¶

hull_volume

Get the volume of the object using its convex hull.

hull_surface_area `property` ¶

hull_surface_area

Get the surface area of the object using its convex hull.

footprint_area `property` ¶

footprint_area

Get the area of the object's footprint using 2D convex hull.

volume `property` ¶

volume

Get the volume of the object using its convex hull.

position `property` ¶

position

Get the center of mass (position) of the object.

materials `property` ¶

materials

Get set of material indices used by this object.

vel `property` `writable` ¶

vel

Get the speed vector of the object in Cartesian coordinates [m/s].

to_dict ¶

to_dict(vertex_map)

Convert physical object to dictionary format.

Parameters:

Name	Type	Description	Default
`vertex_map`	`dict[tuple[float, ...], int]`	Dictionary mapping vertex tuples to their global indices	required

Returns:

Type	Description
`dict`	Dict containing object metadata with face vertex and material indices

from_dict `classmethod` ¶

from_dict(data, vertices)

Create physical object from dictionary format.

Parameters:

Name	Type	Description	Default
`data`	`dict`	Dictionary containing object data	required
`vertices`	`ndarray`	Array of vertex coordinates (shape: N_vertices x 3)	required

Returns:

Name	Type	Description
`PhysicalElement`	`PhysicalElement`	Created object

plot ¶

plot(ax=None, mode='faces', alpha=0.8, color=None)

Plot the object using the specified visualization mode.

Parameters:

Name	Type	Description	Default
`ax`	`Axes \| None`	Matplotlib 3D axes to plot on (if None, creates new figure)	`None`
`mode`	`Literal['faces', 'tri_faces']`	Visualization mode - either 'faces' or 'tri_faces' (default: 'faces')	`'faces'`
`alpha`	`float`	Transparency for visualization (default: 0.8)	`0.8`
`color`	`str \| None`	Color for visualization (default: None, uses object's color)	`None`

PhysicalElementGroup¶

The PhysicalElementGroup class manages collections of physical objects.

# Create a group
group = dm.PhysicalElementGroup(objects)

# Filter objects
buildings = group.get_objects(label='buildings')
metal = group.get_objects(material=1)

# Access objects
first = group[0]
subset = group[1:3]

Represents a group of physical objects that can be queried and manipulated together.

Initialize a group of physical objects.

bounding_box `property` ¶

bounding_box

Get the bounding box containing all objects.

get_materials ¶

get_materials()

Get list of material indices used by objects in this group.

get_objects ¶

get_objects(label=None, material=None)

Get objects filtered by label and/or material.

Parameters:

Name	Type	Description	Default
`label`	`str \| None`	Optional label to filter objects by	`None`
`material`	`int \| None`	Optional material index to filter objects by	`None`

Returns:

Type	Description
`PhysicalElementGroup`	PhysicalElementGroup containing filtered objects

Scene¶

The Scene class represents a complete physical environment containing multiple objects.

import deepmimo as dm

# Create a new scene
scene = dm.Scene()

# Add objects
scene.add_object(building)
scene.add_objects([tree1, tree2])

# Get objects by category
buildings = scene.get_objects(label='buildings')
metal_objects = scene.get_objects(material=1)  # material_id = 1

# Export scene data to dictionary
metadata_dict = scene.export_data()

# Load scene from dictionary
scene = dm.Scene.from_data(metadata_dict)

# 3D visualization
scene.plot(mode='faces')  # Use convex hull representation
scene.plot(mode='tri_faces')  # Use triangular representation

# 2D top-down view
scene.plot(proj_3D=False)

Represents a physical scene with various objects affecting wireless propagation.

Initialize an empty scene.

DEFAULT_VISUALIZATION_SETTINGS `class-attribute` ¶

DEFAULT_VISUALIZATION_SETTINGS = {
    CAT_TERRAIN: {
        "z_order": 1,
        "alpha": 0.1,
        "color": "black",
    },
    CAT_VEGETATION: {
        "z_order": 2,
        "alpha": 0.8,
        "color": "green",
    },
    CAT_BUILDINGS: {
        "z_order": 3,
        "alpha": 0.6,
        "color": None,
    },
    CAT_FLOORPLANS: {
        "z_order": 4,
        "alpha": 0.8,
        "color": "blue",
    },
    CAT_OBJECTS: {
        "z_order": 5,
        "alpha": 0.8,
        "color": "red",
    },
}

objects `instance-attribute` ¶

objects = DelegatingList()

visualization_settings `instance-attribute` ¶

visualization_settings = copy()

face_indices `instance-attribute` ¶

face_indices = []

bounding_box `property` ¶

bounding_box

Get the bounding box containing all objects.

set_visualization_settings ¶

set_visualization_settings(label, settings)

Set visualization settings for a specific label.

add_object ¶

add_object(obj)

Add a physical object to the scene.

Parameters:

Name	Type	Description	Default
`obj`	`PhysicalElement`	PhysicalElement to add	required

add_objects ¶

add_objects(objects)

Add multiple physical objects to the scene.

Parameters:

Name	Type	Description	Default
`objects`	`list[PhysicalElement]`	List of PhysicalElement objects to add	required

get_objects ¶

get_objects(label=None, material=None)

Get objects filtered by label and/or material.

Parameters:

Name	Type	Description	Default
`label`	`str \| None`	Optional label to filter objects by	`None`
`material`	`int \| None`	Optional material index to filter objects by	`None`

Returns:

Type	Description
`PhysicalElementGroup`	PhysicalElementGroup containing filtered objects

export_data ¶

export_data(base_folder)

Export scene data to files and return metadata dictionary.

Creates matrix files for vertices, faces and materials in the base folder. Returns a dictionary containing metadata needed to reload the scene.

Parameters:

Name	Type	Description	Default
`base_folder`	`str`	Base folder to store matrix files	required

Returns:

Type	Description
`dict`	Dict containing metadata needed to reload the scene

from_data `classmethod` ¶

from_data(base_folder)

Create scene from metadata dictionary and data files.

Parameters:

Name	Type	Description	Default
`base_folder`	`str`	Base folder containing matrix files	required

plot ¶

plot(
    *,
    title=True,
    mode="faces",
    ax=None,
    proj_3d=True,
    figsize=(10, 10),
    dpi=100,
    legend=False,
    **kwargs,
)

Create a visualization of the scene.

The scene can be visualized in either 2D (top-down view) or 3D mode:

3D Mode (proj_3d=True): Two representation options: 1. 'faces' (default) - Uses the primary convex hull representation - More efficient for visualization - Cleaner look for simple geometric shapes - Suitable for most visualization needs

2. 'tri_faces' - Uses the secondary triangular representation
- Shows detailed geometry
- Better for debugging geometric issues
- More accurate representation of complex shapes

2D Mode (proj_3d=False): Creates a top-down view showing object footprints: - Projects all objects onto x-y plane - Uses convex hulls for efficient visualization - Better for understanding spatial layout - More efficient for large scenes

Parameters:

Name	Type	Description	Default
`title`	`bool`	Whether to display the title (default: True)	`True`
`mode`	`Literal['faces', 'tri_faces']`	Visualization mode for 3D - either 'faces' or 'tri_faces' (default: 'faces')	`'faces'`
`ax`	`Axes \| None`	Matplotlib axes to plot on (if None, creates new figure)	`None`
`proj_3d`	`bool`	Whether to create 3D projection (default: True)	`True`
`**kwargs`	`Any`	Additional keyword-only options; accepts `proj_3D` alias.	`{}`
`figsize`	`tuple`	Figure dimensions (width, height) in inches (default: (10, 10))	`(10, 10)`
`dpi`	`int`	Plot resolution in dots per inch (default: 100)	`100`
`legend`	`bool`	Whether to show legend for objects/materials (default: False)	`False`

Returns:

Type	Description
`Axes`	matplotlib Axes object

count_objects_by_label ¶

count_objects_by_label()

Count the number of objects for each label in the scene.

Returns:

Type	Description
`dict[str, int]`	dict[str, int]: Dictionary mapping labels to their counts

Scene¶

BoundingBox¶

Face¶

vertices instance-attribute ¶

material_idx instance-attribute ¶

normal property ¶

triangular_faces property ¶

num_triangular_faces property ¶

area property ¶

centroid property ¶

PhysicalElement¶

DEFAULT_LABELS class-attribute ¶

object_id instance-attribute ¶

label instance-attribute ¶

color instance-attribute ¶

name instance-attribute ¶

vertices instance-attribute ¶

bounding_box instance-attribute ¶

height property ¶

faces property ¶

hull property ¶

hull_volume property ¶

hull_surface_area property ¶

footprint_area property ¶

volume property ¶

position property ¶

materials property ¶

vel property writable ¶

to_dict ¶

from_dict classmethod ¶

plot ¶

PhysicalElementGroup¶

bounding_box property ¶

get_materials ¶

get_objects ¶

Scene¶

DEFAULT_VISUALIZATION_SETTINGS class-attribute ¶

objects instance-attribute ¶

visualization_settings instance-attribute ¶

face_indices instance-attribute ¶

bounding_box property ¶

set_visualization_settings ¶

add_object ¶

add_objects ¶

get_objects ¶

export_data ¶

from_data classmethod ¶

plot ¶

count_objects_by_label ¶

vertices `instance-attribute` ¶

material_idx `instance-attribute` ¶

normal `property` ¶

triangular_faces `property` ¶

num_triangular_faces `property` ¶

area `property` ¶

centroid `property` ¶

DEFAULT_LABELS `class-attribute` ¶

object_id `instance-attribute` ¶

label `instance-attribute` ¶

color `instance-attribute` ¶

name `instance-attribute` ¶

vertices `instance-attribute` ¶

bounding_box `instance-attribute` ¶

height `property` ¶

faces `property` ¶

hull `property` ¶

hull_volume `property` ¶

hull_surface_area `property` ¶

footprint_area `property` ¶

volume `property` ¶

position `property` ¶

materials `property` ¶

vel `property` `writable` ¶

from_dict `classmethod` ¶

bounding_box `property` ¶

DEFAULT_VISUALIZATION_SETTINGS `class-attribute` ¶

objects `instance-attribute` ¶

visualization_settings `instance-attribute` ¶

face_indices `instance-attribute` ¶

bounding_box `property` ¶

from_data `classmethod` ¶