Survey capture

Move through taught viewpoints and record camera clouds, TF, and joint states for a survey. The --dry-run option still commands motion.

scripts.survey_mapping.run_survey · Source

Perception and mapping · Guide · Symbol index

How it is used

Use this script after teaching survey viewpoints and starting the configured robot, MoveIt, and Zivid services. main() manages the recorder and node; SurveyRunner.run() visits the poses, waits for settling, and requests each capture. Joint values in the pose YAML are degrees.

The runner sends goals directly to beambot_moveto, outside the orchestrator task queue. Its --dry-run option still moves the arm: it skips camera settings, capture, and bag recording.

Start here

Callable	Purpose
main	Validate the survey options, prepare the ROS node and optional recorder, run the selected viewpoints, and clean up. Camera settings and recording are skipped in dry-run mode; movement is not.
SurveyRunner.run	Visit poses in order, wait after each successful movement, and capture unless `dry_run` is set. Stop on movement failure; continue to later viewpoints after a failed capture.
SurveyRunner.move_to	Send one named joint-space MoveToAction with an inline one-pose JSON registry; wait for acceptance and completion, requesting cancellation after the movement timeout.
SurveyRunner.capture	Request a capture and wait for the received-cloud count to increase. A failed Trigger response only logs a warning; a new cloud can still make the call succeed, without proving that it belongs to this request.

Functions

`main()`

Validate the survey options, prepare the ROS node and optional recorder, run the selected viewpoints, and clean up. Camera settings and recording are skipped in dry-run mode; movement is not.

Entry point · Source

main()

Returns: 0 for full success, 1 for invalid inputs, endpoint/recorder failure, interrupted or incomplete survey.

Errors: Argparse exits for invalid numeric constraints; pose-read failures return 1. KeyboardInterrupt is reported; unexpected runtime errors propagate after cleanup once inside the try block.

Side effects: May move hardware even with –dry-run; normal mode can change camera settings and create a bag. Destroys node, shuts down ROS and stops recorder.

`start_bag()`

Start ros2 bag record in a new process session for survey clouds, TF and joint states.

Lifecycle · Source

start_bag(output, qos_override)

Parameter	Meaning
`output`	Bag output directory argument passed after -o.
`qos_override`	QoS override file path; falsey omits the override flag.

Returns: subprocess.Popen recorder handle; startup success is checked later by main().

Errors: Popen launch errors propagate; does not check output/path validity here.

Side effects: Spawns a recording process, prints its command and causes bag files to be written.

Referenced in source (1)

main — scripts.survey_mapping.run_survey

`stop_bag()`

Finalize a running recorder by sending SIGINT to its process group, escalating to terminate and kill if waits expire.

Lifecycle · Source

stop_bag(process)

Parameter	Meaning
`process`	Popen returned by start_bag, or None; completed processes are ignored.

Returns: None after the process ends or is already absent.

Errors: Suppresses ProcessLookupError; escalates after 15 seconds, then five seconds. Other signal/wait errors propagate.

Side effects: Signals the recorder, waits for exit and lets it finalize its bag.

Referenced in source (1)

main — scripts.survey_mapping.run_survey

Internal callbacks and helpers

`default_settings_file()`

Prefer the installed beambot config/zivid/manufacturing_specular.yml when present, then fall back to the source-tree config location.

Internal helper · Source

default_settings_file()

Returns: Path to an existing installed file, otherwise an unchecked source-tree Path.

Errors: Any installed-package lookup exception is suppressed; fallback existence is not validated here.

Side effects: Queries package metadata and tests a file path.

Referenced in source (1)

main — scripts.survey_mapping.run_survey

`load_poses()`

Load a YAML name-to-six-joint mapping, keeping entries with string names and six finite float-convertible values in input order.

Internal helper · Source

load_poses(path)

Parameter	Meaning
`path`	YAML pose file path; angles are degrees in arm-joint order.

Returns: Dictionary of valid names to six float degree values; empty/null YAML becomes {}.

Errors: ValueError for a nonmapping document; malformed entries are skipped with stderr warnings; file/YAML errors propagate.

Side effects: Reads the pose file and may print warnings.

Referenced in source (1)

main — scripts.survey_mapping.run_survey

`SurveyRunner`

A ROS node that coordinates direct MoveTo goals and Zivid captures. Movement failure stops the sequence; a failed capture allows later viewpoints to proceed.

Inherits from: Node.

`SurveyRunner.run()`

Visit poses in order, wait after each successful movement, and capture unless dry_run is set. Stop on movement failure; continue to later viewpoints after a failed capture.

Method · Source

run(self, poses)

Parameter	Meaning
`poses`	Ordered mapping of pose name to six joint angles in degrees.

Returns: True iff all entries completed; an empty mapping succeeds.

Errors: Returns False on first movement failure or any capture failure; unexpected exceptions propagate.

Side effects: Commands arm movement, sleeps args.settle seconds, triggers captures and logs progress.

`SurveyRunner.move_to()`

Send one named joint-space MoveToAction with an inline one-pose JSON registry; wait for acceptance and completion, requesting cancellation after the movement timeout.

Method · Source

move_to(self, name, joints)

Parameter	Meaning
`name`	Pose name used as goal.target and JSON mapping key.
`joints`	Six arm joint angles in degrees, passed unchanged into goal.poses_json.

Returns: True only for an accepted goal whose returned result.success is true; otherwise False.

Errors: 15-second acceptance timeout/rejection, result timeout or failed/missing result are logged and return False. On movement timeout waits up to five seconds for cancellation; future exceptions propagate.

Side effects: Commands robot motion through beambot_moveto, spins ROS and may cancel the goal.

Referenced in source (1)

SurveyRunner.run — scripts.survey_mapping.run_survey

`SurveyRunner.capture()`

Request a capture and wait for the received-cloud count to increase. A failed Trigger response only logs a warning; a new cloud can still make the call succeed, without proving that it belongs to this request.

Method · Source

capture(self, name)

Parameter	Meaning
`name`	Pose label used in diagnostic messages.

Returns: True when a Trigger response arrives and any new subscribed cloud is observed; False on service-result or cloud timeout.

Errors: Uses args.capture_timeout and args.cloud_timeout seconds; timeout failures are logged. Future exceptions propagate.

Side effects: Triggers Zivid acquisition and spins ROS; does not verify the new cloud’s timestamp or source request.

Referenced in source (1)

SurveyRunner.run — scripts.survey_mapping.run_survey

`SurveyRunner.init()`

Create the survey_runner ROS node, movement action client, capture Trigger client and reliable depth-one cloud subscription.

Lifecycle · Source

__init__(self, args)

Parameter	Meaning
`args`	Parsed options namespace used for dry_run, settings_file, settle and movement/capture/cloud timeout seconds.

Returns: None; starts cloud_count at zero.

Errors: ROS construction failures propagate.

Side effects: Registers ROS node, clients and subscription.

Referenced in source (1)

main — scripts.survey_mapping.run_survey

`SurveyRunner.wait_for_servers()`

Wait up to 15 seconds for beambot_moveto, then up to 15 seconds for /capture unless dry_run is enabled.

Method · Source

wait_for_servers(self)

Returns: True if required endpoints are available, False after a timeout.

Errors: Endpoint timeouts are logged and converted to False; ROS errors propagate.

Side effects: Performs ROS discovery waits and logs availability failures.

`SurveyRunner.apply_settings()`

Set zivid_camera settings_file_path to the resolved settings file and clear settings_yaml. Missing file/service or unsuccessful response leaves the survey running.

Method · Source

apply_settings(self)

Returns: None regardless of whether settings were applied.

Errors: Missing file, 10-second service timeout, response timeout or rejected parameters produce warnings; unexpected service/future errors propagate.

Side effects: Reads file existence, creates a parameter client, requests camera parameter changes and logs results; non-atomic parameter application may partly succeed.

Internal callbacks and helpers

`SurveyRunner._on_cloud()`

Count each received point cloud so capture() can observe a new message.

Callback · Source

_on_cloud(self, _message)

Parameter	Meaning
`_message`	Received PointCloud2; payload and timestamp are intentionally ignored.

Returns: None.

Errors: No explicit error handling.

Side effects: Increments cloud_count.

Referenced in source (1)

SurveyRunner.__init__ — scripts.survey_mapping.run_survey

Survey capture

How it is used

Start here

Functions

main()

start_bag()

stop_bag()

Internal callbacks and helpers

default_settings_file()

load_poses()

SurveyRunner

SurveyRunner.run()

SurveyRunner.move_to()

SurveyRunner.capture()

SurveyRunner.__init__()

SurveyRunner.wait_for_servers()

SurveyRunner.apply_settings()

Internal callbacks and helpers

SurveyRunner._on_cloud()

`main()`

`start_bag()`

`stop_bag()`

`default_settings_file()`

`load_poses()`

`SurveyRunner`

`SurveyRunner.run()`

`SurveyRunner.move_to()`

`SurveyRunner.capture()`

`SurveyRunner.init()`

`SurveyRunner.wait_for_servers()`

`SurveyRunner.apply_settings()`

`SurveyRunner._on_cloud()`