Actor Editor¶

Actor editing for scene manipulation.

The ActorEditor provides methods to edit individual actors (vehicles, pedestrians, etc.) in a scene. Access via scene.actor(id).

Example

>>> # Access an actor and apply transformations
>>> scene.actor(4).shift(left=2)
>>> scene.actor(4).displace(forward=10).rotate(yaw=15)

>>> # Method chaining for complex edits
>>> scene.actor(4) \
...     .displace(forward=10) \
...     .shift(left=2) \
...     .rotate(yaw=15) \
...     .stop(at_idx=50)

class mimic_scene_edition.editors.actor_editor.ActorEditor(root, actor_id, *, limited_mode=False, value_limits=None, editions=None)[source]¶

Bases: object

Editor for manipulating individual actors in a scene.

Provides comprehensive methods for transforming actor trajectories, controlling motion, and modifying actor properties. All transformation methods return self to enable fluent method chaining.

Parameters:

root (SceneEditor) – The parent scene editor that owns this actor.
actor_id (int) – The unique identifier of the actor to edit.
limited_mode (bool, optional) – If True, enable parameter value limit checking. Default is False.
value_limits (dict[str, tuple[float, float]] | None, optional) – Dictionary mapping parameter names to (min, max) bounds.
editions (list[EditionDict] | None, optional) – List to append edition records to.

Variables:

actor_id (int) – The actor’s unique identifier.
actor (Actor) – The underlying Actor object being edited.
traj (WorldTrajectory) – The actor’s trajectory.

Notes

ActorEditor instances should be obtained through SceneEditor.actor(id) rather than instantiated directly.

Examples

Basic translation:

>>> scene.actor(4).shift(left=2)  # Move 2m left
>>> scene.actor(4).shift(forward=5, up=0.5)  # Forward and up

Path displacement (moves along trajectory path):

>>> scene.actor(4).displace(forward=10)  # 10m ahead on path
>>> scene.actor(4).displace(forward=10).shift(left=2)  # Combine with lateral offset

Stop the actor:

>>> scene.actor(4).stop(at_idx=30)  # Stop at frame 30
>>> scene.actor(4).stop(at_idx=30, decel=0)  # Instant stop

Method chaining:

>>> scene.actor(4) \
...     .displace(forward=10) \
...     .shift(left=2) \
...     .rotate(yaw=15) \
...     .stop(at_idx=50)

__init__(root, actor_id, *, limited_mode=False, value_limits=None, editions=None)[source]¶

property actor_id: int¶

The actor’s unique identifier.

Returns:: The actor ID.
Return type:: int

property scene: Scene¶

The scene containing this actor.

Returns:: The parent scene object.
Return type:: Scene

property actor: Actor¶

The underlying Actor object.

Returns:: The actor being edited.
Return type:: Actor

property traj: WorldTrajectory¶

The actor’s trajectory.

Returns:: The actor’s world trajectory.
Return type:: WorldTrajectory

translate(**xyz)[source]¶

Translate the actor using semantic direction components.

Alias for shift(). Applies a local-frame translation using intuitive direction names.

Parameters:

**xyz (float) –

Named translation components:

forward: Distance forward (positive X) in meters
backward: Distance backward (negative X) in meters
left: Distance left (positive Y) in meters
right: Distance right (negative Y) in meters
up: Distance up (positive Z) in meters
down: Distance down (negative Z) in meters

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).translate(forward=5, left=2)

See also

shift: Primary translation method.

rotate(*, roll=0.0, pitch=0.0, yaw=0.0, referential='local', start_idx=None, end_idx=None)[source]¶

Rotate the actor using Euler angles.

Applies a rotation to the actor’s trajectory using roll-pitch-yaw Euler angles in degrees.

Parameters:

roll (float, optional) – Rotation around the X (forward) axis in degrees. Default is 0.
pitch (float, optional) – Rotation around the Y (left) axis in degrees. Default is 0.
yaw (float, optional) – Rotation around the Z (up) axis in degrees. Default is 0.
referential ({"local", "world"}, optional) –
Coordinate frame for the rotation:
- "local": Rotation in actor’s local frame (default).
- "world": Rotation in world frame.
start_idx (int | None, optional) – First frame to rotate (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to rotate (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).rotate(yaw=90)  # Turn 90° left
>>> scene.actor(4).rotate(yaw=180)  # Face opposite direction

See also

transform: Combined translation and rotation.

transform(*, left=0.0, right=0.0, up=0.0, down=0.0, forward=0.0, backward=0.0, roll=0.0, pitch=0.0, yaw=0.0, referential='local', start_idx=None, end_idx=None)[source]¶

Apply both translation and rotation in a single operation.

Combines translation and rotation into a single SE(3) transformation applied to the specified frame range.

Parameters:

left (float, optional) – Distance left (positive Y) in meters. Default is 0.
right (float, optional) – Distance right (negative Y) in meters. Default is 0.
up (float, optional) – Distance up (positive Z) in meters. Default is 0.
down (float, optional) – Distance down (negative Z) in meters. Default is 0.
forward (float, optional) – Distance forward (positive X) in meters. Default is 0.
backward (float, optional) – Distance backward (negative X) in meters. Default is 0.
roll (float, optional) – Rotation around X axis in degrees. Default is 0.
pitch (float, optional) – Rotation around Y axis in degrees. Default is 0.
yaw (float, optional) – Rotation around Z axis in degrees. Default is 0.
referential ({"local", "world"}, optional) –
Coordinate frame:
- "local": Transform in actor’s local axes (default).
- "world": Transform in world axes.
start_idx (int | None, optional) – First frame to transform (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to transform (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).transform(forward=5, left=2, yaw=15)

See also

shift: Translation only.
rotate: Rotation only.

shift(*, forward=0.0, backward=0.0, left=0.0, right=0.0, up=0.0, down=0.0, referential='local', start_idx=None, end_idx=None)[source]¶

Translate the actor using semantic direction components.

Pure translation using intuitive direction names. The coordinate system follows vehicle convention (x-forward, y-left, z-up).

Parameters:

forward (float, optional) – Distance forward (positive X) in meters. Default is 0.
backward (float, optional) – Distance backward (negative X) in meters. Default is 0.
left (float, optional) – Distance left (positive Y) in meters. Default is 0.
right (float, optional) – Distance right (negative Y) in meters. Default is 0.
up (float, optional) – Distance up (positive Z) in meters. Default is 0.
down (float, optional) – Distance down (negative Z) in meters. Default is 0.
referential ({"local", "world"}, optional) –
Coordinate frame:
- "local": Components in actor’s local axes (default). Applied as post-multiplication.
- "world": Components in world axes. Applied as pre-multiplication.
start_idx (int | None, optional) – First frame to shift (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to shift (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).shift(left=2)  # Move 2m left
>>> scene.actor(4).shift(forward=5, up=0.5)  # Forward and up
>>> scene.actor(4).shift(right=3, referential="world")  # In world coords

See also

translate: Alias for shift.
displace: Move along trajectory path.

object_appearance(enabled)[source]¶

Enable or disable the AutoSplat per-frame appearance residual for this actor.

The appearance residual carries the actor’s dynamic, per-frame look (brake lights, blinkers, and other view-dependent overlays). Muting it renders the actor with its static baseline appearance only.

This toggle only takes visible effect inside the rendering pipeline, which installs a callback via scene._object_appearance_sink. In a pure offline editor the call is still recorded in editions (so it replays with the rest of the edit history) but is otherwise a no-op.

Parameters:: enabled (bool) – True to render the per-frame appearance residual for this actor, False to mute it.
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> scene.actor(28).object_appearance(False)  # mute this actor
>>> scene.actor(28).object_appearance(True)   # restore it

See also

SceneEditor.object_appearance: Toggle every actor at once.

apply_T_sequence(T, *, start_idx=None, end_idx=None, referential='local')[source]¶

Apply a sequence of 4x4 transformation matrices.

Applies SE(3) transformation matrices to the actor’s trajectory poses in the specified frame range.

Parameters:

T (np.ndarray) – Transformation matrices with shape (4, 4) for a single transform applied to all frames, or (N, 4, 4) for per-frame transforms, one per scene frame in the window. An actor sampled off the frames reads each sample’s transform at the frame it falls on.
start_idx (int | None, optional) – First frame to transform (inclusive). None means 0.
end_idx (int | None, optional) – Last frame to transform (exclusive). None means end.
referential ({"local", "world"}, optional) –
How to apply the transformation:
- "local": Right-multiply (pose @ T). Default.
- "world": Left-multiply (T @ pose).

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> T = np.eye(4)
>>> T[:3, 3] = [1, 0, 0]  # Translation
>>> scene.actor(4).apply_T_sequence(T)

displace_along_forward(meters, *, start_idx=None, end_idx=None)[source]¶

Displace the actor along its trajectory path by arc-length.

Shortcut for displace(forward=meters).

Parameters:

meters (float) – Distance to displace in meters. Positive moves forward.
start_idx (int | None, optional) – First frame to displace (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to displace (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).displace_along_forward(10)  # 10m ahead on path

See also

displace: Displacement with named direction parameters.

displace(*, forward=0.0, backward=0.0, start_idx=None, end_idx=None)[source]¶

Move the actor along its trajectory path by arc-length.

Unlike shift(), this moves the actor along the path it’s already following, not in a straight line. This is useful for positioning actors relative to their motion path.

Parameters:

forward (float, optional) – Distance to move forward along path in meters. Default is 0.
backward (float, optional) – Distance to move backward along path in meters. Default is 0.
start_idx (int | None, optional) – First frame to displace (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to displace (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).displace(forward=10)  # 10m ahead on path
>>> scene.actor(4).displace(backward=5)  # 5m behind on path

>>> # Combine with shift for lateral offset
>>> scene.actor(4).displace(forward=10).shift(left=2)

See also

shift: Straight-line translation.
displace_along_forward: Shortcut with single distance parameter.

move_forward(*, start_idx, speed)[source]¶

Make the actor move forward at a constant speed.

Modifies the trajectory so the actor moves forward at the specified speed from the given frame index.

Parameters:

start_idx (int) – Frame index to start the constant motion.
speed (float) – Speed in meters per second.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).move_forward(start_idx=10, speed=5.0)  # 5 m/s from frame 10

stop(at_idx, *, duration=None, decel=10, profile='min_jerk')[source]¶

Stop the actor at a specific frame.

Brings the actor to a stop at the specified frame index, optionally with a smooth deceleration profile.

Parameters:

at_idx (int) – Frame index to stop at. If decel > 0, this is where the deceleration ends (actor becomes stationary).
duration (int | None, optional) – Number of frames to stay stopped. If None, the actor remains stopped until the end of the trajectory.
decel (int, optional) – Number of frames for gradual deceleration. Use 0 for instant stop. Default is 10.
profile ({"linear", "min_jerk"}, optional) –
Deceleration profile:
- "linear": Linear velocity reduction.
- "min_jerk": Smooth minimum-jerk profile (default).

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).stop(at_idx=30)  # Stop at frame 30
>>> scene.actor(4).stop(at_idx=30, decel=0)  # Instant stop
>>> scene.actor(4).stop(at_idx=30, duration=50)  # Stop for 50 frames

See also

make_static_at: Make completely static at a position.

spin(*, period_s=None, rpm=None, axis='z', start_idx=None, end_idx=None)[source]¶

Apply continuous rotation (spinning) to the actor.

Makes the actor rotate continuously around the specified axis.

Parameters:

period_s (float | None, optional) – Seconds per full revolution. Mutually exclusive with rpm.
rpm (float | None, optional) – Revolutions per minute. Mutually exclusive with period_s.
axis ({"x", "y", "z"}, optional) – Rotation axis. Default is "z" (vertical).
start_idx (int | None, optional) – First frame to apply spin (inclusive). None means all frames.
end_idx (int | None, optional) – Last frame to apply spin (exclusive). None means all frames.

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).spin(rpm=60, axis="z")  # Spin at 60 RPM

make_static_at(*, at_idx=0)[source]¶

Make the actor completely static at a specific frame’s position.

Anchors the actor’s trajectory at the specified frame, making the actor remain completely stationary at that position for the entire duration.

Parameters:: at_idx (int, optional) – Frame index to anchor the trajectory at. Default is 0.
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> scene.actor(4).make_static_at(at_idx=0)  # Freeze at initial position

See also

stop: Stop with optional deceleration.

offset_frames(offset_frames)[source]¶

Shift the actor’s timeline by a number of frames.

Performs a circular shift of the trajectory, wrapping around at the boundaries.

Parameters:: offset_frames (int) – Number of frames to shift. Positive values shift forward.
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> scene.actor(4).offset_frames(5)  # Shift 5 frames forward

resample(hz)[source]¶

Resample the trajectory to a target frame rate.

Interpolates the trajectory to produce poses at a uniform temporal spacing determined by the specified frequency.

Parameters:: hz (float) – Target frame rate in Hz (frames per second).
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> scene.actor(4).resample(hz=20)  # Resample to 20 Hz

See also

resample_to_times: Resample to specific timestamps.

resample_to_times(new_t)[source]¶

Resample the trajectory to specific timestamps.

Interpolates poses to the specified query timestamps.

Parameters:: new_t (np.ndarray) – Array of target timestamps to sample at.
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> new_times = np.linspace(0, 10, 100)
>>> scene.actor(4).resample_to_times(new_times)

See also

resample: Resample to a uniform frame rate.

slice(start_idx, end_idx)[source]¶

Keep only frames in the specified range.

Truncates the trajectory to contain only poses within the specified index range.

Parameters:

start_idx (int) – First frame to keep (inclusive).
end_idx (int) – Last frame to keep (exclusive).

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).slice(10, 50)  # Keep frames 10-49

Raises:: ValueError – If the window holds none of the actor’s samples — which would leave it with no trajectory at all.

speed(multiplier)[source]¶

Change the actor’s apparent speed by retiming timestamps.

Adjusts trajectory timestamps to change perceived speed without modifying the spatial path.

Parameters:

multiplier (float) –

Speed scaling factor:

> 1: Faster (double speed with 2.0)
< 1: Slower (half speed with 0.5)

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).speed(multiplier=2.0)  # Double speed
>>> scene.actor(4).speed(multiplier=0.5)  # Half speed

replace_trajectory(traj)[source]¶

Replace the actor’s entire trajectory.

Substitutes the current trajectory with a new one. Velocities are recomputed automatically.

Parameters:: traj (WorldTrajectory) – The new trajectory to use.
Returns:: Self for method chaining.
Return type:: ActorEditor

Examples

>>> new_traj = create_custom_trajectory()
>>> scene.actor(4).replace_trajectory(new_traj)

set_dimensions(*, length=None, width=None, height=None)[source]¶

Modify the actor’s bounding box dimensions.

Updates the actor’s physical dimensions. Only provided parameters are updated.

Parameters:

length (float | None, optional) – New length in meters (X dimension).
width (float | None, optional) – New width in meters (Y dimension).
height (float | None, optional) – New height in meters (Z dimension).

Returns:

Self for method chaining.

Return type:

ActorEditor

Examples

>>> scene.actor(4).set_dimensions(length=4.5, width=1.8)

duplicate(*, forward=0.0, backward=0.0)[source]¶

Create a copy of the actor with optional displacement.

Creates a deep copy of the actor, optionally displaced along its trajectory path. The copy is not inserted into the scene; use scene.insert_actor() to add it.

Parameters:

forward (float, optional) – Distance to displace forward on path in meters. Default is 0.
backward (float, optional) – Distance to displace backward on path in meters. Default is 0.

Returns:

A new Actor object (not yet in scene).

Return type:

Actor

Examples

>>> new_actor = scene.actor(4).duplicate(forward=20)
>>> new_id = scene.insert_actor(new_actor)

See also

SceneEditor.insert_actor: Insert the duplicated actor.
SceneEditor.duplicate_actor: Duplicate and insert in one step.