ros_sugar.robot.mapping#

Mapping capability descriptors.

A robot plugin declares how maps of its environment get built. Mapping is a one-off, operator-driven activity that produces a file on disk, so it is driven from the EMOS CLI.

A declaration is read through python -m ros_sugar.robot inspect.

Two kinds:

  • VendorMapping – the robot ships its own SLAM, reached by running a vendor tool. The plugin supplies the argv and where the results land.

  • NativeMapping – EMOS maps the environment itself from the plugin’s own LiDAR and IMU feedbacks.

A plugin that declares neither simply cannot be mapped, and the CLI says so.

Module Contents#

Classes#

VendorMapping

Mapping performed by the robot’s own software.

NativeMapping

Mapping performed by EMOS from the plugin’s own sensor feedbacks.

API#

class ros_sugar.robot.mapping.VendorMapping#

Bases: ros_sugar.config.BaseAttrs

Mapping performed by the robot’s own software.

The commands are argv lists rather than shell strings. {name} is substituted with the map name at call time.

Parameters:

  • start – Begin a mapping session.

  • stop – End the session and save. A clean exit code does not mean the map was written – what settles it is the map appearing in the store.

  • stop_retries – How many extra times to re-issue stop if the map has not appeared. Only for vendors that document stop as safe to repeat and sometimes needing it; the default of 0 issues it once.

  • store – Directory holding every map on the robot.

  • grid – Occupancy-grid YAML filename inside a map directory. The default is the ROS map_server convention, which is also what Kompass’s MapServer loads.

  • cloud – Point-cloud filename inside a map directory.

  • apply – Make a map the active one. None if the vendor offers no such command.

  • after_apply – Run after apply – typically restarting the vendor’s localization service, without which the switch silently does not take effect.

  • export – Package a map for copying off the robot. Vendors commonly only package the active map and take no argument, so {name} and {path} are optional here.

  • export_dir – Where export leaves the archive, when the vendor chooses the path itself. Empty means unknown, and the caller reports only that the command ran.

  • import_ – Unpack an archive produced by export into the store. {path} is substituted with the archive’s absolute path. Trailing underscore because import is a keyword; it is import in spec.

  • remove – Delete a map. None where the vendor offers no such command, in which case the map directory is removed directly.

  • active_link – Name of the symlink in store pointing at the active map.

  • requires_root – Whether any command here escalates privilege. Purely a capability hint: the dashboard cannot drive such a provider, because its daemon has no terminal for a password prompt, so it directs the operator to the CLI instead. It does not shape the commands – escalation belongs in the argv, because it is per-verb. DEEP Robotics, for instance, documents sudo on mapping and apply but not on pack, and prefixing it anyway would leave a root-owned archive the operator cannot delete.

  • host – "local" when the commands run on the machine EMOS is installed on, otherwise "ssh://user@host".

  • area_limit_m – Largest square area the vendor supports, in metres, if documented. Advisory only; shown to the operator before they start.

active_grid_path() → Optional[str]#

Absolute path of the active map’s occupancy-grid YAML, or None.

grid is preferred when it names a file that exists, otherwise the sole .yaml in the directory is taken; an ambiguous directory returns None rather than guessing.

property kind: str#

Discriminator for consumers reading a describe tree.

spec() → Dict[str, Any]#

JSON-serializable introspection record, tagged with kind.

asdict(filter: Optional[Callable] = None) → Dict#

Convert class to dict.

Return type:

dict

to_dict() → Dict#

Convert class to dict.

Return type:

dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:

Fields that differ from the defaults

Return type:

dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

  • ValueError – If attribute_name in dictionary does not exists in class attributes

  • TypeError – If attribute_value type in dictionary does not correspond to class attribute type

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

Update class attributes from yaml, json, or toml

Parameters:

  • file_path – Path to config file (.yaml, .json, .toml)

  • nested_root_name – Nested root name for the config, defaults to None

  • get_common – Whether to get extra config root (for merging), defaults to False

to_json() → Union[str, bytes, bytearray]#

Dump to json

Returns:

description

Return type:

str | bytes | bytearray

from_json(json_obj: Union[str, bytes, bytearray]) → None#

Gets attributes values from given json

Parameters:

json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:

attr_name (str) – description

Returns:

If object has attribute with given name

Return type:

bool

get_attribute_type(attr_name: str) → Optional[type]#

Gets type of given attribute name

Parameters:

attr_name (str) – description

Raises:

AttributeError – If class does not have attribute with given name

Returns:

Attribute type

Return type:

type

update_value(attr_name: str, attr_value: Any) → bool#

Updates the value of an attribute in the class

Parameters:

  • attr_name (str) – Attribute name - can be nested name

  • attr_value (Any) – Attribute value

Raises:

  • AttributeError – If class does not contain attribute with given name

  • TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:

A dictionary where keys are field names and values are dicts of metadata.

class ros_sugar.robot.mapping.NativeMapping#

Bases: ros_sugar.config.BaseAttrs

Mapping performed by EMOS from the plugin’s own sensor feedbacks.

The inputs are named by feedback key, not by topic, so the plugin stays the single source of truth for what the topic actually is and a topic rename does not invalidate this declaration.

Parameters:

  • cloud – Feedback key of the LiDAR point cloud.

  • imu – Feedback key of an IMU mounted with the LiDAR, at a rate suitable for LiDAR-inertial odometry – typically the one inside the LiDAR itself. A robot-state IMU arriving at 10 Hz over telemetry is far too slow. None means no IMU is available, which limits EMOS to a LiDAR-only backend and degrades the result on a robot whose gait pitches the sensor.

  • z_min – Bottom of the height band kept when flattening the 3D map to an occupancy grid, in metres above the base frame’s ground plane. Anything below is floor.

  • z_max – Top of that band. Anything above cannot obstruct the robot.

  • resolution – Grid cell size in metres.

  • imu_xyz – Position of the IMU in the LiDAR’s frame, in metres, for an IMU built into the LiDAR unit: the driver stamps both streams with the LiDAR’s frame, so nothing else carries this offset. From the sensor’s datasheet. None leaves the backend’s default.

  • imu_rpy – Orientation of the IMU in the LiDAR’s frame, in radians.

  • custom_settings – Mapping backend settings that can be sensor-specific. e.g. {"preprocess": {"k_correspondences": 20}} for a 16-beam LiDAR. They win over EMOS’s indoor and outdoor defaults.

active_grid_path() → Optional[str]#

Absolute path of the active map’s occupancy-grid YAML, or None.

Same contract as VendorMapping.active_grid_path, so a recipe can ask either provider the same question.

property kind: str#

Discriminator for consumers reading a describe tree.

spec() → Dict[str, Any]#

JSON-serializable introspection record, tagged with kind.

asdict(filter: Optional[Callable] = None) → Dict#

Convert class to dict.

Return type:

dict

to_dict() → Dict#

Convert class to dict.

Return type:

dict

asdict_explicit() → Dict#

Convert to dict, keeping only what differs from the class defaults.

See explicit_fields, which this defers to.

Returns:

Fields that differ from the defaults

Return type:

dict

from_dict(dict_obj: Dict) → None#

Gets attributes values from given dictionary

Parameters:

dict_obj (Dict) – Dictionary {attribute_name: attribute_value}

Raises:

  • ValueError – If attribute_name in dictionary does not exists in class attributes

  • TypeError – If attribute_value type in dictionary does not correspond to class attribute type

from_file(file_path: str, nested_root_name: Union[str, None] = None, get_common: bool = False) → bool#

Update class attributes from yaml, json, or toml

Parameters:

  • file_path – Path to config file (.yaml, .json, .toml)

  • nested_root_name – Nested root name for the config, defaults to None

  • get_common – Whether to get extra config root (for merging), defaults to False

to_json() → Union[str, bytes, bytearray]#

Dump to json

Returns:

description

Return type:

str | bytes | bytearray

from_json(json_obj: Union[str, bytes, bytearray]) → None#

Gets attributes values from given json

Parameters:

json_obj (str | bytes | bytearray) – Json object

has_attribute(attr_name: str) → bool#

Checks if class object has attribute with given name

Parameters:

attr_name (str) – description

Returns:

If object has attribute with given name

Return type:

bool

get_attribute_type(attr_name: str) → Optional[type]#

Gets type of given attribute name

Parameters:

attr_name (str) – description

Raises:

AttributeError – If class does not have attribute with given name

Returns:

Attribute type

Return type:

type

update_value(attr_name: str, attr_value: Any) → bool#

Updates the value of an attribute in the class

Parameters:

  • attr_name (str) – Attribute name - can be nested name

  • attr_value (Any) – Attribute value

Raises:

  • AttributeError – If class does not contain attribute with given name

  • TypeError – If class attribute with given name if of different type

Returns:

If attribute value is updated

Return type:

bool

classmethod get_fields_info(class_object) → Dict[str, Dict[str, Any]]#

Returns a dictionary with metadata about each field in the class.

This includes the field’s name, type annotation, and parsed validator info.

Returns:

A dictionary where keys are field names and values are dicts of metadata.