Moving Sources (Beta)

Trajectory

The TrajectoryGenerator class provides a collection of predefined geometric shapes and utilities for generating motion trajectories. These built-in generators allow users to quickly create common movement patterns such as linear paths, circular motions, and other parametric shapes.

For more advanced scenarios, multiple trajectories can be concatenated to construct complex motion paths. This enables the creation of hybrid trajectories composed of sequential segments with different geometries or motion characteristics.

Among the available options, the TrajectoryGenerator.polyline() function is generally recommended for defining custom moving paths. It allows users to specify a sequence of control points along the desired route, offering a flexible and intuitive way to describe arbitrary motion. Additionally, a corner-rounding option can be applied to ensure smooth transitions between segments, avoiding abrupt directional changes and enabling more physically realistic movement.

While Polyline provides the highest level of flexibility for custom paths, several other predefined geometric shapes remain available and may be more convenient for standard or analytically defined trajectories.

Trajectory direction

For most trajectory generators, the direction is therefore implicitly defined by the input arguments. Generators with explicit start and end points (e.g. line, quadratic_bezier, L_shape, Z_shape, random) move from the start point toward the end point. For multi-point generators such as polyline, the movement follows the order of the points provided in the input list. Concatenated trajectories preserve the order of the concatenated segments.

Some generators introduce additional direction controls. For the semicircle, the direction parameter (1 or -1) determines the turning direction within the plane defined by the normal vector. Using the right-hand rule with the normal vector, direction 1 produces a counter-clockwise turn and direction -1 a clockwise turn (when looking along the normal direction). Currently, closed trajectories (e.g. circle, figure8, spiral) follow the direction defined by their internal parameterization.

Several usage examples are provided below to illustrate typical trajectory configurations and composition workflows.

# Model loaded from Treble library
model = tsdk.geometry_library.get_dataset("Apartments")[261]

# Polyline 
# The direction of the trajectory movement follows the order of the points in the list. 
# For example, it starts at point 1 and ends at the last point.
points = [
    Point3d(2,6,1.2),
    Point3d(-2.5, 5.96, 1.2),
    Point3d(-2.5, 3.8, 1.2),
    Point3d(2, 3.8, 1.2),
    Point3d(2, -3.4,1.2),
    Point3d(-1, -3.4,1.2)
   
]
traj_polyline = TrajectoryGenerator.polyline(points=points,corner_radius=1)

# Semicircle
traj_semicircle = TrajectoryGenerator.semicircle(start_point=Point3d(-1,-3.4,1.2), radius=1.3,direction=1)

# Circle
traj_circle = TrajectoryGenerator.circle(center=Point3d(-0.56, 3.07, 1.7), radius=1.5)

# Bezier curve
traj_bezier = TrajectoryGenerator.quadratic_bezier(start=Point3d(2, 3.8, 1.2),
                                                   control=Point3d(0, 3.8, 1.2),
                                                   end=Point3d(2, 1, 1.2))

# Spiral 
traj_spiral = TrajectoryGenerator.spiral(Point3d(-0.56, 3.07, 1.5), a=0.2,b=0.1,turns=2)


# Concatenation of different trajectories
traj_concat = traj_polyline.concat([traj_semicircle])

Creating a Moving Source

Defining the Orientation

A moving source is created by assigning a trajectory to it. The source can be either omnidirectional or directional; in the latter case, an orientation must also be specified.

The orientation of a moving source is specified using one of the orientation methods. The following options are available:

• fixed_orientation() — assigns a constant orientation for the entire trajectory.

• look_at() — orients the source toward a fixed point in space.

• look_at_keyframes() — defines look-at targets at specific percentages along the trajectory, enabling piecewise orientation control.

• look_ahead() — automatically aligns the source with the instantaneous direction of travel.

Each of these methods returns a TrajectoryOrientation object, which can then be provided when defining the moving source.

orientation_look_ahead = traj_polyline.look_ahead()

Creating the Moving Source

To define a moving source, the following methods are available:

• make_moving_directive() — creates a moving source with a specified directivity pattern and associated orientation along the trajectory.

• make_moving_omni() — creates a moving omnidirectional source that follows the trajectory without requiring orientation.

• make_omni_boundary_velocity_submodel() — creates an omnidirectional boundary velocity submodel for moving-source simulations, typically used when modeling sources represented through boundary-based formulations.

These constructors provide flexibility in defining both physically directive and omnidirectional moving sources, depending on the intended simulation setup. In the given example, a moving speeach directive source is created.

natural_directivities = tsdk.source_directivity_library.query( 
    category=treble.SourceDirectivityCategory.natural,
    sub_category=treble.SourceDirectivityNatural.speech,
)   
speech_directivity = natural_directivities[0]

moving_source_speech = [treble.Source.make_moving_directive( 
    trajectory=traj_polyline, 
    orientation = orientation_look_ahead,
    label='moving_speech', 
    source_directivity=speech_directivity
)]

The created moving source is then used a source in simulaiton definition.

sim_def = treble.SimulationDefinition(
        name="Simulation",
        simulation_type=treble.SimulationType.ga,
        model=model, 
        energy_decay_threshold=40, 
        receiver_list=receiver, 
        source_list=moving_source_speech,
        material_assignment=material_assignments 
)