Download as Python script

Download as Jupyter notebook

Download example’s assets

How to create a component#

This tutorial demonstrates how to create a component feature.

Component feature includes: lightbox import.

Prerequisites#

Perform imports#

[1]:

import json
from pathlib import Path

[2]:

from ansys.speos.core import OptProp, Project, Speos, launcher
from ansys.speos.core.component import LightBox, LightBoxFileInstance
from ansys.speos.core.kernel.client import (
    default_docker_channel,
)
from ansys.speos.core.simulation import SimulationDirect
from ansys.speos.core.source import SourceSurface

Define constants#

The constants help ensure consistency and avoid repetition throughout the example.

[3]:

HOSTNAME = "localhost"
GRPC_PORT = 50098  # Be sure the Speos GRPC Server has been started on this port.
USE_DOCKER = True  # Set to False if you're running this example locally as a Notebook.
FILES = "CameraInputFiles"

Define helper functions#

These helpers keep LightBox output concise for documentation. Detailed nested content is truncated because it is not the focus of this example.

[4]:

def _truncate_json_value(value, *, max_depth=3, max_list_items=8, max_dict_items=12, _depth=0):
    """Truncate nested JSON-like data for readable output.

    Parameters
    ----------
    value : Any
        Input value to truncate.
    max_depth : int, default: 3
        Maximum nesting depth to keep.
    max_list_items : int, default: 8
        Maximum number of items kept per list.
    max_dict_items : int, default: 12
        Maximum number of keys kept per dictionary.
    _depth : int, default: 0
        Current recursion depth. This parameter is for internal use.

    Returns
    -------
    Any
        Truncated representation of the input value.
    """
    if _depth >= max_depth:
        if isinstance(value, dict):
            return {"...": f"{len(value)} keys hidden"}
        if isinstance(value, list):
            return [f"... {len(value)} items hidden"]
        return value

    if isinstance(value, dict):
        items = list(value.items())
        out = {
            key: _truncate_json_value(
                sub_value,
                max_depth=max_depth,
                max_list_items=max_list_items,
                max_dict_items=max_dict_items,
                _depth=_depth + 1,
            )
            for key, sub_value in items[:max_dict_items]
        }
        hidden = len(items) - max_dict_items
        if hidden > 0:
            out["..."] = f"{hidden} more keys"
        return out

    if isinstance(value, list):
        out = [
            _truncate_json_value(
                item,
                max_depth=max_depth,
                max_list_items=max_list_items,
                max_dict_items=max_dict_items,
                _depth=_depth + 1,
            )
            for item in value[:max_list_items]
        ]
        hidden = len(value) - max_list_items
        if hidden > 0:
            out.append(f"... {hidden} more items")
        return out

    return value


def print_lightbox_compact(lightbox, *, max_depth=3, max_list_items=8):
    """Print a compact LightBox representation.

    Parameters
    ----------
    lightbox : ansys.speos.core.component.LightBox
        LightBox feature to print.
    max_depth : int, default: 3
        Maximum nesting depth kept in the printed JSON payload.
    max_list_items : int, default: 8
        Maximum number of items shown per list in the printed payload.

    Returns
    -------
    None
        This function prints formatted output and returns nothing.

    Notes
    -----
    The optional ``"local: "`` prefix from ``str(lightbox)`` is preserved.
    """
    out_str = str(lightbox)
    prefix = ""
    payload = out_str
    if out_str.startswith("local: "):
        prefix = "local: "
        payload = out_str[len(prefix) :]

    try:
        payload_dict = json.loads(payload)
    except json.JSONDecodeError:
        # Fallback to default string output if it is not valid JSON.
        print(out_str)
        return

    compact_payload = _truncate_json_value(
        payload_dict,
        max_depth=max_depth,
        max_list_items=max_list_items,
    )
    print(prefix + json.dumps(compact_payload, indent=4))

Model Setup#

Load assets#

The assets used to run this example are available in the PySpeos repository on GitHub.

Note: Make sure you have downloaded the simulation assets and set assets_data_path to point to the assets’ folder.

[5]:

if USE_DOCKER:  # Running on the remote server.
    assets_data_path = Path("/app") / "assets"
else:
    assets_data_path = Path("/path/to/your/download/assets/directory")

Connect to the RPC Server#

This Python client connects to a server where the Speos engine is running as a service. In this example, the server and client are the same machine. The launch_local_speos_rpc_method can be used to start a local instance of the service.

[6]:

if USE_DOCKER:
    speos = Speos(channel=default_docker_channel())
else:
    speos = launcher.launch_local_speos_rpc_server(port=GRPC_PORT)

/home/runner/work/pyspeos/pyspeos/.venv/lib/python3.14/site-packages/ansys/tools/common/cyberchannel.py:188: UserWarning: Starting gRPC client without TLS on localhost:50098. This is INSECURE. Consider using a secure connection.
  warn(f"Starting gRPC client without TLS on {target}. This is INSECURE. Consider using a secure connection.")

Create a new project#

The only way to create a lightbox import, is to create it from a project.

[7]:

p = Project(speos=speos)
print(p)

{
    "name": "",
    "description": "",
    "metadata": {},
    "part_guid": "",
    "sub_scene_anchor_axis_system": [],
    "sources": [],
    "sensors": [],
    "simulations": [],
    "materials": [],
    "scenes": []
}

Create#

Create locally

The mention “local: “ is added when printing the lightbox

[8]:

lightbox = p.create_lightbox(
    name="Light Box Import.1",
    lightbox=LightBoxFileInstance(
        file=assets_data_path / "lightbox" / "Light Box Export.2.SPEOSLightBox", password=""
    ),
)
print_lightbox_compact(lightbox)

local: {
    "name": "Light Box Import.1",
    "axis_system": [
        0.0,
        0.0,
        0.0,
        1.0,
        0.0,
        0.0,
        0.0,
        1.0,
        "... 4 more items"
    ],
    "display_name": "",
    "description": "",
    "metadata": {},
    "scene_guid": "",
    "trajectory_file_uri": ""
}

/home/runner/work/pyspeos/pyspeos/.venv/lib/python3.14/site-packages/ansys/speos/core/project.py:1231: UserWarning: The pySpeos feature : FaceStub.read_batch needs a Speos Version of 2025 R2 SP0 or higher.
  f_data_list = face_db.read_batch(refs=f_links)
/home/runner/work/pyspeos/pyspeos/.venv/lib/python3.14/site-packages/ansys/speos/core/project.py:1338: UserWarning: The pySpeos feature : SourceSurface needs a Speos Version of 2025 R2 SP0 or higher.
  src_feat = SourceSurface(

Push it to the server.#

Now that it is committed to the server, the mention “local: “ is no more present when printing the lightbox.

[9]:

lightbox.commit()
print_lightbox_compact(lightbox)

{
    "name": "Light Box Import.1",
    "metadata": {
        "UniqueId": "788e3104-331a-43e1-9a53-a2bcc60b29de"
    },
    "scene_guid": "daaf2f33-ef81-485b-a817-94ba3fd01dfa",
    "axis_system": [
        0.0,
        0.0,
        0.0,
        1.0,
        0.0,
        0.0,
        0.0,
        1.0,
        "... 4 more items"
    ],
    "display_name": "",
    "description": "",
    "trajectory_file_uri": "",
    "scene": {
        "name": "Light Box Export.2",
        "description": "From Speos Light Box: /app/assets/lightbox/Light Box Export.2.SPEOSLightBox",
        "part_guid": "a960dac2-7d99-453a-ab75-9a76b26154c8",
        "sources": [
            {
                "...": "7 keys hidden"
            }
        ],
        "materials": [
            {
                "...": "8 keys hidden"
            }
        ],
        "metadata": {},
        "sub_scene_anchor_axis_system": [],
        "sensors": [],
        "simulations": [],
        "scenes": [],
        "part": {
            "name": "RootPart",
            "body_guids": [
                "... 1 items hidden"
            ],
            "description": "",
            "metadata": {
                "...": "0 keys hidden"
            },
            "parts": [
                "... 0 items hidden"
            ],
            "bodys": [
                "... 1 items hidden"
            ]
        }
    }
}

How to create a component#

Prerequisites#

Perform imports#

Define constants#

Define helper functions#

Model Setup#

Load assets#

Connect to the RPC Server#

Create a new project#

Create#

Push it to the server.#

Read#

Lightbox Instance#

Source and Bodies instance inside Lightbox#

Modify lightbox features#

feature instance modify method#

lightbox instance as global modify method#

Lightbox sources in simulation#

Adding lightbox sources in simulation#

Black Lightbox#