sim.utils#

Utility functions for the sim package.

Functions#

load_sim_launch_parameters(→ dict)

Load simulation launch parameters from YAML (sim/launch/launch_params.yaml).

load_yaml_to_dict(→ dict)

Load and validate YAML file.

load_sim_parameters(→ tuple[dict, pathlib.Path])

Find simulation configuration file, checking source location first (for development),

convert_parameter_value(→ Any)

Convert a parameter value to match its type annotation.

build_node_arguments(→ Dict[str, Any])

Build arguments dictionary for node initialization from parameters.

find_package_resource(→ pathlib.Path)

Find a package resource (file or directory), checking source location first (for development),

template_world_reference_candidates(→ list[pathlib.Path])

copy_models_to_gazebo(→ None)

Copy model files from source to Gazebo models directory.

camel_to_snake(→ str)

get_available_worlds(→ list[str])

Returns a list of the basenames of all of the sdf files in the given path

Module Contents#

load_sim_launch_parameters() → dict#

Load simulation launch parameters from YAML (sim/launch/launch_params.yaml).

load_yaml_to_dict(params_file: pathlib.Path) → dict#

Load and validate YAML file.

load_sim_parameters(competition: str, logger: logging.Logger, competition_name: str = '', mission_stage: str = '') → tuple[dict, pathlib.Path]#

Find simulation configuration file, checking source location first (for development), then falling back to installed location.

Simulation stages live under simulations/<competition_name>/. When mission_stage is provided the loader looks for <mission_stage>.yaml. When mission_stage is empty/omitted the loader uses base.yaml.

Parameters:

  • competition – Legacy competition selector retained for compatibility

  • logger – Logger instance

  • competition_name – Directory under simulations/ to resolve from

  • mission_stage – Optional mission stage name (e.g., ‘horizontal_takeoff’)

Returns:

Tuple of (parsed YAML dict, config file path (as string))

Raises:

FileNotFoundError – If config file cannot be found

convert_parameter_value(param_value: Any, param_annotation: Any, param_name: str) → Any#

Convert a parameter value to match its type annotation.

Parameters:

  • param_value – The parameter value (may be a string from YAML)

  • param_annotation – The type annotation from the function signature

  • param_name – The parameter name (for error messages)

Returns:

The converted parameter value

Raises:

ValueError – If conversion fails

build_node_arguments(node_class: type, params: Dict[str, Any]) → Dict[str, Any]#

Build arguments dictionary for node initialization from parameters.

Parameters:

  • node_class – The node class to instantiate

  • params – Dictionary of parameter values from config

Returns:

Dictionary of arguments ready to pass to node_class.__init__

Raises:

ValueError – If required parameters are missing or invalid

find_package_resource(relative_path: str | pathlib.Path, package_name: str = 'sim', resource_type: str = 'file', logger: Any | None = None, base_file: pathlib.Path | None = None) → pathlib.Path#

Find a package resource (file or directory), checking source location first (for development), then falling back to installed location.

This allows editing resources during development without needing to rebuild.

Parameters:

  • relative_path – Path relative to package root (e.g., ‘simulations/in_house.yaml’ or ‘world_gen/models’)

  • package_name – ROS2 package name (default: ‘sim’)

  • resource_type – ‘file’ or ‘directory’ (default: ‘file’)

  • logger – Optional logger for info messages (if None, no logging)

  • base_file – File to use as reference for source paths (typically Path(__file__) from caller)

Returns:

Path to the resource

Raises:

FileNotFoundError – If resource cannot be found

template_world_reference_candidates(template_world_path: str | pathlib.Path) → list[pathlib.Path]#
copy_models_to_gazebo(src_models_dir: pathlib.Path, dst_models_dir: pathlib.Path) → None#

Copy model files from source to Gazebo models directory.

Parameters:

  • src_models_dir – Source models directory

  • dst_models_dir – Destination models directory (Gazebo models path)

Raises:

OSError – If copy operations fail

camel_to_snake(name: str) → str#
get_available_worlds(path: str | pathlib.Path) → list[str]#

Returns a list of the basenames of all of the sdf files in the given path

Parameters:

path – Path to search

Returns:

List of available world names