Core API

This page documents the simulator-agnostic Python API surface exposed by the refactored package layout.

Scene Subpackage

Public scene-definition types and YAML I/O exports.

class simkit.core.scene.Camera(position, target, fov, near_clip, far_clip)[source][source]

Bases: object

Camera configuration.

Parameters:

  • position (Vector3)

  • target (Vector3)

  • fov (float)

  • near_clip (float)

  • far_clip (float)

far_clip: float
fov: float
get_view_direction()[source][source]

Get camera view direction.

Return type:

Vector3

near_clip: float
position: Vector3
target: Vector3
validate()[source][source]

Validate camera properties.

Return type:

bool

class simkit.core.scene.CollisionProperties(enabled, shape, size)[source][source]

Bases: object

Collision properties for objects.

Parameters:

  • enabled (bool)

  • shape (str)

  • size (List[float])

enabled: bool
shape: str
size: List[float]
validate()[source][source]

Validate collision properties.

Return type:

bool

class simkit.core.scene.Color(r, g, b, a=1.0)[source][source]

Bases: object

RGBA color representation.

Parameters:

  • r (float)

  • g (float)

  • b (float)

  • a (float)

a: float = 1.0
b: float
g: float
r: float
to_rgb()[source][source]

Convert to RGB tuple (0-255).

Return type:

tuple[int, int, int]

to_rgba()[source][source]

Convert to RGBA tuple (0-255).

Return type:

tuple[int, int, int, int]

class simkit.core.scene.DirectionalLight(direction, color, intensity)[source][source]

Bases: object

Directional light configuration.

Parameters:
color: Color
direction: Vector3
intensity: float
validate()[source][source]

Validate directional light properties.

Return type:

bool

class simkit.core.scene.Environment(gravity, wind, time_step)[source][source]

Bases: object

Environment settings for the scene.

Parameters:
gravity: Vector3
time_step: float
validate()[source][source]

Validate environment settings.

Return type:

bool

wind: Vector3
class simkit.core.scene.Lighting(ambient, directional)[source][source]

Bases: object

Lighting configuration.

Parameters:
ambient: Color
directional: List[DirectionalLight]
validate()[source][source]

Validate lighting configuration.

Return type:

bool

class simkit.core.scene.PhysicsProperties(mass, friction, restitution)[source][source]

Bases: object

Physics properties for objects.

Parameters:

  • mass (float)

  • friction (float)

  • restitution (float)

friction: float
mass: float
restitution: float
validate()[source][source]

Validate physics properties.

Return type:

bool

class simkit.core.scene.Quaternion(x, y, z, w)[source][source]

Bases: object

Quaternion rotation representation.

Parameters:

  • x (float)

  • y (float)

  • z (float)

  • w (float)

conjugate()[source][source]

Get quaternion conjugate.

Return type:

Quaternion

magnitude()[source][source]

Get quaternion magnitude.

Return type:

float

normalize()[source][source]

Get normalized quaternion.

Return type:

Quaternion

w: float
x: float
y: float
z: float
class simkit.core.scene.Scene(name, description, version, environment, objects, lighting, camera)[source][source]

Bases: object

Complete scene definition.

Parameters:
camera: Camera
description: str
environment: Environment
get_object_by_name(name)[source][source]

Get object by name.

Return type:

Optional[SceneObject]

Parameters:

name (str)

get_objects_by_type(obj_type)[source][source]

Get all objects of a specific type.

Return type:

List[SceneObject]

Parameters:

obj_type (str)

get_total_mass()[source][source]

Get total mass of all objects in the scene.

Return type:

float

lighting: Lighting
name: str
objects: List[SceneObject]
validate()[source][source]

Validate entire scene.

Return type:

bool

version: str
class simkit.core.scene.SceneObject(name, type, position, rotation, scale, physics, visual, collision)[source][source]

Bases: object

Object in the scene.

Parameters:
collision: CollisionProperties
get_world_transform()[source][source]

Get world transformation matrix data.

Return type:

Dict[str, Any]

name: str
physics: PhysicsProperties
position: Vector3
rotation: Quaternion
scale: Vector3
type: str
validate()[source][source]

Validate scene object.

Return type:

bool

visual: VisualProperties
class simkit.core.scene.SceneReader[source][source]

Bases: object

Reader for YAML scene definition files.

static load_scene(file_path)[source][source]

Load a scene from a YAML file.

Parameters:

file_path (str) – Path to the YAML scene definition file

Return type:

Scene

Returns:

Scene object containing all scene data

Raises:

  • FileNotFoundError – If the file doesn’t exist

  • yaml.YAMLError – If the YAML is invalid

  • KeyError – If required fields are missing

class simkit.core.scene.SceneWriter[source][source]

Bases: object

Writer for saving scenes to YAML files.

static save_scene(scene, file_path)[source][source]

Save a scene to a YAML file.

Parameters:

  • scene (Scene) – Scene object to save

  • file_path (str) – Path where to save the YAML file

Raises:

IOError – If the file cannot be written

Return type:

None

class simkit.core.scene.Vector3(x, y, z)[source][source]

Bases: object

3D vector representation.

Parameters:

  • x (float)

  • y (float)

  • z (float)

magnitude()[source][source]

Get vector magnitude.

Return type:

float

normalize()[source][source]

Get normalized vector.

Return type:

Vector3

x: float
y: float
z: float
class simkit.core.scene.VisualProperties(mesh, material, color)[source][source]

Bases: object

Visual properties for objects.

Parameters:

  • mesh (str)

  • material (str)

  • color (Color)

color: Color
has_mesh()[source][source]

Check if object has a mesh file.

Return type:

bool

material: str
mesh: str

Scene Types

Dataclasses and helper types for structured scene definitions.

class simkit.core.scene.scene_types.Camera(position, target, fov, near_clip, far_clip)[source][source]

Bases: object

Camera configuration.

Parameters:

  • position (Vector3)

  • target (Vector3)

  • fov (float)

  • near_clip (float)

  • far_clip (float)

far_clip: float
fov: float
get_view_direction()[source][source]

Get camera view direction.

Return type:

Vector3

near_clip: float
position: Vector3
target: Vector3
validate()[source][source]

Validate camera properties.

Return type:

bool

class simkit.core.scene.scene_types.CollisionProperties(enabled, shape, size)[source][source]

Bases: object

Collision properties for objects.

Parameters:

  • enabled (bool)

  • shape (str)

  • size (List[float])

enabled: bool
shape: str
size: List[float]
validate()[source][source]

Validate collision properties.

Return type:

bool

class simkit.core.scene.scene_types.Color(r, g, b, a=1.0)[source][source]

Bases: object

RGBA color representation.

Parameters:

  • r (float)

  • g (float)

  • b (float)

  • a (float)

a: float = 1.0
b: float
g: float
r: float
to_rgb()[source][source]

Convert to RGB tuple (0-255).

Return type:

tuple[int, int, int]

to_rgba()[source][source]

Convert to RGBA tuple (0-255).

Return type:

tuple[int, int, int, int]

class simkit.core.scene.scene_types.DirectionalLight(direction, color, intensity)[source][source]

Bases: object

Directional light configuration.

Parameters:
color: Color
direction: Vector3
intensity: float
validate()[source][source]

Validate directional light properties.

Return type:

bool

class simkit.core.scene.scene_types.Environment(gravity, wind, time_step)[source][source]

Bases: object

Environment settings for the scene.

Parameters:
gravity: Vector3
time_step: float
validate()[source][source]

Validate environment settings.

Return type:

bool

wind: Vector3
class simkit.core.scene.scene_types.Lighting(ambient, directional)[source][source]

Bases: object

Lighting configuration.

Parameters:
ambient: Color
directional: List[DirectionalLight]
validate()[source][source]

Validate lighting configuration.

Return type:

bool

class simkit.core.scene.scene_types.PhysicsProperties(mass, friction, restitution)[source][source]

Bases: object

Physics properties for objects.

Parameters:

  • mass (float)

  • friction (float)

  • restitution (float)

friction: float
mass: float
restitution: float
validate()[source][source]

Validate physics properties.

Return type:

bool

class simkit.core.scene.scene_types.Quaternion(x, y, z, w)[source][source]

Bases: object

Quaternion rotation representation.

Parameters:

  • x (float)

  • y (float)

  • z (float)

  • w (float)

conjugate()[source][source]

Get quaternion conjugate.

Return type:

Quaternion

magnitude()[source][source]

Get quaternion magnitude.

Return type:

float

normalize()[source][source]

Get normalized quaternion.

Return type:

Quaternion

w: float
x: float
y: float
z: float
class simkit.core.scene.scene_types.Scene(name, description, version, environment, objects, lighting, camera)[source][source]

Bases: object

Complete scene definition.

Parameters:
camera: Camera
description: str
environment: Environment
get_object_by_name(name)[source][source]

Get object by name.

Return type:

Optional[SceneObject]

Parameters:

name (str)

get_objects_by_type(obj_type)[source][source]

Get all objects of a specific type.

Return type:

List[SceneObject]

Parameters:

obj_type (str)

get_total_mass()[source][source]

Get total mass of all objects in the scene.

Return type:

float

lighting: Lighting
name: str
objects: List[SceneObject]
validate()[source][source]

Validate entire scene.

Return type:

bool

version: str
class simkit.core.scene.scene_types.SceneObject(name, type, position, rotation, scale, physics, visual, collision)[source][source]

Bases: object

Object in the scene.

Parameters:
collision: CollisionProperties
get_world_transform()[source][source]

Get world transformation matrix data.

Return type:

Dict[str, Any]

name: str
physics: PhysicsProperties
position: Vector3
rotation: Quaternion
scale: Vector3
type: str
validate()[source][source]

Validate scene object.

Return type:

bool

visual: VisualProperties
class simkit.core.scene.scene_types.Vector3(x, y, z)[source][source]

Bases: object

3D vector representation.

Parameters:

  • x (float)

  • y (float)

  • z (float)

magnitude()[source][source]

Get vector magnitude.

Return type:

float

normalize()[source][source]

Get normalized vector.

Return type:

Vector3

x: float
y: float
z: float
class simkit.core.scene.scene_types.VisualProperties(mesh, material, color)[source][source]

Bases: object

Visual properties for objects.

Parameters:

  • mesh (str)

  • material (str)

  • color (Color)

color: Color
has_mesh()[source][source]

Check if object has a mesh file.

Return type:

bool

material: str
mesh: str

Scene Reader

YAML readers and writers for structured scene definitions.

class simkit.core.scene.scene_reader.SceneReader[source][source]

Bases: object

Reader for YAML scene definition files.

static load_scene(file_path)[source][source]

Load a scene from a YAML file.

Parameters:

file_path (str) – Path to the YAML scene definition file

Return type:

Scene

Returns:

Scene object containing all scene data

Raises:

  • FileNotFoundError – If the file doesn’t exist

  • yaml.YAMLError – If the YAML is invalid

  • KeyError – If required fields are missing

class simkit.core.scene.scene_reader.SceneWriter[source][source]

Bases: object

Writer for saving scenes to YAML files.

static save_scene(scene, file_path)[source][source]

Save a scene to a YAML file.

Parameters:

  • scene (Scene) – Scene object to save

  • file_path (str) – Path where to save the YAML file

Raises:

IOError – If the file cannot be written

Return type:

None