package bosdyn.api.graph_nav
Get desktop application:
View/edit binary Protocol Buffers messages
Retrieve information about how to operate the service, including what lease resources are required by the navigation callback.
message
area_callback.proto:44Message for requesting information about a area callback implementation.
optional header = 1
Common request header.
message
area_callback.proto:143Message for providing information about a area callback implementation.
optional header = 1
Common response header.
optional info = 2
Information about how the AreaCallback should be called.
BeginCallback is called once as the robot enters a AreaCallback region of a map. This call initializes the navigation callback for operation.
message
area_callback.proto:169optional header = 1
Common request header.
optional region_info = 4
Description of the region we are going to cross.
optional end_time = 3
The timestamp (in robot time) by which a command must finish executing. If unset, a AreaCallback implementation may pick a reasonable value.
optional recorded_data = 5
Deprecated in 4.1, the relevant data is set in custom_params and config_data instead. Configuration data associated with this area callback region
optional custom_params = 6
Any other custom parameters to the callback.
optional config_data = 7
Custom config data used by the service to do its job.
BeginControl is called once after the area callback implementation requests control. Control is handed off (via a lease) from the caller to the area callback.
message
area_callback.proto:225optional header = 1
Common request header.
repeated leases = 2
Leases that a AreaCallback uses once it takes control of the robot. This list should match AreaCallbackInformation required_lease_resources.
uint32 command_id = 3
The command id associated with a single execution of a navigation callback.
UpdateCallback is called periodically while the callback is running. Area callback implementations use UpdateCallback to dictate how caller should operate while callback is running (pause, continue, etc.)
message
area_callback.proto:265optional header = 1
Common request header.
uint32 command_id = 2
The command id associated with a single execution of a navigation callback.
optional end_time = 3
If set, update the end time (in robot time) by which a command must finish executing.
UpdateCallbackRequest.Stage stage = 4
Called only if the route changes in the middle of the region (for example, if the robot is blocked by an obstacle and re-routes).
message
area_callback.proto:421optional header = 1
Common request header.
uint32 command_id = 2
The command id for which the route is changing.
optional route = 3
The new planned route through the region.
optional unfinished_route = 4
The remaining old route that was not completed.
message
area_callback.proto:441optional header = 1
Common response header.
RouteChangeResponse.Status status = 2
EndCallback is called once when the caller decides the navigation callback is over. This might be because the robot exited the callback region or might be because the callback reported that it finished doing work.
message
area_callback.proto:387optional header = 1
Common request header.
uint32 command_id = 2
The command id associated with a single execution of a navigation callback.
The recording service can be used to record a Graph Nav map (containing waypoints and edges). The recorded map can consist of the following: * Chain: a topological arrangement of waypoints/edges where every waypoint has at least 1 but at most 2 edges attached to it. * Branch: separate Chains can be joined together into a Branch at exactly one waypoint. When recording a map using the recording service, a common pattern is: * Call StartRecording to begin recording a chain of waypoints. * Call SetRecordingEnvironment to define persistent annotations for the edges and waypoints. * While recording, call GetRecordStatus to get feedback on the state of the recording service. * While recording, call GetMapStatus to determine what waypoints have been created. * Optionally call CreateWaypoint to create waypoints in specific locations. * Call StopRecording to pause the recording service and create branches. * While recording (or after completing recording), call DownloadWaypoint/Edge Snapshot rpcs from the GraphNavService to download the large sensor data with the map.
Start recording the map from the current localization. Creates a waypoint if you are starting to record. Otherwise, waits until you are sufficiently far away from the previous waypoint.
message
recording.proto:60The StartRecording request tells the recording service to begin creating waypoints with the specified recording_environment.
optional header = 1
Common request header.
optional lease = 2
The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
optional recording_environment = 3
This will be merged into a copy of the existing persistent recording environment and used as the environment for the created waypoint and the edge from the previous waypoint to the new one. It will not affect the persistent environment.
repeated int32 require_fiducials = 4
If filled out, asks that the record service verify that the given fiducial IDs are presently visible before starting to record. This is useful for verifying that the robot is where the user thinks it is in an area with known fiducials.
optional session_start_time = 5
If provided, this timestamp will be used in every waypoint snapshot as the "started_recording_on" timestamp. Otherwise, a new timestamp will be generated after "StartRecording" is called. This is to allow association between waypoint snapshots based on recording session time.
message
recording.proto:84The StartRecording response message returns the first created waypoint, which is made at the location the robot was standing when the request was made, in addition to any status information.
optional header = 1
Common response header.
optional created_waypoint = 2
The waypoint that was just created.
optional lease_use_result = 3
The results/status of the lease provided.
StartRecordingResponse.Status status = 4
Return status for the request.
repeated int32 missing_fiducials = 5
If the status is STATUS_MISSING_FIDUCIALS, these are the fiducials that are not currently visible.
repeated int32 bad_pose_fiducials = 7
If the status is STATUS_FIDUCIAL_POSE_NOT_OK, these are the fiducials that could not be localized confidently.
LicenseInfo.Status license_status = 6
Large graphs can only be uploaded if the license permits them. Recording will stop automatically when the graph gets too large. If StartRecording is requested again after the graph gets too large, it will fail, and license status will be filled out.
optional impaired_state = 8
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
optional session_start_time = 9
This is the robot local timestamp that graph_nav began recording on. If the Start Recording Request's session start time is provided, this should be the same as the request's session start time.
optional map_stats = 10
General statistics of the map loaded in GraphNav.
Stop recording the map from the current localization.
message
recording.proto:152The StopRecording request message tells the robot to no longer continue adding waypoints and edges to the graph.
optional header = 1
Common request header.
optional lease = 2
The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
message
recording.proto:162The StopRecording response message contains the status of this request and any useful error information if the request fails.
optional header = 1
Common response header.
StopRecordingResponse.Status status = 2
The return status for the request.
string error_waypoint_localized_id = 3
If not localized to end, specifies which waypoint we are localized to.
optional lease_use_result = 4
The results/status of the lease provided.
optional session_start_time = 5
This is the robot local timestamp that graph_nav began recording on. If the StartRecordingRequest's session start time is provided, this should be the same as the request's session start time.
optional map_stats = 6
General statistics of the map loaded in GraphNav.
Create a new waypoint at the current localization.
message
recording.proto:196The CreateWaypoint request message specifies a name and environment the robot should use to generate a waypoint in the graph at it's current location.
optional header = 1
Common request header.
string waypoint_name = 2
Name of the waypoint to create. Overrides any naming prefix.
optional recording_environment = 3
This will be merged into a copy of the existing persistent recording environment and used as the environment for the created waypoint and the edge from the previous waypoint to the new one. It will not affect the persistent environment.
optional lease = 4
The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
repeated int32 require_fiducials = 5
If filled out, asks that the record service verify that the given fiducial IDs are presently visible before creating a waypoint. This is useful for verifying that the robot is where the user thinks it is in an area with known fiducials.
repeated world_objects = 6
Additional world objects to insert into this waypoint.
message
recording.proto:219The CreateWaypoint response message contains the complete waypoint, and the associated edge connecting this waypoint to the graph when the request succeeds.
optional header = 1
Common response header.
optional created_waypoint = 2
The waypoint that was just created.
optional created_edge = 3
The edge connecting the waypoint just created with the last created waypoint in the map.
CreateWaypointResponse.Status status = 5
Return status for the request.
optional lease_use_result = 4
The results/status of the lease provided.
repeated int32 missing_fiducials = 6
If the status is STATUS_MISSING_FIDUCIALS, the following fiducials were not visible to the robot when trying to create the waypoint.
repeated int32 bad_pose_fiducials = 8
If the status is STATUS_FIDUCIAL_POSE_NOT_OK, these are the fiducials that could not be localized confidently.
LicenseInfo.Status license_status = 7
Large graphs can only be uploaded if the license permits them. Recording will stop automatically when the graph gets too large. If CreateWaypointResponse is requested after the graph gets too large, it will fail, and license status will be filled out.
optional map_stats = 9
General statistics of the map loaded in GraphNav.
Set the environment and name prefix to use for the recording.
message
recording.proto:38The SetRecordingEnvironment request message sets a persistent recording environment until changed with another SetRecordingEnvironment rpc.
optional header = 1
Common request header.
optional environment = 2
Persistent environment to use while recording. This allows the user to specify annotations and naming prefixes for new waypoints and edges.
optional lease = 3
The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
message
recording.proto:51The SetRecordingEnvironment response message includes the result and status of the request.
optional header = 1
Common response header.
optional lease_use_result = 2
The results/status of the lease provided.
rpc CreateEdge (, )
recording_service.proto:47Create an arbitrary edge between two waypoints.
message
recording.proto:272The CreateEdge request message specifies an edge to create between two existing waypoints. The edge must not already exist in the map. This can be used to close a loop or to add any additional edges.
optional header = 1
Common request header.
optional edge = 2
Create an edge between two existing waypoints in the map with the given parameters.
optional lease = 3
The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
message
recording.proto:285The CreateEdge response message contains the status of this request and any useful error information if the request fails.
optional header = 1
Common response header.
CreateEdgeResponse.Status status = 2
Return status for the request.
optional error_existing_edge = 3
If set, the existing edge that caused the STATUS_EXISTS error.
optional lease_use_result = 4
The results/status of the lease provided.
optional map_stats = 5
General statistics of the map loaded in GraphNav.
Tells the client the internal state of the record service, and the structure of the map that has been recorded so far.
message
recording.proto:313The GetRecordStatus request message asks for the current state of the recording service.
optional header = 1
Common request header.
message
recording.proto:320The GetRecordStatus response message returns whether the service is currently recording and what the persistent recording environment is at the time the request was received.
optional header = 1
Common response header.
bool is_recording = 2
If true, the record service is actively recording a chain.
optional recording_environment = 3
The current persistent recording environment.
GetRecordStatusResponse.MapState map_state = 4
GetRecordStatusResponse.Status status = 5
optional impaired_state = 6
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
optional session_start_time = 7
This is the robot local timestamp that graph_nav began recording on. If the Start Recording Request's session start time is provided, this should be the same as the request's session start time.
optional map_stats = 8
General statistics of the map loaded in GraphNav.
The GraphNav service service is a place-based localization and locomotion service. The service can be used to get/set the localization, upload and download the current graph nav maps, and send navigation requests to move around the map.
Trigger a manual localization. Typically done to provide the initial localization.
message
graph_nav.proto:120The SetLocalization response message contains the resulting localization to the map.
optional header = 1
Common response header.
optional lease_use_result = 2
Result of using the lease.
SetLocalizationResponse.Status status = 3
Return status for the request.
string error_report = 4
If set, describes the reason the status is not OK.
optional localization = 5
Result of localization.
optional suspected_ambiguity = 7
Alternative information if the localization is ambiguous.
optional impaired_state = 8
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
optional sensor_status = 9
This status determines whether the robot has compatible sensors for the map that was recorded. Note that if sensors aren't working, STATUS_IMPAIRED will be returned, rather than STATUS_INCOMPATIBLE_SENSORS.
SetLocalizationResponse.QualityCheckResult quality_check_result = 10
Graph Nav will check the quality of the resulting localization and report the status here. Note that to preserve backwards compatability with 3.2 and earlier, a poor quality check does not result in this RPC failing.
Tell GraphNav to navigate/traverse a given route.
message
graph_nav.proto:506A NavigateRoute request message specifies a route of waypoints/edges and parameters about how to get there. Like NavigateTo, this command returns immediately upon processing and provides a command_id that the user can use along with a NavigationFeedbackRequest RPC to poll the system for feedback on this command. The RPC does not block until the route is completed.
optional header = 1
Common request header.
repeated leases = 2
The Lease to show ownership of the robot.
optional route = 3
A route for the robot to follow.
optional route_follow_params = 9
What should the robot do if it is not at the expected point in the route, or the route is blocked.
optional travel_params = 4
How to travel the route.
optional end_time = 5
The timestamp (in robot time) that the navigation command is valid until.
string clock_identifier = 6
Identifier provided by the time sync service to verify time sync between robot and client.
optional destination_waypoint_tform_body_goal = 7
If provided, graph_nav will move the robot to an SE2 pose relative to the final waypoint in the route. Note that the robot will treat this as a simple goto request. It will first arrive at the destination waypoint, and then travel in a straight line from the destination waypoint to the offset goal, attempting to avoid obstacles along the way.
uint32 command_id = 8
Unique identifier for the command. If 0, this is a new command, otherwise it is a continuation of an existing command.
message
graph_nav.proto:545Response to a NavigateRouteRequest. This is returned immediately after the request is processed. A command_id is provided to specify the ID that the user may use to poll the system for feedback on the NavigateRoute command.
optional header = 1
Common response header.
repeated lease_use_results = 2
Details about how the lease was used.
NavigateRouteResponse.Status status = 3
Return status for the request.
optional impaired_state = 7
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
uint32 command_id = 4
Unique identifier for the command, If 0, command was not accepted.
repeated string error_waypoint_ids = 5
On a relevant error status code, these fields contain the waypoint/edge IDs that caused the error.
repeated error_edge_ids = 6
On a relevant error status code (STATUS_INVALID_EDGE), this is populated with the edge ID's that cased the error.
optional area_callback_error = 8
Errors about Area Callbacks in the map.
rpc NavigateTo (, )
graph_nav_service.proto:26Tell GraphNav to navigate to a waypoint along a route it chooses.
message
graph_nav.proto:331The NavigateToRequest can be used to command GraphNav to drive the robot to a specific waypoint. GraphNav will plan a path through the map which most efficiently gets the robot to the specified goal waypoint. Parameters are provided which influence how GraphNav will generate and follow the path. This RPC returns immediately after the request is processed. It does not block until GraphNav completes the path to the goal waypoint. The user is expected to periodically check the status of the NavigateTo command using the NavigationFeedbackRequest RPC.
optional header = 1
Common request header.
repeated leases = 2
The Leases to show ownership of the robot and the graph.
string destination_waypoint_id = 3
ID of the waypoint to go to.
optional route_params = 4
Preferences on how to pick the route.
optional travel_params = 5
Parameters that define how to traverse and end the route.
optional end_time = 6
The timestamp (in robot time) that the navigation command is valid until.
string clock_identifier = 7
Identifier provided by the time sync service to verify time sync between robot and client.
optional destination_waypoint_tform_body_goal = 8
If provided, graph_nav will move the robot to an SE2 pose relative to the waypoint. Note that the robot will treat this as a simple goto request. It will first arrive at the destination waypoint, and then travel in a straight line from the destination waypoint to the offset goal, attempting to avoid obstacles along the way.
uint32 command_id = 9
Unique identifier for the command. If 0, this is a new command, otherwise it is a continuation of an existing command. If this is a continuation of an existing command, all parameters will be ignored, and the old parameters will be preserved.
RouteFollowingParams.RouteBlockedBehavior route_blocked_behavior = 10
Defines robot behavior when route is blocked. Defaults to reroute when route is blocked.
message
graph_nav.proto:370Response to a NavigateToRequest. This is returned immediately after the request is processed. A command_id is provided to specify the ID that the user may use to poll the system for feedback on the NavigateTo command.
optional header = 1
Common response header.
repeated lease_use_results = 2
Results of using the various leases.
NavigateToResponse.Status status = 3
Return status for the request.
optional impaired_state = 6
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
uint32 command_id = 4
Unique identifier for the command, If 0, command was not accepted.
repeated string error_waypoint_ids = 5
On a relevant error status code, these fields contain the waypoint/edge IDs that caused the error.
optional area_callback_error = 10
Errors about Area Callbacks in the map.
Tell GraphNav to navigate to a goal with respect to the current anchoring.
message
graph_nav.proto:651The NavigateToAnchorRequest can be used to command GraphNav to drive the robot to a specific place in an anchoring. GraphNav will find the waypoint that has the shortest path length from robot's current position but is still close to the goal. GraphNav will plan a path through the map which most efficiently gets the robot to the goal waypoint, and will then travel in a straight line from the destination waypoint to the offset goal, attempting to avoid obstacles along the way. Parameters are provided which influence how GraphNav will generate and follow the path. This RPC returns immediately after the request is processed. It does not block until GraphNav completes the path to the goal waypoint. The user is expected to periodically check the status of the NavigateToAnchor command using the NavigationFeedbackRequest RPC.
optional header = 1
Common request header.
repeated leases = 2
The Leases to show ownership of the robot and the graph.
oneof goal
Users may either choose seed_tform_goal or gps_navigation_params as a goal.
seed_tform_goal = 3
The goal, expressed with respect to the seed frame of the current anchoring. The robot will use the z value to find the goal waypoint, but the final z height the robot achieves will depend on the terrain height at the offset from the goal.
gps_navigation_params = 11
If given, the NavigateToAnchor request will instead be interpreted as a command to navigate to GPS coordinates. When given, the seed_tform_goal will be ignored,and instead the parameters in this message will be used. Otherwise, the NavigateToAnchorRequest works identically to when seed_tform_goal is used instead. For example, the TravelParams will be respected for this kind of goal.
optional goal_waypoint_rt_seed_ewrt_seed_tolerance = 4
These parameters control selection of the goal waypoint. In seed frame, they are the x, y, and z tolerances with respect to the goal pose within which waypoints will be considered. If these values are negative, or too small, reasonable defaults will be used.
optional route_params = 6
Preferences on how to pick the route.
optional travel_params = 7
Parameters that define how to traverse and end the route.
optional end_time = 8
The timestamp (in robot time) that the navigation command is valid until.
string clock_identifier = 9
Identifier provided by the time sync service to verify time sync between robot and client.
uint32 command_id = 10
Unique identifier for the command. If 0, this is a new command, otherwise it is a continuation of an existing command. If this is a continuation of an existing command, all parameters will be ignored, and the old parameters will be preserved.
message
graph_nav.proto:697Response to a NavigateToAnchorRequest. This is returned immediately after the request is processed. A command_id is provided to specify the ID that the user may use to poll the system for feedback on the NavigateTo command.
optional header = 1
Common response header.
repeated lease_use_results = 2
Results of using the various leases.
NavigateToAnchorResponse.Status status = 3
Return status for the request.
optional impaired_state = 6
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
uint32 command_id = 4
Unique identifier for the command, If 0, command was not accepted.
repeated string error_waypoint_ids = 5
On a relevant error status code, these fields contain the waypoint/edge IDs that caused the error.
optional area_callback_error = 7
Errors about Area Callbacks in the map.
NavigateToAnchorResponse.GPSStatus gps_status = 8
Result of the GPS command.
Get feedback on active navigation command.
message
graph_nav.proto:795The NavigationFeedback request message uses the command_id of a navigation request to get the robot's progress and current status for the command. Note that all commands return immediately after they are processed, and the robot will continue to execute the command asynchronously until it times out or completes. New commands override old ones.
optional header = 1
Common request header.
uint32 command_id = 2
Unique identifier for the command, provided by nav command response. Omit to get feedback on currently executing command.
message
graph_nav.proto:806The NavigationFeedback response message returns the robot's progress and current status for the command.
optional header = 1
Common response header.
NavigationFeedbackResponse.Status status = 2
Return status for the request.
optional impaired_state = 6
If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
map<string, > area_callback_errors = 9
If the status is AREA_CALLBACK_ERROR, this map will be filled out with the error. The key of the map is the region id.
optional remaining_route = 3
Remaining part of current route.
optional completed_route = 18
The completed route taken for this command. Intended primarily for visualization of route progress. Do not use this to determine if the route is finished, as under certain conditions edges can be reported as completed before the route is done. Check the status for STATUS_REACHED_GOAL to determine if the robot has finished the route.
double remaining_route_length = 17
Estimated length of remaining route.
uint32 command_id = 4
ID of the command this feedback corresponds to.
optional last_ko_tform_goal = 5
The most recent transform describing the robot's pose relative to the navigation goal.
SE2TrajectoryCommand.Feedback.BodyMovementStatus body_movement_status = 7
Indicates whether the robot's body is currently in motion.
Edge.Annotations.PathFollowingMode path_following_mode = 8
Path following mode
map<string, > active_region_information = 10
Map of Region IDs with relevant information
NavigationFeedbackResponse.RouteFollowingStatus route_following_status = 1000
Additional information about what kind of route the robot is following and why.
NavigationFeedbackResponse.BlockageStatus blockage_status = 1001
Additional information about whether or not the robot believes the current route to be blocked.
NavigationFeedbackResponse.StuckReason stuck_reason = 11
Only filled out if status is STATUS_STUCK to provide additional context.
Get the localization status and data.
message
graph_nav.proto:969The GetLocalizationState request message requests the current localization state and any other live data from the robot if desired. The localization consists of a waypoint ID and the relative pose of the robot with respect to that waypoint.
optional header = 1
Common request header.
string waypoint_id = 8
Return the localization relative to this waypoint, if specified.
bool request_live_point_cloud = 2
If true, request the live edge-segmented point cloud that was used to generate this localization.
bool request_live_images = 3
If true, request the live images from realsense cameras at the time of localization.
bool request_live_terrain_maps = 4
If true, request the live terrain maps at the time of localization.
bool request_live_world_objects = 5
If true, request the live world objects at the time of localization.
bool request_live_robot_state = 6
If true, requests the full live robot state at the time of localization.
bool compress_live_point_cloud = 7
If true, the smallest available encoding will be used for the live point cloud data. If false, three 32 bit floats will be used per point in the point cloud.
bool request_gps_state = 9
If true, request data about the robot's GPS localization.
message
graph_nav.proto:1064The GetLocalizationState response message returns the current localization and robot state, as well as any requested live data information.
optional header = 1
Common response header.
optional localization = 2
Where the robot currently is. If a waypoint_id was specified in the request, this localization will be relative to that waypoint.
optional robot_kinematics = 4
Robot kinematic state at time of localization.
repeated remote_cloud_status = 5
Status of one or more remote point cloud services (such as velodyne).
optional live_data = 6
Contains live data at the time of localization, with elements only filled out if requested.
optional lost_detector_state = 7
If the robot drives around without a good localization for a while, eventually it becomes "lost." I.E. it has a localization, but it no longer trusts that the localization it has is accurate. Lost detector state is available through this message.
optional gps = 8
If the robot has GPS capability and the map was recorded with GPS, this message will show graph nav's estimate of the robot location in earth-centered frames. To see the raw GPS data, look at the WorldObject list.
rpc ClearGraph (, )
graph_nav_service.proto:39Clears the local graph structure. Also erases any snapshots currently in RAM.
message
graph_nav.proto:1098Clears the graph on the server. Also clears GraphNav's localization to the graph. Note that waypoint and edge snapshots may still be cached on the server after this operation. This RPC may not be used while recording a map.
optional header = 1
Common request header.
optional lease = 2
The Lease to show ownership of graph-nav service.
message
graph_nav.proto:1106The results of the ClearGraphRequest.
optional header = 1
Common response header.
optional lease_use_result = 2
Details about how the lease was used.
ClearGraphResponse.Status status = 3
Status of the ClearGraphResponse.
Download the graph structure.
message
graph_nav.proto:1273The DownloadGraph response message includes the current graph on the robot.
optional header = 1
Common request header.
optional graph = 2
The structure of the graph.
rpc DownloadGraphStreaming (, stream )
graph_nav_service.proto:45This is a streaming version of the DownloadGraph RPC.
message
graph_nav.proto:1281Streaming version of the DownloadGraphResponse.
optional header = 1
Common response header.
optional chunk = 2
Chunk of data to download. Responses are sent in sequence until the data chunk is complete. After receiving all chunks, concatenate them into a single byte string. Then, deserialize the byte string into a DownloadGraphResponse object.
Upload the full list of waypoint IDs, graph topology and other small info. Note: if multiple clients/RPCs are attempting to upload a graph at the same time, uploads will be performed synchronously in the order in which they are received, and the later UploadGraph request will block until the earlier completes.
message
graph_nav.proto:1124Uploads a graph to the server. This graph will be appended to the graph that currently exists on the server.
optional header = 1
Common request header.
optional graph = 2
Structure of the graph containing waypoints and edges without underlying sensor data.
optional lease = 3
The Lease to show ownership of graph-nav service.
bool generate_new_anchoring = 4
If this is true, generate an (overwrite the) anchoring on upload.
bool treat_validation_warnings_as_errors = 5
If true, validation warnings will be treated as errors, and STATUS_INVALID_GRAPH will be returned. This is false by default.
rpc UploadGraphStreaming (stream , )
graph_nav_service.proto:61This is a streaming version of UploadGraph to allow uploading larger graphs. Note: as with UploadWaypointSnapshot, this streaming process involves serializing a full UploadGraph message from chunks. After all the chunks have been uploaded, a regular UploadGraph RPC will be performed internally, so UploadGraphStreaming has the same semantics as UploadGraph when it completes. That is, UploadGraphStreaming is *not* to be used for incrementally uploading graph data as the robot is navigating -- this is merely a streaming wrapper around UploadGraph.
message
graph_nav.proto:1142This is a streaming version of the UploadGraph request.
optional header = 1
Common request header.
optional chunk = 2
Serialized bytes of a UploadGraphRequest message, restricted to a chunk no larger than 4MB in size. To break the data into chunks, first serialize it to bytes. Then, send the bytes in order as DataChunk objects. The chunks will be concatenated together on the server, and deserialized.
rpc UploadWaypointSnapshot (stream , )
graph_nav_service.proto:64Uploads large waypoint snapshot as a stream for a particular waypoint.
message
graph_nav.proto:1296Used to upload waypoint snapshot in chunks for a specific waypoint snapshot. Waypoint snapshots consist of the large sensor data at each waypoint. Chunks will be streamed one at a time to the server. Chunk streaming is required to prevent overwhelming gRPC with large http requests.
optional header = 1
Common response header.
optional chunk = 3
Serialized bytes of a WaypointSnapshot message, restricted to a chunk no larger than 4MB in size. To break the data into chunks, first serialize it to bytes. Then, send the bytes in order as DataChunk objects. The chunks will be concatenated together on the server, and deserialized.
optional lease = 4
The Leases to show ownership of the graph-nav service.
message
graph_nav.proto:1310One response for the entire WaypointSnapshot after all chunks have been concatenated and deserialized.
optional header = 1
Common response header.
optional lease_use_result = 2
Details about how the lease was used.
UploadWaypointSnapshotResponse.Status status = 3
optional sensor_status = 4
optional map_stats = 5
General map statistics after upload.
rpc UploadEdgeSnapshot (stream , )
graph_nav_service.proto:68Uploads large edge snapshot as a stream for a particular edge.
message
graph_nav.proto:1336Used to upload edge data in chunks for a specific edge snapshot. Edge snapshots contain large sensor data associated with each edge. Chunks will be streamed one at a time to the server. Chunk streaming is required to prevent overwhelming gRPC with large http requests.
optional header = 1
Common response header.
optional chunk = 4
Serialized bytes of a EdgeSnapshot message, restricted to a chunk no larger than 4MB in size. To break the data into chunks, first serialize it to bytes. Then, send the bytes in order as DataChunk objects. The chunks will be concatenated together on the server, and deserialized
optional lease = 5
The Leases to show ownership of the graph-nav service.
message
graph_nav.proto:1349One response for the entire EdgeSnapshot after all chunks have been concatenated and deserialized.
optional header = 1
Common response header.
optional lease_use_result = 2
Details about how the lease was used.
optional map_stats = 3
General map statistics after upload.
rpc DownloadWaypointSnapshot (, stream )
graph_nav_service.proto:72Download waypoint data from the server. If the snapshot exists in disk cache, it will be loaded.
message
graph_nav.proto:1362The DownloadWaypointSnapshot request asks for a specific waypoint snapshot id to be downloaded and has parameters to decrease the amount of data downloaded. After recording a map, first call the DownloadGraph RPC. Then, for each waypoint snapshot id, request the waypoint snapshot from the server using the DownloadWaypointSnapshot RPC.
optional header = 1
Common request header.
string waypoint_snapshot_id = 2
ID of the snapshot associated with a waypoint.
bool download_images = 3
If true, download the full images and point clouds from each camera.
bool compress_point_cloud = 4
If true, the point cloud will be compressed using the smallest available point cloud encoding. If false, three 32-bit floats will be used per point.
bool do_not_download_point_cloud = 5
Skip downloading the point cloud, and only download other data such as images or world objects.
message
graph_nav.proto:1385The DownloadWaypointSnapshot response streams the data of the waypoint snapshot id currently being downloaded in data chunks no larger than 4MB in size. It is necessary to stream these data to avoid overwhelming gRPC with large http requests.
optional header = 1
Common response header.
DownloadWaypointSnapshotResponse.Status status = 2
Return status for the request.
string waypoint_snapshot_id = 4
ID of the snapshot associated with a waypoint.
optional chunk = 5
Chunk of data to download. Responses are sent in sequence until the data chunk is complete. After receiving all chunks, concatenate them into a single byte string. Then, deserialize the byte string into a WaypointSnapshot object.
rpc DownloadEdgeSnapshot (, stream )
graph_nav_service.proto:76Download edge data from the server. If the snapshot exists in disk cache, it will be loaded.
message
graph_nav.proto:1407The DownloadEdgeSnapshot request asks for a specific edge snapshot id to be downloaded. Edge snapshots contain the large sensor data stored in each edge.
optional header = 1
Common request header.
string edge_snapshot_id = 2
ID of the data associated with an edge.
message
graph_nav.proto:1417The DownloadEdgeSnapshot response streams the data of the edge snapshot id currently being downloaded in data chunks no larger than 4MB in size. It is necessary to stream these data to avoid overwhelming gRPC with large http requests.
optional header = 1
Common response header.
DownloadEdgeSnapshotResponse.Status status = 2
Return status for the request.
string edge_snapshot_id = 4
ID of the snapshot associated with an edge.
optional chunk = 5
Chunk of data to download. Responses are sent in sequence until the data chunk is complete. After receiving all chunks, concatenate them into a single byte string. Then, deserialize the byte string into an EdgeSnapshot object.
Verify that the graph is still valid and all required external services are still available. A map that was valid at upload time may not still be valid if required services are no longer running.
message
graph_nav.proto:1449Run a check on the currently loaded map.
optional header = 1
message
graph_nav.proto:1454Report possible errors with the loaded map.
optional header = 1
ValidateGraphResponse.Status status = 2
Status of the currently loaded map.
optional sensor_status = 3
optional area_callback_error = 4
Errors about Area Callbacks in the map.
Defines services for processing an existing GraphNav map.
rpc ProcessTopology (, stream )
map_processing_service.proto:19Processes a GraphNav map by creating additional edges or waypoints. After processing, a new subgraph is created containing additional waypoints or edges to add to the map.
message
map_processing.proto:24Processes a GraphNav map by creating additional edges. After processing, a new subgraph is created containing additional edges to add to the map. Edges are created between waypoints that are near each other. These waypoint pairs are called "loop closures", and are found by different means. In general, if parameters are not provided, reasonable defaults will be used. Note that this can be used to merge disconnected subgraphs from multiple recording sessions so long as they share fiducial observations.
optional header = 1
Standard message header.
optional params = 2
Parameters. If not filled out, reasonable defaults will be used.
bool modify_map_on_server = 3
If true, any processing should directly modify the map on the server. Otherwise, the client is expected to upload the processing results (newly created edges) back to the server. The processing service shares memory with a map container service (e.g the GraphNav service).
message
map_processing.proto:152Result of the topology processing RPC. If successful, contains a subgraph of new waypoints or edges created by this process.
optional header = 1
Standard message header.
ProcessTopologyResponse.Status status = 2
Result of the processing.
optional new_subgraph = 3
This graph contains the new edge(s) created by map processing. Note that these edges will be annotated with their creation method. Note that several subgraphs may be returned via streaming as the map is processed.
bool map_on_server_was_modified = 4
If modify_map_on_server was set to true in the request, then the map currently on the server was modified using map processing. If this is set to false, then either an error occurred during processing, or modify_map_on_server was set to false in the request. When map_on_server_was_modified is set to false, the client is expected to upload the results back to the server to commit the changes.
repeated string missing_snapshot_ids = 10
When there are missing waypoint snapshots, these are the IDs of the missing snapshots. Upload them to continue.
repeated string missing_waypoint_ids = 11
When there are missing waypoints, these are the IDs of the missing waypoints. Upload them to continue.
bool timed_out = 12
If true, the processing timed out. Note that this is not considered an error. Run topology processing again to continue adding edges.
rpc ProcessAnchoring (, stream )
map_processing_service.proto:23Processes a GraphNav map by modifying the anchoring of waypoints and world objects in the map with respect to a seed frame. After processing, a new anchoring is streamed back.
message
map_processing.proto:293Causes the server to optimize an existing anchoring, or generate a new anchoring for the map using the given parameters. In general, if parameters are not provided, reasonable defaults will be used. The new anchoring will be streamed back to the client, or modified on the server if desired.
optional header = 1
Standard request header.
optional params = 2
optional initial_hint = 3
Initial guess at some number of waypoints and world objects and their anchorings.
bool modify_anchoring_on_server = 4
If true, the map currently uploaded to the server will have its anchoring modified. Otherwise, the user is expected to re-upload the anchoring.
bool stream_intermediate_results = 5
If true, the anchoring will be streamed back to the user after every iteration. This is useful for debug visualization.
bool apply_gps_result_to_waypoints_on_server = 6
If true, the GPSSettings inside waypoint annotations will be modified based on the optimization. Every waypoint will have waypoint.gps_settings set, with ecef_tform_waypoint applied form this optimization. To get these results, call the DownloadGraph RPC. Alternatively, the ecef_tform_waypoint can be found using: response.gps_result.ecef_tform_seed * seed_tform_waypoint[waypoint_id]. Note that after this operation completes successfully, all waypoints in the graph can be used to navigate using GPS, even if they didn't have GPS data in their waypoint snapshots.
message
map_processing.proto:374Streamed response from the ProcessAnchoringRequest. These will be streamed until optimization is complete. New anchorings will be streamed as they become available.
optional header = 1
ProcessAnchoringResponse.Status status = 2
repeated waypoint_results = 3
Contains new anchorings for waypoint(s) processed by the server. These will be streamed back to the user as they become available.
repeated world_object_results = 4
Contains new anchorings for object(s) (e.g april tags) processed by the server. These will be streamed back to the user as they become available
bool anchoring_on_server_was_modified = 5
If modify_anchoring_on_server was set to true in the request, then the anchoring currently on the server was modified using map processing. If this is set to false, then either an error occurred during processing, or modify_anchoring_on_server was set to false in the request. When anchoring_on_server_was_modified is set to false, the client is expected to upload the results back to the server to commit the changes.
int32 iteration = 6
The current optimizer iteration that produced these data.
double cost = 7
The current nonlinear optimization cost.
bool final_iteration = 8
If true, this is the result of the final iteration of optimization. This will always be true when stream_intermediate_results in the request is false.
repeated violated_waypoint_constraints = 9
On failure due to constraint violation, these hints were violated by the optimization. Try increasing the pose bounds on the constraints of these hints.
repeated violated_object_constraints = 10
On failure due to constraint violation, these hints were violated by the optimization. Try increasing the pose bounds on the constraints of these hints.
repeated string missing_snapshot_ids = 11
When there are missing waypoint snapshots, these are the IDs of the missing snapshots. Upload them to continue.
repeated string missing_waypoint_ids = 12
When there are missing waypoints, these are the IDs of the missing waypoints. Upload them to continue.
repeated string invalid_hints = 13
Unorganized list of waypoints and object IDs which were invalid (missing from the map).
repeated inconsistent_edges = 14
List of edges that are inconsistent with the optimized result. This can happen when incorrect loop closures have been made before optimization, when inconsistent anchoring hints were passed in, or because the optimizer ended up in a local minimum.
optional gps_result = 15
If GPS embedding optimization was enabled, this is the result of that process.
message
map.proto:433This associates a waypoint with a common reference frame, which is not necessarily metric.
Used in: , ,
string id = 1
Identifier of the waypoint.
optional seed_tform_waypoint = 2
Pose of the waypoint in the seed frame.
message
map_processing.proto:210Controls how certain the user is of an anchor's pose. If left empty, a reasonable default will be chosen.
Used in: ,
oneof uncertainty
se3_covariance = 1
A full 6x6 Gaussian covariance matrix representing uncertainty of an anchoring.
confidence_bounds = 2
Represents the 95 percent confidence interval on individual axes. This will be converted to a SE3Covariance internally by creating a diagonal matrix whose elements are informed by the confidence bounds.
message
map.proto:442This associates a world object with a common reference frame, which is not necessarily metric.
Used in: , ,
string id = 1
Identifier of the world object.
optional seed_tform_object = 2
Pose of the object in the seed frame.
message
map.proto:450Used in:
repeated anchors = 1
The waypoint ids for the graph, expressed in a common reference frame, which is not necessarily metric. If there is no anchoring, this is empty.
repeated objects = 2
World objects, located in the common reference frame.
message
map_processing.proto:282The user may assign a number of world objects and waypoints a guess at where they are in the seed frame. These hints will be respected by the ProcessAnchoringRequest.
Used in:
repeated waypoint_anchors = 1
List of waypoints and hints as to where they are in the seed frame.
repeated world_objects = 2
List of world objects and hints as to where they are in the seed frame.
Indicator of whether or not the waypoint and edge annotations are complete and filled out.
Used in: , ,
ANNOTATION_STATE_UNKNOWN = 0
No assertions made about this annotation.
ANNOTATION_STATE_SET = 1
This annotation and all of its fields have been deliberately set.
ANNOTATION_STATE_NONE = 2
This annotation has been deliberately set to "no annotation" -- any subfields are unset.
message
area_callback_data.proto:20Data for a AreaCallback to be stored in the map
Used in: , ,
optional config_data = 1
Custom config data used by the service to do its job.
optional custom_params = 2
Deprecated in 4.1, use param_collection instead so that the parameter specs are available for building editors. Any other custom parameters to the callback. This will be copied into custom_params inside the BeginCallback RPC if it exists.
optional parameters = 4
Any other custom parameters to the callback. This will be copied into custom_params inside the BeginCallback RPC if it exists.
optional map_config = 3
Configuration data for how this area callback should be treated in the map.
message
area_callback.proto:23Error reporting for things that can go wrong with calls.
Used in:
string service_name = 1
AreaCallbackError.CallError error = 2
oneof response_error
If error is ERROR_RESPONSE, the response will be included here.
begin_callback = 3
begin_control = 4
update_callback = 5
end_callback = 6
Used in:
ERROR_UNKNOWN = 0
ERROR_TRANSPORT = 1
Unable to communicate with the callback.
ERROR_RESPONSE = 2
The callback responded with an error.
ERROR_SERVICE = 3
The service was not registered.
message
area_callback.proto:85Specific information about how a AreaCallback implementation should be called. All fields are optional, and need only be filled out if the desired behavior is different from the default.
Used in:
repeated string required_lease_resources = 1
A area callback can request to be in control of one or more resources at runtime.
optional custom_params = 4
Parameters this area callback supports that do not match any of the other fields.
AreaCallbackInformation.Blockage blockage = 5
AreaCallbackInformation.Impairment impairment_check = 6
AreaCallbackInformation.EntityWaiting entity_waiting = 7
optional default_stop = 8
How the robot should stop at waypoints by default.
optional map_config = 9
Configuration to store in the map about how to treat the region edges.
Specify what graph nav should expect to detect for blockages in this region. For example, if the callback can open doors, the region may initially look blocked due to a closed door, but Graph Nav should still expect it to be traversable.
Used in:
BLOCKAGE_UNKNOWN = 0
BLOCKAGE_SKIP = 1
(Default) The region may appear blocked to Graph Nav, but the callback will still be able to traverse it. If the region is blocked, Graph Nav should consider it passable unless it actually gets stuck trying to navigate it.
BLOCKAGE_CHECK = 2
Graph Nav should expect the region to be clear. If the region is blocked, Graph Nav can treat that as impassable.
Control whether Graph Nav will stop and wait for nearby entities when crossing the region. Entity waiting is normally on for regular Graph Nav, but is by default turned off inside Area callback regions.
Used in:
ENTITY_WAITING_UNKNOWN = 0
ENTITY_WAITING_DISABLE = 1
(Default) Disable waiting for entities when crossing the region.
ENTITY_WAITING_ENABLE = 2
Enable waiting for entities when crossing the region.
Specify whether graph nav should check for impairment when the callback is in control of the robot. Certain failures may make Graph Nav unable to navigate, but may not affect the callback. If the callback is in control of the robot, it may be preferable to let it finish and return control to Graph Nav before reporting any impaired error instead of interrupting the callback.
Used in:
IMPAIRMENT_UNKNOWN = 0
IMPAIRMENT_SKIP = 1
(Default) Do not check Graph Nav impairment when the callback is in control.
IMPAIRMENT_CHECK = 2
Continue to check Graph Nav impairment when the callback is in control. If Graph Nav detects that it is impaired, it will stop the callback immediately.
message
area_callback_data.proto:16Configuration data for how an area callback should be treated in a map.
Used in: ,
(message has no fields)
message
map.proto:460Data for a AreaCallback in the annotation.
Used in:
string service_name = 1
This service must be used in a given region to safely traverse it.
string description = 3
Human-readable description of this region.
optional recorded_data = 4
Configuration data associated with this area callback.
message
graph_nav.proto:1438Information about problems Area Callback services specified in a map or on a route.
Used in: , , , ,
repeated string missing_services = 1
Area Callback services that were requested but could not be contacted by graph nav. A service is considered missing if it is either not registered, or if it is registered but does not respond to a AreaCallbackInformation request.
repeated faulted_services = 2
Area Callback services that were requested but are reporting critical faults.
message
area_callback.proto:191Used as response type in: AreaCallbackService.BeginCallback
Used as field type in:
optional header = 1
Common response header.
BeginCallbackResponse.Status status = 2
Return status for the request.
uint32 command_id = 3
Unique identifier for the AreaCallback, used to update the callback in subsequent calls. If empty, the request was not accepted.
optional custom_param_error = 4
Filled out if status is STATUS_CUSTOM_PARAMS_ERROR.
Used in:
STATUS_UNKNOWN = 0
UNKNOWN should never be used.
STATUS_OK = 1
The area callback successfully began.
STATUS_INVALID_CONFIGURATION = 2
The area callback failed to start due to some problem with the supplied configuration_data.
STATUS_EXPIRED_END_TIME = 3
The area callback end time already expired.
STATUS_CUSTOM_PARAMS_ERROR = 8
One or more keys or values in custom_params are unsupported by the area callback. See the custom_param_error for details.
message
area_callback.proto:237Used as response type in: AreaCallbackService.BeginControl
Used as field type in:
optional header = 1
Common response header.
repeated lease_use_results = 2
Details about how the lease was used.
BeginControlResponse.Status status = 3
Return status for the request.
Used in:
STATUS_UNKNOWN = 0
UNKNOWN should never be used.
STATUS_OK = 1
The AreaCallback has successfully taken control of the robot.
STATUS_INVALID_COMMAND_ID = 2
The request command id does not exist or is no longer executing.
STATUS_MISSING_LEASE_RESOURCES = 3
The supplied lease does not match the leases requested in AreaCallbackInformation.
STATUS_LEASE_ERROR = 4
A lease use error occurred.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_RECORDING = 2
Graph Nav is currently recording a map. You must call StopRecording from the recording service to continue.
message
map.proto:164Optional metadata to attach to waypoints that are being recorded.
Used in:
string session_name = 1
User-provided name for this recording "session". For example, the user may start and stop recording at various times and assign a name to a region that is being recorded. Usually, this will just be the map name.
string client_username = 2
If the application recording the map has a special user name, this is the name of that user.
string client_software_version = 3
Version string of any client software that generated this object.
string client_id = 4
Identifier of any client software that generated this object.
string client_type = 5
Special tag for the client software which created this object. For example, "Tablet", "Scout", "Python SDK", etc.
message
nav.proto:29Information about the route that a robot has followed during a command.
Used in:
repeated string waypoint_ids = 1
List of waypoints reached in the order they were reached.
repeated edges = 2
Information about the completed edges, in the order they were completed.
message
nav.proto:33Used in:
optional edge_id = 1
bool not_in_map = 2
If true, this edge was specially constructed to bypass a blockage, and does not exist in the map.
Used in:
STATUS_UNKNOWN = 0
Status is unknown/unset.
STATUS_OK = 1
The edge was successfully created.
STATUS_EXISTS = 2
Edge already exists with the given ID.
STATUS_NOT_RECORDING = 3
Clients can only create edges when recording.
STATUS_UNKNOWN_WAYPOINT = 4
One or more of the specified waypoints aren't in the map.
STATUS_MISSING_TRANSFORM = 5
Specified edge did not include a transform.
Used in:
STATUS_UNKNOWN = 0
Status is unknown/unset.
STATUS_OK = 1
The waypoint was successfully created.
STATUS_NOT_RECORDING = 2
Clients can only create waypoints when recording.
STATUS_COULD_NOT_CREATE_WAYPOINT = 3
An internal server error prevented the creation of the waypoint.
STATUS_MISSING_FIDUCIALS = 4
Could not see the required fiducials.
STATUS_MAP_TOO_LARGE_LICENSE = 5
The map was too big to create a waypoint based on the license.
STATUS_REMOTE_CLOUD_FAILURE_NOT_IN_DIRECTORY = 6
A required remote cloud did not exist in the service directory.
STATUS_REMOTE_CLOUD_FAILURE_NO_DATA = 7
A required remote cloud did not have data.
STATUS_FIDUCIAL_POSE_NOT_OK = 8
All fiducials are visible but their pose could not be determined accurately.
message
visual_features.proto:88A 3D direction with a covariance estimate.
Used in:
optional direction = 1
The vector is to be interpreted as a 3D normalized direction in a frame.
optional covariance = 2
2x2 covariance matrix representing uncertainty in the direction (in a local tangent frame).
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_SNAPSHOT_DOES_NOT_EXIST = 2
Error where the given snapshot ID does not exist.
message
graph_nav.proto:1267The DownloadGraphRequest requests that the server send the graph (waypoints and edges) to the client. Note that the returned Graph message contains only the topological structure of the map, and not any large sensor data. Large sensor data should be downloaded using DownloadWaypointSnapshotRequest and DownloadEdgeSnapshotRequest. Both snapshots and the graph are required to exist on the server for GraphNav to localize and navigate.
Used as request type in: GraphNavService.DownloadGraph, GraphNavService.DownloadGraphStreaming
optional header = 1
Common request header.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_SNAPSHOT_DOES_NOT_EXIST = 2
Error where the given snapshot ID does not exist.
message
map.proto:237A base element of the graph nav map. Edges consist of a directed edge from one waypoint to another and a transform that estimates the relationship in 3D space between the two waypoints.
Used in: , , ,
optional id = 1
Identifier of this Edge. Edges are mutable -- the identifier does not have to be updated when other fields change.
string snapshot_id = 2
Identifier of this edge's Snapshot data.
optional from_tform_to = 3
Describes the transform between the "from" waypoint and the "to" waypoint.
optional annotations = 4
Annotations specific to the current edge.
message
map.proto:277Annotations understood by BostonDynamics systems.
Used in: ,
optional stairs = 2
Stairs information/parameters specific to the edge.
Annotations.DirectionConstraint direction_constraint = 4
Direction constraints for how the robot must move and the directions it can face when traversing the edge.
optional require_alignment = 5
If true, the robot must be aligned with the edge in yaw before traversing it.
optional flat_ground = 6
If true, the edge crosses flat ground and the robot shouldn't try to climb over obstacles. DEPRECATED as of 3.3. Replaced by ground_clutter_mode. As of 4.1, no longer functional.
optional override_mobility_params = 9
Overrides the following fields of the mobility parameters to whatever is stored in the map. For example, if this FieldMask contains "stairs_mode" and "terrain_params.enable_grated_floor", then the map will be annotated with "stairs_mode" and "enable_grated_floor" settings. An empty FieldMask means all fields are active annotations. Note that the more conservative of the velocity limit stored in the mobility parameters and the TravelParams of the entire route will be used for this edge (regardless of what override_mobility_params says).
optional mobility_params = 10
Contains terrain parameters, swing height, obstacle avoidance parameters, etc. When the robot crosses this edge, it will use the mobility parameters here.
optional cost = 11
Assign edges a cost; used when finding the "shortest" (lowest cost) path.
EdgeSource edge_source = 12
How this edge was made.
bool disable_alternate_route_finding = 13
If true, disables alternate-route-finding for this edge.
Annotations.PathFollowingMode path_following_mode = 14
Path following mode for this edge.
double max_corridor_distance = 18
Max distance from the recorded edge that the robot is allowed to travel when avoiding obstacles or optimized its path. This is half of the full width of the corridor the robot may walk within. If this value is not set, the robot will choose a default corridor width.
bool disable_directed_exploration = 15
Disable directed exploration for this edge.
map<string, > area_callbacks = 16
Reference to area callback regions needed to cross this edge. The string is a unique id for this region, which may be shared across multiple edges.
Annotations.GroundClutterAvoidanceMode ground_clutter_mode = 17
Used in:
DIRECTION_CONSTRAINT_UNKNOWN = 0
We don't know if there are direction constraints.
DIRECTION_CONSTRAINT_NO_TURN = 1
The robot must not turn while walking the edge, but can face either waypoint.
DIRECTION_CONSTRAINT_FORWARD = 2
Robot should walk the edge face-first.
DIRECTION_CONSTRAINT_REVERSE = 3
Robot should walk the edge rear-first.
DIRECTION_CONSTRAINT_NONE = 4
No constraints on which way the robot faces.
Ground clutter avoidance mode. This enables detection and avoidance of low obstacles.
Used in: , ,
GROUND_CLUTTER_UNKNOWN = 0
The mode is unset.
GROUND_CLUTTER_OFF = 1
The mode is explicitly off.
GROUND_CLUTTER_FROM_FOOTFALLS = 2
Enable detection of ground clutter using recorded footfalls. Objects that were not stepped on during map recording are obstacles.
Path following mode
Used in: , , ,
PATH_MODE_UNKNOWN = 0
Unknown value
PATH_MODE_DEFAULT = 1
Use default path following parameters
PATH_MODE_STRICT = 2
Use strict path following parameters
message
map.proto:279Defines any parameters of the stairs
Used in:
AnnotationState state = 1
Check this before reading other fields.
optional straight_staircase = 2
Parameters describing a straight staircase. DEPRECATED as of 3.3. Please use staircase_with_landings.
optional staircase_with_landings = 3
Parameters describing an arbitrary staircase.
StairData.DescentPreference descent_preference = 4
optional traversal_y_offset = 5
The Y position with respect to the staircase frame to align to when traversing this staircase. Regardless of how the recorded waypoints are distributed on the staircase, when traversing the staircase all navigation goals will have this Y position with respect to the staircase in order to guide the robot over the stairs in a straight line.
Used in:
DESCENT_PREFERENCE_UNKNOWN = 0
Unknown value, default to DESCENT_PREFERENCE_ALWAYS_REVERSE.
DESCENT_PREFERENCE_PREFER_REVERSE = 1
Robot will prefer to descend in reverse, but may descend forwards if the route could not otherwise be executed. This could be due to conflicting constraints created by an annotation or by another staircase.
DESCENT_PREFERENCE_ALWAYS_REVERSE = 2
Robot will always attempt to descend stairs in reverse, even if it causes navigation to fail.
DESCENT_PREFERENCE_NONE = 3
Robot may descend in any order. The exact order it chooses will be decided by the lowest cost path found by the local trajectory optimizer and adjacent constraints, if they exist. NOTE: If a staircase which is difficult for the robot to descend in the forward direction is marked with this option, it may cause the robot to fall.
Used in:
EDGE_SOURCE_UNKNOWN = 0
EDGE_SOURCE_ODOMETRY = 1
Edges with transforms from odometry.
EDGE_SOURCE_SMALL_LOOP_CLOSURE = 2
Edges with transforms from a short chain of other edges.
EDGE_SOURCE_FIDUCIAL_LOOP_CLOSURE = 3
Edges with transforms from multiple fiducial observations.
EDGE_SOURCE_ALTERNATE_ROUTE_FINDING = 4
Edges that may help find alternate routes.
EDGE_SOURCE_USER_REQUEST = 5
Created via a CreateEdge RPC.
EDGE_SOURCE_LOCALIZATION = 6
Created when we start recording after recording has been paused. For example, an "extension" of a graph will start with an edge of type EDGE_SOURCE_LOCALIZATION.
message
map.proto:241An edge is uniquely identified by the waypoints it connects. Two waypoints will only ever be connected by a single edge. That edge is traversable in either direction.
Used in: , , , , ,
string from_waypoint = 1
Identifier of the "from" waypoint.
string to_waypoint = 2
Identifier of the "to" waypoint.
message
map.proto:408Relevant data collected along the edge. May be used for automatically generating annotations, for example.
string id = 1
Identifier of this snapshot. Snapshots are immutable -- if any of the other fields change, this ID must also change.
repeated stances = 2
Sampling of stances as robot traversed this edge.
map<string, > area_callbacks = 16
Data used by area callback services to perform their action.
message
map.proto:413Used in:
optional timestamp = 1
Timestamp of the stance.
repeated foot_states = 2
List of all the foot positions for a single stance.
optional ko_tform_body = 3
KO Body position corresponding to this stance.
optional vision_tform_body = 5
Vision Body position corresponding to this stance.
optional planar_ground = 4
Does this stance correspond to a planar ground region.
message
area_callback.proto:398Used as response type in: AreaCallbackService.EndCallback
Used as field type in:
optional header = 1
Common response header.
EndCallbackResponse.Status status = 2
Return status for the request.
Used in:
STATUS_UNKNOWN = 0
UNKNOWN should never be used.
STATUS_OK = 1
The AreaCallback has cleanly ended.
STATUS_INVALID_COMMAND_ID = 2
The request command id does not exist or is no longer executing.
STATUS_SHUTDOWN_CALLBACK_FAILED = 3
Shutting down the callback failed. The callback worker thread did not respond to shutdown signal.
message
gps.proto:15Info about GPS localization if the robot has this capability.
Used in:
GPSLocalization.State live_gps_state = 1
State of the live GPS data.
GPSLocalization.State map_gps_state = 2
State of GPS data at the current waypoint.
optional ecef_tform_body = 3
Estimate of where the robot body is in the Earth-Centered-Earth-Fixed (ECEF) frame at the time of localization.
optional latitude_longitude_height = 4
Estimate of the latitude/longitude/height of the robot at the time of localization.
Used in:
STATE_UNKNOWN = 0
STATE_OK = 1
Using GPS.
STATE_BAD_FRAMES = 2
Error getting frames (ko, etc.)
STATE_NO_GPS_OBJECTS = 3
No GPS available.
STATE_REGISTRATION_NOT_OK = 4
GPS registration isn't ready.
STATE_NO_GPS_STATES = 5
No GPS state measurements.
STATE_NOT_ENOUGH_SATELLITES = 6
Too few satellites to localize.
STATE_NO_ECEF_FRAME = 7
GPS registration is missing a frame.
STATE_HIGH_ERROR = 8
The GPS data exists, but is high error.
STATE_STALE = 9
The GPS data exists, and we have not used it yet, but it is too old to use.
STATE_INTERNAL_ERROR = 10
Internal error (e.g. missing waypoints).
message
graph_nav.proto:625Parameters controlling how the robot will navigate to a GPS coordinate.
Used in:
optional goal_llh = 1
The goal position as latitude/longitude. Height is ignored.
optional goal_yaw = 2
Counter-clockwise rotation in radians around the "up" axis that the robot will try to achieve at the goal. This is a bearing around the "up" axis such that East points to zero yaw, and West is pi radians yaw. If not provided, the robot will try to achieve any allowable orientation at the goal.
optional max_distance_from_map = 3
The maximum distance we are willing to accept for the LLH coordinate from the mapped data in meters. This is a 2 dimensional measurement (height is not considered). If not filled out, Spot will decide based on internal defaults.
message
visual_features.proto:18Generic sparse visual descriptor with a byte blob and a descriptor name.
Used in:
string name = 1
Name of the descriptor which identifies how it is to be interpreted.
bytes data = 2
Binary blob representing the descriptor.
Used in:
MAP_STATE_UNKNOWN = 0
MAP_STATE_OK = 1
Successfully started recording.
MAP_STATE_TOO_LARGE_FOR_LICENSE = 2
Unable to continue recording because a larger map requires an upgraded license.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_ROBOT_IMPAIRED = 2
Unable to record waypoints because the robot is impaired. When this happens, the system will not create new waypoints until the robot is no longer impaired. See impaired_state for more details.
message
map.proto:476This is an arbitrary collection of waypoints and edges. The edges and waypoints are not required to be connected. A waypoint may belong to multiple graphs. This message is used to pass around information about a graph's topology, and is used to serialize map topology to and from files. Note that the graph does not contain any of the waypoint/edge data (which is found in snapshots). Snapshots are stored separately.
Used in: , ,
repeated waypoints = 1
The waypoints for the graph (containing frames, annotations, and sensor data).
repeated edges = 2
The edges connecting the graph's waypoints.
optional anchoring = 3
The anchoring (mapping from waypoints to their pose in a shared reference frame).
message
visual_features.proto:110Indexes an observation of a landmark at a particular bundle, keyframe and keypoint. Waypoint snapshots have bundles of keyframes, each keyframe has a number of extracted keypoints. Observations are structured as: bundle_0 ... bundle_1 .... keyframe_0 .... keyframe_1 ........ keypoint_0 ........ keypoint_1 ........ ... ........ keypoint_J .... ... .... keyframe_K ... bundle_N
Used in:
int32 bundle_id = 1
The bundle from within the waypoint snapshot that this landmark observation came from.
int32 keyframe_id = 2
The keyframe from within the bundle that this observation came from.
int32 keypoint_id = 3
The keypoint within the keyframe that this observation came from.
optional timestamp = 4
Time of the camera image which observed this landmark.
message
nav.proto:47The localization state of the robot. This reports the pose of the robot relative to a particular waypoint on the graph nav map.
Used in: , , ,
string waypoint_id = 1
Waypoint this localization is relative to.
optional waypoint_tform_body = 2
Pose of body in waypoint frame.
optional seed_tform_body = 5
Pose of body in a common reference frame. The common reference frame defaults to the starting fiducial frame, but can be changed. See Anchoring for more info.
optional timestamp = 3
Time (in robot time basis) that this localization was valid.
message
graph_nav.proto:1012Message describing whether or not graph nav is lost, and if it is lost, how lost it is. If robot is lost, this state can be reset by either: * Driving to an area where the robot's localization improves. * Calling SetLocalization RPC.
Used in:
bool is_lost = 1
Whether or not the robot is currently lost. If this is true, graph nav will reject NavigateTo or NavigateRoute RPCs.
int32 total_num_accepted_localizations = 2
The lost detector either accepts or rejects localizations based on a scoring criteria. This is the total number of localizations that have been accepted since the last SetLocalization RPC.
int32 total_num_rejected_localizations = 3
This is the total number of localizations that have been rejected since the last SetLocalization RPC.
int32 num_rejected_localizations_since_accepted = 4
This is the total number of localizations that have been rejected by the lost detector since either a localization was accepted, or a SetLocalization RPC.
float distance_traveled_with_rejected_localization = 5
This is the number of meters (3d translation of the robot body) the lost detector believes the robot to have traveled since it had a rejected localization.
optional last_accepted_localization = 6
This is the most recent localization the lost detector accepted.
optional last_rejected_localization = 7
This is the most recent localization that the lost detector rejected.
int32 num_consecutive_bad_edges = 8
The number of edges the LostDetector believes the robot has crossed without first getting an accepted localization.
optional params = 9
Parameters the lost detector is using.
message
graph_nav.proto:1044Parameters for the lost detector which control when it determines that we are lost. In general, when we start seeing "bad" localizations, (based on sensor data and map data agreement) we start counting the amount of time and distance the robot has traveled before we see a "good" localization. If this distance exceeds a threshold, we then start counting the number of edges that the robot has crossed with a "bad" localization. Once a number of edges crosses a threshold, we then declare the robot lost. Note that these thresholds are hierarchical; so we first start counting time, then distance, then number of edges.
Used in:
double max_time_with_bad_localization = 1
Maximum time (seconds) that the robot can walk with a bad localization before we start counting distance/edges with bad localization.
double max_distance_with_bad_localization = 2
The maximum distance the robot can walk (m) with a bad localization before we start counting the number of edges with bad localization.
int32 max_num_edges_with_bad_localization = 3
The maximum number of edges the robot can walk with a bad localization before we declare the robot to be lost.
LostDetectorStrictness strictness = 4
Determines how "strict" the lost detector is about declaring lost. This value is used to set the other thresholds.
Determines how "strict" the lost detector is about declaring lost.
Used in: , ,
LOST_DETECTOR_STRICTNESS_UNKNOWN = 0
Unset (defaults to STRICTNESS_DEFAULT).
LOST_DETECTOR_STRICTNESS_DISABLED = 1
Never declares lost.
LOST_DETECTOR_STRICTNESS_PERMISSIVE = 2
Declares lost less readily than default.
LOST_DETECTOR_STRICTNESS_DEFAULT = 3
Default lost detector strictness.
LOST_DETECTOR_STRICTNESS_STRICT = 4
Declares lost more readily than default.
message
map.proto:488General statistics on the map that is loaded into GraphNav on the robot, including information on the graph topology and snapshot data.
Used in: , , , , , , ,
optional waypoints = 1
Waypoints (including alternate route finding waypoints).
optional waypoint_snapshots = 2
Waypoint snapshots.
optional alternate_waypoints = 3
The alternate route finding waypoints (used for alternate path planning).
optional edges = 4
Edges (including alternate route finding edges).
optional edge_snapshots = 5
Edge snapshots.
optional alternate_edges = 6
Alternate edges (used for alternate path planning).
optional waypoint_anchors = 7
Anchors for waypoints. (For computing anchorings to fixed reference frames).
optional object_anchors = 8
Anchors for world objects (fiducials).
double total_path_length = 9
The total distance travelled along recorded edges by the robot in the loaded map.
message
map.proto:490Statistics from a particular type of object stored in the GraphNav map.
Used in:
int32 count = 1
The number of elements.
int64 num_bytes = 2
Lower bound on the number of bytes allocated for these elements on RAM inside the GraphNav server.
message
graph_nav.proto:311optional header = 1
repeated lease_use_results = 2
Results of using the various leases.
ModifyNavigationResponse.Status status = 3
Status code specific to the ModifyNavigationResponse.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
Modify request was accepted.
STATUS_UNRECOGNIZED_COMMAND = 2
The command ID wasn't the ID of the last command.
Used in:
STATUS_UNKNOWN = 0
An unknown / unexpected error occurred.
STATUS_OK = 1
Request was accepted.
STATUS_NO_TIMESYNC = 2
[Time Error] Client has not done timesync with robot.
STATUS_EXPIRED = 3
[Time Error] The command was received after its end time had already passed.
STATUS_TOO_DISTANT = 4
[Time Error] The command end time was too far in the future.
STATUS_ROBOT_IMPAIRED = 5
[Robot State Error] Cannot navigate a route if the robot has a critical perception fault, or behavior fault, or LIDAR not working.
STATUS_RECORDING = 6
[Robot State Error] Cannot navigate a route while recording a map.
STATUS_UNKNOWN_ROUTE_ELEMENTS = 8
[Route Error] One or more waypoints/edges are not in the map.
STATUS_INVALID_EDGE = 9
[Route Error] One or more edges do not connect to expected waypoints.
STATUS_NO_PATH = 20
[Route Error] There is no path to the specified route.
STATUS_CONSTRAINT_FAULT = 11
[Route Error] Route contained a constraint fault.
STATUS_FEATURE_DESERT = 13
[Route Error] Route contained too many waypoints with low-quality features.
STATUS_LOST = 14
[Route Error] Happens when you try to issue a navigate route while the robot is lost.
STATUS_NOT_LOCALIZED_TO_ROUTE = 16
[Route Error] Happens when the current localization doesn't refer to any waypoint in the route (possibly uninitialized localization).
STATUS_NOT_LOCALIZED_TO_MAP = 19
[Route Error] Happens when the current localization doesn't refer to any waypoint in the map (possibly uninitialized localization).
STATUS_COULD_NOT_UPDATE_ROUTE = 15
[Wrestling Errors] Happens when graph nav refuses to follow the route you specified. Try saying please?
STATUS_STUCK = 17
[Route Error] Happens when you try to issue a navigate to while the robot is stuck. Navigate a different route, or clear the route and try again.
STATUS_UNRECOGNIZED_COMMAND = 18
[Request Error] Happens when you try to continue a command that was either expired, or had an unrecognized id.
STATUS_AREA_CALLBACK_ERROR = 21
[Route Error] Happens when you try to navigate along a route and a needed callback is no longer available.
The result of the GPS command, if relevant.
Used in:
GPS_STATUS_UNKNOWN = 0
An unknown/unexpected error occurred.
GPS_STATUS_OK = 1
The GPS command was valid and can be executed.
GPS_STATUS_NO_COORDS_IN_MAP = 2
The GPS command could not be completed because the map does not have GPS coordinates, neither in waypoint annotations nor in the waypoint snapshot data. Please record the map using a GPS-enabled robot, or annotate the waypoints with custom GPS coordinates.
GPS_STATUS_TOO_FAR_FROM_MAP = 3
The GPS command could not be completed because the coordinates passed in were too far from any mapped GPS data.
Used in:
STATUS_UNKNOWN = 0
An unknown / unexpected error occurred.
STATUS_OK = 1
Request was accepted.
STATUS_NO_TIMESYNC = 2
[Time error] Client has not done timesync with robot.
STATUS_EXPIRED = 3
[Time error] The command was received after its end time had already passed.
STATUS_TOO_DISTANT = 4
[Time error]The command end time was too far in the future.
STATUS_ROBOT_IMPAIRED = 5
[Robot State Error] Cannot navigate a route if the robot has a critical perception fault, or behavior fault, or LIDAR not working.
STATUS_RECORDING = 6
[Robot State Error] Cannot navigate a route while recording a map.
STATUS_NO_ANCHORING = 7
[Route Error] There is no anchoring.
STATUS_NO_PATH = 8
[Route Error] There is no path to a waypoint near the specified goal. If any waypoints were found (but no path), the error_waypoint_ids field will be filled.
STATUS_FEATURE_DESERT = 10
[Route Error] Route contained too many waypoints with low-quality features.
STATUS_LOST = 11
[Route Error] Happens when you try to issue a navigate to while the robot is lost.
STATUS_NOT_LOCALIZED_TO_MAP = 13
[Route Error] Happens when the current localization doesn't refer to any waypoint in the map (possibly uninitialized localization).
STATUS_COULD_NOT_UPDATE_ROUTE = 12
[Wrestling error] Happens when graph nav refuses to follow the route you specified.
STATUS_STUCK = 14
[Route Error] Happens when you try to issue a navigate to while the robot is stuck. Navigate to a different waypoint, or clear the route and try again.
STATUS_UNRECOGNIZED_COMMAND = 15
[Request Error] Happens when you try to continue a command that was either expired, or had an unrecognized id.
STATUS_INVALID_POSE = 16
[Route Error] The pose is invalid, or known to be unachievable (upside-down, etc).
STATUS_AREA_CALLBACK_ERROR = 17
[Route Error] Happens when you try to navigate along a route and a needed callback is no longer available.
STATUS_INVALID_GPS_COMMAND = 18
[Route Error] The command contained an invalid GPS request. See gps_status for more details.
Used in:
STATUS_UNKNOWN = 0
An unknown / unexpected error occurred.
STATUS_OK = 1
Request was accepted.
STATUS_NO_TIMESYNC = 2
[Time error] Client has not done timesync with robot.
STATUS_EXPIRED = 3
[Time error] The command was received after its end time had already passed.
STATUS_TOO_DISTANT = 4
[Time error]The command end time was too far in the future.
STATUS_ROBOT_IMPAIRED = 5
[Robot State Error] Cannot navigate a route if the robot has a critical perception fault, or behavior fault, or LIDAR not working.
STATUS_RECORDING = 6
[Robot State Error] Cannot navigate a route while recording a map.
STATUS_UNKNOWN_WAYPOINT = 7
[Route Error] One or more of the waypoints specified weren't in the map.
STATUS_NO_PATH = 8
[Route Error] There is no path to the specified waypoint.
STATUS_FEATURE_DESERT = 10
[Route Error] Route contained too many waypoints with low-quality features.
STATUS_LOST = 11
[Route Error] Happens when you try to issue a navigate to while the robot is lost.
STATUS_NOT_LOCALIZED_TO_MAP = 13
[Route Error] Happens when the current localization doesn't refer to any waypoint in the map (possibly uninitialized localization).
STATUS_COULD_NOT_UPDATE_ROUTE = 12
[Wrestling error] Happens when graph nav refuses to follow the route you specified.
STATUS_STUCK = 14
[Route Error] Happens when you try to issue a navigate to while the robot is stuck. Navigate to a different waypoint, or clear the route and try again.
STATUS_UNRECOGNIZED_COMMAND = 15
[Request Error] Happens when you try to continue a command that was either expired, or had an unrecognized id.
STATUS_AREA_CALLBACK_ERROR = 16
[Route Error] Happens when you try to navigate along a route and a needed callback is no longer available.
message
graph_nav.proto:886Data for a Area Callback region
Used in:
string description = 1
human readable name for the region
string service_name = 2
service name for the Area Callback region
ActiveRegionInformation.AreaCallbackStatus region_status = 3
Status of the Area Callback region
Used in:
STATUS_UNKNOWN = 0
STATUS_NAVIGATING = 1
The robot is navigating the Area Callback region
STATUS_WAITING = 2
The robot is waiting for assistance to navigate through the Area Callback region
STATUS_CALLBACK_IN_CONTROL = 3
The Area Callback service is in control of the robot
Indicates whether the robot thinks its current path is blocked by an obstacle. This will be set when Status is STATUS_FOLLOWING_ROUTE, or STATUS_STUCK, and will be BLOCKAGE_STATUS_UNKNOWN in all other cases.
Used in:
BLOCKAGE_STATUS_UNKNOWN = 0
BLOCKAGE_STATUS_ROUTE_CLEAR = 1
The robot believes the path forward to be clear of obstacles.
BLOCKAGE_STATUS_ROUTE_BLOCKED_TEMPORARILY = 2
The robot believes there is an obstacle in the path which it can't get around easily. It will attempt to get around the obstacle, and if all else fails it will declare itself stuck.
BLOCKAGE_STATUS_STUCK = 3
The robot has given up trying to get around perceived obstacles in the path and has declared itself stuck. This will only ever be set when Status is STATUS_STUCK.
When the robot is following a route (and Status is STATUS_FOLLOWING_ROUTE), this gives additional detail about what the robot is doing to follow that route. When Status is not STATUS_FOLLOWING_ROUTE, this will be set to ROUTE_FOLLOWING_STATUS_UNKNOWN.
Used in:
ROUTE_FOLLOWING_STATUS_UNKNOWN = 0
ROUTE_FOLLOWING_STATUS_FOLLOWING_ROUTE = 1
The robot is following the nominal path to the goal, either from a request or from internal path planning.
ROUTE_FOLLOWING_STATUS_RETURNING_TO_ROUTE = 2
The robot is trying to get back to the nominal path to the goal, either because it was not on the nominal path originally, or because it was moved away from the path.
ROUTE_FOLLOWING_STATUS_FOLLOWING_ALTERNATE_ROUTE = 3
The robot is taking a different path through the map via edges/waypoints to get around a perceived obstacle. This might take it through a different part of the building.
ROUTE_FOLLOWING_STATUS_EXPLORING = 4
The robot is walking to a different, nearby part of the map to find a path around a perceived blockage.
Used in:
STATUS_UNKNOWN = 0
An unknown / unexpected error occurred.
STATUS_FOLLOWING_ROUTE = 1
The robot is currently, successfully following the route.
STATUS_REACHED_GOAL = 2
The robot has reached the final goal of the navigation request.
STATUS_NO_ROUTE = 3
There's no route currently being navigated. This can happen if no command has been issued, or if the graph has been changed during navigation.
STATUS_NO_LOCALIZATION = 4
Robot is not localized to a route.
STATUS_LOST = 5
Robot appears to be lost.
STATUS_STUCK = 6
Robot appears stuck and unable to make progress, but can still navigate to other destinations. stuck_reason provides more details on the reason that caused the robot to become stuck.
STATUS_COMMAND_TIMED_OUT = 7
The command expired.
STATUS_ROBOT_IMPAIRED = 8
Cannot navigate a route if the robot has a critical perception fault, or behavior fault, or LIDAR not working. See impaired_status for details.
STATUS_CONSTRAINT_FAULT = 11
The route constraints were not feasible.
STATUS_COMMAND_OVERRIDDEN = 12
The command was replaced by a new command
STATUS_NOT_LOCALIZED_TO_ROUTE = 13
The localization or route changed mid-traverse.
STATUS_LEASE_ERROR = 14
The lease is no longer valid.
STATUS_AREA_CALLBACK_ERROR = 15
An error occurred with an Area Callback in a way that graph nav was unable to recover from. Navigating to another location may also fail. Lease errors will be reported via STATUS_LEASE_ERROR instead.
If status is STATUS_STUCK, this enum provides reasons differentiating various cases that can cause the robot to re
Used in:
STUCK_REASON_UNKNOWN = 0
STUCK_REASON_OBSTACLE = 1
The robot failed to find a way past an obstacle.
STUCK_REASON_AREA_CALLBACK_BLOCKED = 2
An area callback reported that it is blocked.
STUCK_REASON_AREA_CALLBACK_FAILED = 3
An area callback failed, but in a way that the robot is still able to navigate to other locations.
STUCK_REASON_GOAL_BLOCKED = 4
The robot has seen the goal and perceived that there is no pose it can navigate to to reach the goal. There is no value in rerouting.
message
map_processing.proto:197Represents an interval in x, y, z and yaw around some center. Some value x will be within the bounds if center - x_bounds <= x >= center + x_bounds. If the values are left at zero, the bounds are considered to be unconstrained. The center of the bounds is left implicit, and should be whatever this message is packaged with.
Used in: , ,
double x_bounds = 1
Bounds on the x position in meters.
double y_bounds = 2
Bounds on the y position in meters.
double z_bounds = 3
Bounds on the z position in meters.
double yaw_bounds = 4
Bounds on the yaw (rotation around z axis) in radians.
message
visual_features.proto:80A 3D position with a covariance estimate.
Used in:
optional position = 1
The vector is to be interpreted as a 3D position in a frame.
optional covariance = 2
3x3 covariance matrix representing uncertainty in the position.
message
map_processing.proto:295Parameters for processing an anchoring.
Used in:
optional optimizer_params = 1
optional measurement_params = 2
optional weights = 3
optional optimize_existing_anchoring = 4
If true, the anchoring which already exists on the server will be used as the initial guess for the optimizer. Otherwise, a new anchoring will be generated for every waypoint which doesn't have a value passed in through initial_hint. If no hint is provided, and this value is false, every waypoint will be given a starting anchoring based on the oldest waypoint in the map.
optional gravity_ewrt_seed = 5
The optimizer will try to keep the orientation of waypoints consistent with gravity. If provided, this is the gravity direction expressed with respect to the seed. This will be interpreted as a unit vector. If not filled out, a default of (0, 0, -1) will be used.
message
map_processing.proto:304Parameters which affect the measurements the optimizer uses to process the anchoring.
Used in:
optional use_kinematic_odometry = 1
If true, waypoints which share the same kinematic odometry frame will be constrained to one another using it.
optional use_visual_odometry = 2
If true, waypoints which share the same visual odometry frame will be constrained to one another using it.
optional use_gyroscope_measurements = 3
If true, waypoints will be constrained so that the apparent pose of the robot w.r.t the waypoint at the time of recording is consistent with gravity.
optional use_loop_closures = 4
If true, edges which were created by topology processing via loop closures will be used as constraints.
optional use_world_objects = 5
If true, world object measurements will be used to constrain waypoints to one another when those waypoints co-observe the same world object.
optional use_gps = 6
If true, GPS measurements stored in waypoint snapshots will be used to help constrain the anchoring.
message
map_processing.proto:297Parameters affecting the underlying optimizer.
Used in:
optional max_iters = 1
Maximum iterations of the optimizer to run.
optional max_time_seconds = 2
Maximum time the optimizer is allowed to run before giving up.
message
map_processing.proto:327Relative weights to use for each of the optimizer's terms. These can be any positive value. If set to zero, a reasonable default will be used. In general, the higher the weight, the more the optimizer will care about that particular measurement.
Used in:
double kinematic_odometry_weight = 1
double visual_odometry_weight = 2
double world_object_weight = 3
double hint_weight = 4
double gyroscope_weight = 5
double loop_closure_weight = 6
double gps_weight = 7
message
map_processing.proto:439Used in:
GPSResult.GPSStatus status = 1
Overall status of the GPS embedding optimization.
optional ecef_tform_seed = 2
Pose of the "seed" frame of this optimization in the Earth-Centered-Earth-Fixed (ECEF) frame. This can be used to estimate the pose of every waypoint in the ECEF frame via: ecef_tform_waypoint = ecef_tform_seed * anchoring.waypoints[waypoint_id].seed_tform_waypoint
int32 num_measurements_used = 3
This is the number of GPS measurements actually used to compute the GPS embedding.
Status of the GPS embedding optimization.
Used in:
GPS_STATUS_UNKNOWN = 0
GPS_STATUS_OK = 1
Managed to find an ECEF transform.
GPS_STATUS_NOT_ENOUGH_MEASUREMENTS = 2
Not enough high quality GPS measurements in the map.
Used in:
STATUS_UNKNOWN = 0
Programming error.
STATUS_OK = 1
Success.
STATUS_MISSING_WAYPOINT_SNAPSHOTS = 2
Not all of the waypoint snapshots exist on the server. Upload them to continue.
STATUS_INVALID_GRAPH = 3
The graph is invalid topologically, for example containing
STATUS_OPTIMIZATION_FAILURE = 4
missing waypoints referenced by edges.
The optimization failed due to local minima or an
STATUS_INVALID_PARAMS = 5
ill-conditioned problem definition.
The parameters passed to the optimizer do not make sense (e.g negative weights).
STATUS_CONSTRAINT_VIOLATION = 6
One or more anchors were moved outside of the desired constraints.
STATUS_MAX_ITERATIONS = 7
The optimizer reached the maximum number of iterations before converging.
STATUS_MAX_TIME = 8
The optimizer timed out before converging.
STATUS_INVALID_HINTS = 9
One or more of the hints passed in to the optimizer are
STATUS_MAP_MODIFIED_DURING_PROCESSING = 10
invalid (do not correspond to real waypoints or objects).
Tried to write the anchoring after processing, but another client may have
STATUS_INVALID_GRAVITY_ALIGNMENT = 11
modified the map. Try again.
An anchor hint (waypoint or fiducial) had an
message
map_processing.proto:101Parameters for how to check for collisions when creating loop closures. The system will avoid creating edges in the map that the robot cannot actually traverse due to the presence of nearby obstacles.
Used in:
optional check_edges_for_collision = 1
By default, this is true.
optional collision_check_robot_radius = 2
Assume that the robot is a sphere with this radius. Only accept a loop closure if this spherical robot can travel in a straight line from one waypoint to the other without hitting obstacles.
optional collision_check_height_variation = 3
Consider significant height variations along the edge (like stairs or ramps) to be obstacles. The edge will not be created if there is a height change along it of more than this value according to the nearby sensor data.
message
map_processing.proto:36Parameters to control point cloud sparse feature matching.
Used in:
optional do_feature_matching = 1
If true, feature matching will be performed. If both ICP and Feature matching are used, feature matching will be performed first for a coarse alignment, followed by ICP for a local refinement.
message
map_processing.proto:77Parameters for how to close a loop using fiducials (AprilTags). This infers which waypoints should be connected to one another based on shared observations of AprilTags. Note that multiple disconnected subgraphs (for example from multiple recording sessions) can be merged this way.
Used in:
optional min_loop_closure_path_length = 1
The minimum distance between waypoints found by walking a path from one waypoint to the other using only the existing edges in the map. Set this higher to avoid creating small shortcuts along the existing path. Note that this is a 2d path length.
optional max_loop_closure_edge_length = 2
Once a loop closure candidate is found, the system creates an edge between the candidate waypoints. Only create the edge if it is shorter than this value. Note that this is a 3d edge length.
optional max_fiducial_distance = 3
Maximum distance to accept between a waypoint and a fiducial detection to use that fiducial detection for generating loop closure candidates.
optional max_loop_closure_height_change = 4
The maximum apparent height change of the created edge that we are willing to accept between waypoints. This avoids closing loops up ramps, stairs, etc. or closing loops where there is significant odometry drift.
optional prune_edges = 5
If true, redundant edges will be ignored, and only the "best" in a small area will be selected (true by default).
message
map_processing.proto:28Parameters for how to refine loop closure edges using iterative closest point matching. If both ICP and Feature matching are used, feature matching will be performed first for a coarse alignment, followed by ICP for a local refinement.
Used in:
optional icp_iters = 1
The maximum number of iterations to run. Set to zero to skip ICP processing.
optional max_point_match_distance = 2
The maximum distance between points in the point cloud we are willing to accept for matches.
message
map_processing.proto:44Parameters for how to close loops using odometry. This infers which waypoints should be connected to one another based on the odometry measurements in the map.
Used in:
optional max_loop_closure_path_length = 1
The maximum distance between waypoints found by walking a path from one waypoint to the other using only the existing edges in the map. Beyond this distance, we are unwilling to trust odometry.
optional min_loop_closure_path_length = 2
The minimum distance between waypoints found by walking a path from one waypoint to the other using only the existing edges in the map. Set this higher to avoid creating small shortcuts along the existing path. Note that this is a 2d path length.
optional max_loop_closure_height_change = 3
The maximum apparent height change of the created edge that we are willing to accept between waypoints. This avoids closing loops up ramps, stairs, etc. or closing loops where there is significant odometry drift.
optional max_loop_closure_edge_length = 4
Once a loop closure candidate is found, the system creates an edge between the candidate waypoints. Only create the edge if it is shorter than this value. Note that this is a 3d edge length.
optional num_extra_loop_closure_iterations = 5
Use prior loop closures to infer new odometry based loop closures. This is useful when other sources of loop closures (like fiducials) are being used. The existence of those loop closures allows the system to infer other nearby loop closures using odometry. Alternatively, the user may call the ProcessTopology RPC multiple times to achieve the same effect.
optional prune_edges = 6
If true, redundant edges will be ignored, and only the "best" in a small area will be selected (true by default).
message
map_processing.proto:115Parameters which control topology processing. In general, anything which isn't filled out will be replaced by reasonable defaults.
Used in:
optional do_odometry_loop_closure = 1
True by default -- generate loop closure candidates using odometry.
optional odometry_loop_closure_params = 2
Parameters for generating loop closure candidates using odometry.
optional icp_params = 3
Parameters for refining loop closure candidates using iterative closest point cloud matching.
optional do_fiducial_loop_closure = 4
True by default -- generate loop closure candidates using fiducials.
optional fiducial_loop_closure_params = 5
Parameters for generating loop closure candidates using fiducials.
optional collision_check_params = 6
Parameters which control rejecting loop closure candidates which collide with obstacles.
double timeout_seconds = 7
Causes the processing to time out after this many seconds. If not set, a default of 45 seconds will be used. If this timeout occurs before the overall RPC timeout, a partial result will be returned with ProcessTopologyResponse.timed_out set to true. Processing can be continued by calling ProcessTopology again.
optional feature_matching_params = 8
Controls whether and how the service performs sparse feature matching.
Used in:
STATUS_UNKNOWN = 0
Programming error.
STATUS_OK = 1
Success.
STATUS_MISSING_WAYPOINT_SNAPSHOTS = 2
Not all of the waypoint snapshots exist on the server. Upload them to continue.
STATUS_INVALID_GRAPH = 3
The graph is invalid topologically, for example containing
STATUS_MAP_MODIFIED_DURING_PROCESSING = 4
missing waypoints referenced by edges.
Tried to write the anchoring after processing, but another client may have
message
recording.proto:25The RecordingEnvironment is a set of annotation information and a name for the current environment that will persist for all edges and waypoints until it is changed or updated
Used in: , , ,
string name_prefix = 1
This will be prepended to the start of every waypoint name.
optional waypoint_environment = 2
Persistent waypoint annotation that will be merged in to all waypoints in this recording.
optional edge_environment = 3
Persistent edge annotation that will be merged in to all edges in this recording.
message
map.proto:526Defines a region in a map. Regions are shapes, commonly they are boxes. Many waypoints may share the same regions. Regions do not need to cover the waypoint itself. A common use for such regions is to define certain parts of the point cloud as being unreliable for localization. Note that this is a different concept than the LocalizeRegion, which is used to determine where the robot's body must be relative to the waypoint for it to localize -- the RegionWithFrame instead can be used to label data near the waypoint. *Regions and Reference Frames* -- regions are stored inside waypoint annotations as "RegionWithFrames". These consist of a region and a named reference frame relative to the waypoint (such as "odom" or "seed", or "waypoint" etc).
Used in:
string region_id = 1
Unique identifier of the region within a map. This will be used to deduplicate regions that many waypoints may reference. Note that the transform of the region is defined with respect to this waypoint's KO frame, so the same region may exist in several waypoints while having different transforms in each case. Regions with the same ID are not guaranteed to be unique. Graph Nav will use whatever regions exist in the current waypoint only, and will ignore all other regions; so if you want Graph Nav to use a region in multiple waypoints, you must duplicate the region into each waypoint in which it is to be used.
oneof shape
bounding_box = 2
Oriented bounding box defining the region. The axes are defined relative to the "base frame" for this region. See RegionWithFrame for how this frame may be defined.
Region.DataFilter data_filter = 3
How (if at all) the region affects data filtering for scan matching.
Defines how scan match data is filtered near this waypoint. Data filters are logical set operators expressed on sets of data near the waypoint. Notes on interactions: If there are multiple regions marked as INCLUDE_ONLY, data that falls within any of these regions will be used, that is the operation of many DATA_FILTER_INCLUDE_ONLY regions is a logical set union. Conversely, DATA_FILTER_IGNORE operators override DATA_FILTER_INCLUDE_ONLY. For example, if there are 3 regions, A, B and C; and region A is marked as INCLUDE_ONLY, B is marked as INCLUDE_ONLY, and C is marked as IGNORE, the data that will be used for scan matching is: (A _u_ B) ~ C (that is, union(A, B) excluding C).
Used in:
DATA_FILTER_UNKNOWN = 0
Defaults to DATA_FILTER_NONE.
DATA_FILTER_NONE = 1
No special considerations for scan matching in this region.
DATA_FILTER_IGNORE = 2
No scan match data falling within this region will be used.
DATA_FILTER_INCLUDE_ONLY = 3
Only data from within this region will be used.
message
area_callback.proto:152Description of an Area Callback region at the time of crossing
Used in:
string region_id = 1
The unique id of the region we are entering.
string description = 2
Human-readable description of the region we are entering.
optional route = 3
The planned route through the region.
bool starting_inside_region = 4
Flag that indicates that the robot is already inside the callback region at the beginning of the callback, rather than starting from the edge of the region as usual. This can happen in some cases when the robot gets stuck inside the region, and restarts with a new navigation command.
message
map.proto:562Defines a region and a transform near a specific waypoint. Regions will only be used if they are attached to waypoint annotations. Regions may be duplicated over many waypoints.
Used in:
optional region = 1
The region attached to this waypoint.
string base_frame_name = 2
Reference frame that the region's transform is defined with respect to. For example, "waypoint" for the waypoint's reference frame, or "odom" for the odometry frame at the time of waypoint recording.
optional base_frame_tform_region = 3
Transform of the region in the base frame.
message
graph_nav.proto:997Message describing the state of a remote point cloud service (such as a velodyne).
Used in:
string service_name = 1
The name of the point cloud service.
bool exists_in_directory = 2
Boolean indicating if the point cloud service was registered in the robot's directory with the provided name.
bool has_data = 3
Boolean indicating if the point cloud service is currently outputting data.
message
nav.proto:20Route that the robot should follow or is currently following.
Used in: , , , , ,
repeated string waypoint_id = 2
Ordered list of waypoints to traverse, starting from index 0.
repeated edge_id = 3
Ordered list of edges to traverse between those waypoints.
Used in:
STATUS_UNKNOWN = 0
UNKNOWN should never be used.
STATUS_OK = 1
The AreaCallback has acknowledged the route change.
STATUS_INVALID_COMMAND_ID = 2
The request command id does not exist or is no longer executing.
message
graph_nav.proto:439These parameters are specific to how the robot follows a specified route in NavigateRoute.
For each enum in this message, if UNKNOWN is passed in, we default to one of the values (indicated in the comments). Passing UNKNOWN is not considered a programming error.
Used in: ,
RouteFollowingParams.StartRouteBehavior new_cmd_behavior = 1
RouteFollowingParams.ResumeBehavior existing_cmd_behavior = 2
RouteFollowingParams.RouteBlockedBehavior route_blocked_behavior = 3
This setting applies when a NavigateRoute command is issued with the same route and final-waypoint-offset. It is not necessary that command_id indicate the same command. The expected waypoint is the last waypoint that GraphNav was autonomously navigating to.
Used in:
RESUME_UNKNOWN = 0
The mode is unset.
RESUME_RETURN_TO_UNFINISHED_ROUTE = 1
The robot will find the shortest path to any point on the route after the furthest-along traversed edge, and go to the point that gives that shortest path. Then, the robot will follow the rest of the route from that point. This is the default.
RESUME_FAIL_WHEN_NOT_ON_ROUTE = 2
The robot will fail the command with status STATUS_NOT_LOCALIZED_TO_ROUTE.
This setting applies when the robot discovers that the route is blocked.
Used in: , ,
ROUTE_BLOCKED_UNKNOWN = 0
The mode is unset.
ROUTE_BLOCKED_REROUTE = 1
For NavigateToRequests, the robot will find the shortest path to the destination that avoids the blockage. For NavigateRouteRequests, the robot will find the shortest path to any point after the furthest-along blockage, and after the furthest-along traversed edge, and go to the point that gives that shortest path. Then, the robot will follow the rest of the route from that point. If multiple points on the route are similarly close to the robot, the robot will prefer the earliest on the route. This is the default.
ROUTE_BLOCKED_FAIL = 2
The robot will fail the command with status STATUS_STUCK;
This setting applies when a new NavigateRoute command is issued (different route or final-waypoint-offset), and command_id indicates a new command.
Used in:
START_UNKNOWN = 0
The mode is unset.
START_GOTO_START = 1
The robot will find the shortest path to the start of the route, possibly using edges that are not in the route. After going to the start, the robot will follow the route.
START_GOTO_ROUTE = 2
The robot will find the shortest path to any point on the route, and go to the point that gives that shortest path. Then, the robot will follow the rest of the route from that point. If multiple points on the route are similarly close to the robot, the robot will prefer the earliest on the route. This is the default.
START_FAIL_WHEN_NOT_ON_ROUTE = 3
The robot will fail the command with status STATUS_NOT_LOCALIZED_TO_ROUTE.
message
graph_nav.proto:222Used in: , ,
(message has no fields)
message
graph_nav.proto:112Info on whether the robot's current sensor setup is compatible with the recorded data in the map.
Used in: , , ,
bool map_has_lidar_data = 1
If true, the loaded map has LIDAR data in it.
bool robot_configured_for_lidar = 2
If true, the robot is currently configured to use LIDAR data.
message
graph_nav.proto:46The SetLocalization request is used to initialize or reset the localization of GraphNav to a map. A localization consists of a waypoint ID, and a pose of the robot relative to that waypoint. GraphNav uses the localization to decide how to navigate through a map. The SetLocalizationRequest contains parameters to help find a correct localization. For example, AprilTags (fiducials) may be used to set the localization, or the caller can provide an explicit guess of the localization. Once the SetLocalizationRequest completes, the current localization to the map will be modified, and can be retrieved using a GetLocalizationStateRequest.
Used as request type in: GraphNavService.SetLocalization
Used as field type in: ,
optional header = 1
Common request header.
optional initial_guess = 3
Operator-supplied guess at localization. In this localization message, only waypoint_id and waypoint_tform_body will be used. All other fields are ignored. If the message is not provided, the initial guess will be assumed to be the identity transform to whatever waypoint was requested for methods that require it. Use initial_guess.waypoint_id to restrict the SetLocalizationRequest to specific waypoints.
optional ko_tform_body = 4
Robot pose when the initial_guess was made. This overcomes the race that occurs when the client is trying to initialize a moving robot. GraphNav will use its local ko_tform_body and this ko_tform_body to update the initial localization guess, if necessary.
double max_distance = 5
The max distance [meters] is how far away the robot is allowed to localize from the position supplied in the initial guess. If not specified, the offset is used directly. Otherwise it searches a neighborhood of the given size.
double max_yaw = 6
The max yaw [radians] is how different the localized yaw is allowed to be from the supplied yaw in the initial guess. If not specified, the offset is used directly. Otherwise it searches a neighborhood of the given size.
SetLocalizationRequest.FiducialInit fiducial_init = 7
Tells the initializer whether to use fiducials, and how to use them.
int32 use_fiducial_id = 8
If using FIDUCIAL_INIT_SPECIFIC, this is the specific fiducial ID to use for initialization. If no detection of this fiducial exists, the service will return STATUS_NO_MATCHING_FIDUCIAL. If detections exist, but are low quality, STATUS_FIDUCIAL_TOO_FAR_AWAY, FIDUCIAL_TOO_OLD, or FIDUCIAL_POSE_UNCERTAIN will be returned.
bool do_ambiguity_check = 10
If true, consider how nearby localizations appear (like turned 180).
bool restrict_fiducial_detections_to_target_waypoint = 11
If using FIDUCIAL_INIT_SPECIFIC and this is true, the initializer will only consider fiducial detections from the target waypoint (from initial_guess). Otherwise, if the target waypoint does not contain a good measurement of the desired fiducial, nearby waypoints may be used to infer the robot's location.
oneof refinement
bool refine_fiducial_result_with_icp = 9
If true, and we are using fiducials during initialization, will run ICP after the fiducial was used for an initial guess.
refine_with_visual_features = 12
Improve localization based on images from body cameras
Used in:
FIDUCIAL_INIT_UNKNOWN = 0
It is a programming error to use this one.
FIDUCIAL_INIT_NO_FIDUCIAL = 1
Ignore fiducials during initialization.
FIDUCIAL_INIT_NEAREST = 2
Localize to the nearest fiducial in any waypoint.
FIDUCIAL_INIT_NEAREST_AT_TARGET = 3
Localize to nearest fiducial at the target waypoint (from initial_guess).
FIDUCIAL_INIT_SPECIFIC = 4
Localize to the given fiducial at the target waypoint (from
Used in:
QUALITY_CHECK_UNKNOWN = 0
Unset. Note that the quality check is only performed if the overall Status enum returns STATUS_SUCCESS, and will be unset otherwise.
QUALITY_CHECK_SUCCESS = 1
The quality check passed.
QUALITY_CHECK_POOR_POINT_CLOUD_MATCH = 2
After applying the localization, a poor point cloud match to the map was detected. This can happen if, for example, the map has changed, or the starting location of the robot is now very different than it was at recording time.
QUALITY_CHECK_POOR_GRAVITY_ALIGNMENT = 3
After applying the localization, Graph Nav checked the localization, and found that the robot's gravity vector does not align with the map's. This can happen if a fiducial being used to align to the map was detected wrongly during recording, or if the robot's IMU is miscalibrated. It can also occur when the initial guess passed in to the SetLocalization RPC is in the incorrect reference frame.
QUALITY_CHECK_SKIPPED = 4
There wasn't enough data to make a determination about quality.
QUALITY_CHECK_BAD_HEIGHT = 5
The prior passed in is too different from the expected height of the robot e.w.r.t the waypoint.
Used in:
STATUS_UNKNOWN = 0
The status is unknown/unset.
STATUS_OK = 1
Localization success.
STATUS_ROBOT_IMPAIRED = 2
Robot is experiencing a condition that prevents localization.
STATUS_UNKNOWN_WAYPOINT = 3
The given waypoint is unknown by the system. This could be due to a client error, or because the graph was changed out from under the client.
STATUS_ABORTED = 4
Localization was aborted, likely because of a new request.
STATUS_FAILED = 5
Failed to localize for some other reason; see the error_report for details. This is often because the initial guess was incorrect.
STATUS_FIDUCIAL_TOO_FAR_AWAY = 6
Failed to localize because the fiducial requested by 'use_fiducial_id' was too far away from the robot.
STATUS_FIDUCIAL_TOO_OLD = 7
Failed to localize because the fiducial requested by 'use_fiducial_id' had a detection time that was too far in the past.
STATUS_NO_MATCHING_FIDUCIAL = 8
Failed to localize because the fiducial requested by 'use_fiducial_id' did not exist in the map at the required location.
STATUS_FIDUCIAL_POSE_UNCERTAIN = 9
Failed to localize because the fiducial requested by 'use_fiducial_id' had an unreliable pose estimation, either in the current detection of that fiducial, or in detections that were saved in the map. Note that when using FIDUCIAL_INIT_SPECIFIC, fiducial detections at the target waypoint will be used so long as they are not uncertain -- otherwise, detections at adjacent waypoints may be used. If there exists no uncertain detection of the fiducial near the target waypoint in the map, the service returns this status.
STATUS_INCOMPATIBLE_SENSORS = 10
The localization could not be set, because the map was recorded using a different sensor setup than the robot currently has onboard. See SensorStatus for more details.
STATUS_VISUAL_ALIGNMENT_FAILED = 11
Visual feature based alignment failed or the pose solution was considered unreliable.
STATUS_NO_MAP_LOADED = 12
Failed to localize because there is no map loaded.
message
graph_nav.proto:177Used in:
optional alternate_robot_tform_waypoint = 1
Example of a potentially ambiguous localization near the result of the initialization.
Used in:
STATUS_UNKNOWN = 0
Status is unknown/unset.
STATUS_OK = 1
Recording has been started.
STATUS_COULD_NOT_CREATE_WAYPOINT = 2
In this case we tried to start recording, but GraphNav was internally still waiting for some data from the robot.
STATUS_FOLLOWING_ROUTE = 3
Can't start recording because the robot is following a route.
STATUS_NOT_LOCALIZED_TO_EXISTING_MAP = 4
When recording branches, the robot is not localized to the existing map before starting to record a new branch.
STATUS_MISSING_FIDUCIALS = 5
Can't start recording because the robot doesn't see the required fiducials.
STATUS_MAP_TOO_LARGE_LICENSE = 6
Can't start recording because the map was too large for the license.
STATUS_REMOTE_CLOUD_FAILURE_NOT_IN_DIRECTORY = 7
A required remote cloud did not exist in the service directory.
STATUS_REMOTE_CLOUD_FAILURE_NO_DATA = 8
A required remote cloud did not have data.
STATUS_FIDUCIAL_POSE_NOT_OK = 9
All fiducials are visible but at least one pose could not be determined accurately.
STATUS_TOO_FAR_FROM_EXISTING_MAP = 10
When recording branches, the robot is too far from the existing map when starting to record a new branch.
STATUS_ROBOT_IMPAIRED = 11
Unable to start recording because the robot is impaired. See impaired_state for more details.
message
area_callback.proto:50Information about how the robot should behave when stopping at a location.
Used in: ,
StopConfiguration.FaceDirection face_direction = 3
Which direction the robot should face when lining up at a waypoint.
bool face_stairs_if_present = 5
If true, always align to stairs at the start of the callback. Overrides face_direction if stairs are found.
optional face_yaw_offset = 4
Offset applied to the above facing direction (radians).
optional max_distance = 1
How close the robot needs to be to the desired pose (meters).
optional max_yaw = 2
How close the robot needs to be to the desired pose (radians).
What direction robot should face.
Used in:
FACE_DIRECTION_UNKNOWN = 0
FACE_DIRECTION_ALONG_ROUTE = 1
(Default) Face along the direction of the next edges in the route, regardless of the waypoint orientation.
FACE_DIRECTION_WAYPOINT_EXACT = 2
Face in the direction of the recorded waypoint.
FACE_DIRECTION_WAYPOINT_AUTO = 3
Face in the direction of the recorded waypoint, but if traversing the region in the opposite direction to how it was recorded, flip the orientation 180 degrees.
FACE_DIRECTION_REGION_END = 4
Face in the direction of the end of the region.
Used in:
STATUS_UNKNOWN = 0
Status is unknown/unset.
STATUS_OK = 1
Recording is stopped.
STATUS_NOT_LOCALIZED_TO_END = 2
In this case we tried to stop recording, but had an incorrect localization. graph_nav is expected to be localized to the final waypoint in the chain before we stop recording.
STATUS_NOT_READY_YET = 3
The robot is still processing the map it created to where the robot is currently located. You can't stop recording until that processing is finished. You should not move the robot, then try to stop recording again after 1-2 seconds.
message
graph_nav.proto:227Parameters describing how to travel along a route.
Used in: , , , , , ,
oneof cartesian_distance_parameters
double max_distance = 1
Threshold for the maximum distance [meters] that defines a circular region for when we have reached the final waypoint.
box_region = 15
Oriented 2D bounding box [meters & radians] that defines an rectangular region for when we have reached the final waypoint.
double max_yaw = 2
Threshold for the maximum yaw [radians] that defines when we have reached the final waypoint (ignored if ignore_final_yaw is set to true).
optional velocity_limit = 3
Speed the robot should use. Omit to let the robot choose.
bool ignore_final_yaw = 4
If true, the robot will only try to achieve the final translation of the route. Otherwise, it will attempt to achieve the yaw as well.
double max_corridor_distance = 18
Max distance from the recorded edge that the robot is allowed to travel when avoiding obstacles or optimized its path. This is half of the full width of the corridor the robot may walk within. If this value is not set, the robot will choose a default corridor width.
TravelParams.FeatureQualityTolerance feature_quality_tolerance = 5
bool disable_directed_exploration = 6
Disable directed exploration to skip blocked portions of route
bool disable_alternate_route_finding = 8
Disable alternate-route-finding; overrides the per-edge setting in the map.
Edge.Annotations.PathFollowingMode path_following_mode = 9
Path following mode
optional blocked_path_wait_time = 10
Time to wait for blocked path to clear (seconds)
Edge.Annotations.GroundClutterAvoidanceMode ground_clutter_mode = 11
Ground clutter avoidance mode.
LostDetectorStrictness lost_detector_strictness = 14
The strictness at which the lost detector will declare the robot lost during this command. Note that this level of strictness will continue to apply even if the robot is teleoperated by the user. Changing the level of strictness also resets the lost detector. So if the robot is lost, issuing a new command with a lower level of strictness will cause the robot to continue as if it were not lost. Issuing a command with LOST_DETECTOR_STRICTNESS_UNKNOWN results in no change.
TravelParams.PathPlannerMode planner_mode = 17
Indicates whether robot will navigate through areas with poor quality features
Used in:
TOLERANCE_UNKNOWN = 0
Unknown value
TOLERANCE_DEFAULT = 1
Navigate through default number of waypoints with poor quality features
TOLERANCE_IGNORE_POOR_FEATURE_QUALITY = 2
Navigate through unlimited number of waypoints with poor quality features
Determines which local path planner to use.
Used in: ,
PLANNER_MODE_UNKNOWN = 0
Unknown value.
PLANNER_MODE_DEFAULT = 1
Use default path planner. Currently this is the short range planner.
PLANNER_MODE_SHORT_RANGE = 2
Use short range planner.
PLANNER_MODE_LONG_RANGE = 3
Use long range planner. This is an experimental feature that helps the robot navigate around large obstacles that were not present during mission recording. NOTE: Alternate route-finding waypoints are disabled when using the long range planner.
Used in:
STAGE_UNKNOWN = 0
STAGE_TO_START = 1
Traveling to the start of the region.
STAGE_AT_START = 2
Waiting at the start of the region.
STAGE_TO_END = 3
Traveling to the end of the region.
STAGE_AT_END = 4
Waiting at the end of the region.
message
area_callback.proto:285Used as response type in: AreaCallbackService.UpdateCallback
Used as field type in:
optional header = 1
Common response header.
UpdateCallbackResponse.Status status = 2
Return status for the request.
oneof response
Enumeration of ways navigation callback can ask Graph Nav to continue operating.
policy = 3
Set the control policy that Graph Nav should use when crossing this region, and how and when Graph Nav should delegate control to or wait for the callback. This is the expected way to respond, and changing the policy is how a callback instructs graph nav to wait or continue on.
error = 4
An error has occurred. Graph Nav will stop calling UpdateCallback and will call EndCallback.
complete = 5
The area callback is complete. Graph Nav will stop calling UpdateCallback and will call EndCallback.
optional localization = 6
Localization changes inform Graph Nav when the callback has moved the robot, and are ignored unless callback has control of the robot.
message
area_callback.proto:384Used in:
(message has no fields)
message
area_callback.proto:360Used in:
Error.ErrorType error = 1
repeated lease_use_results = 2
Details about how the lease was used. Only set when error == ERROR_LEASE.
Used in:
ERROR_UNKNOWN = 0
UNKNOWN should never be used.
ERROR_BLOCKED = 1
The callback has determined that this way is impassable.
ERROR_CALLBACK_FAILED = 2
Something went wrong with the callback.
ERROR_LEASE = 3
A lease error occurred while executing commands.
ERROR_TIMED_OUT = 4
The callback has exceeded allowed execution time.
message
area_callback.proto:340Used in:
NavPolicy.Option at_start = 1
Policy for what Graph Nav should do at the start of the region.
NavPolicy.Option at_end = 2
Policy for what Graph Nav should do at the end of the region.
optional end_config = 4
Override the default settings for how the robot should behave at the end. Does not apply for OPTION_CONTINUE.
Used in:
OPTION_UNKNOWN = 0
OPTION_CONTINUE = 1
Continue past the waypoint. If not already stopped at it, do not stop.
OPTION_STOP = 2
Stop at the waypoint.
OPTION_CONTROL = 3
Stop at the waypoint and transfer control to the callback.
Used in:
STATUS_UNKNOWN = 0
UNKNOWN should never be used.
STATUS_OK = 1
The AreaCallback is actively updating. If an execution error does occur, that is reported via the response oneof.
STATUS_INVALID_COMMAND_ID = 2
The request command id does not exist or is no longer executing.
STATUS_EXPIRED_END_TIME = 3
The area callback end time already expired.
message
area_callback.proto:328Used in:
UpdateLocalization.LocalizationChange change = 1
Change the localization within GraphNav.
Used in:
LOCALIZATION_UNKNOWN = 0
When unset, Graph Nav will not change the localization.
LOCALIZATION_AT_END = 1
The robot is now at the end of the region.
message
graph_nav.proto:1156Response to the UploadGraphRequest. After uploading a graph, the user is expected to upload large data at waypoints and edges (called snapshots). The response provides a list of snapshot IDs which are not yet cached on the server. Snapshots with these IDs should be uploaded by the client.
Used as response type in: GraphNavService.UploadGraph, GraphNavService.UploadGraphStreaming
optional header = 1
Common response header.
UploadGraphResponse.Status status = 8
Status for an upload request.
optional lease_use_result = 2
Details about how the lease was used.
repeated string loaded_waypoint_snapshot_ids = 3
The waypoint snapshot ids for which there was cached data.
repeated string unknown_waypoint_snapshot_ids = 4
The waypoint snapshot ids for which there is no cached data.
repeated string loaded_edge_snapshot_ids = 5
The edge snapshot ids for which there was cached data.
repeated string unknown_edge_snapshot_ids = 6
The edge snapshot ids for which there was no cached data.
LicenseInfo.Status license_status = 7
Large graphs can only be uploaded if the license permits them.
optional sensor_status = 9
optional area_callback_error = 10
Errors about Area Callbacks in the map.
optional map_stats = 11
General map statistics.
optional validation_status = 12
If the returned status is STATUS_INVALID_GRAPH, this contains the detailed information about why the graph was invalid. Note that some graph validation errors are warnings and the robot will be able to navigate on the graph even when they are present.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_MAP_TOO_LARGE_LICENSE = 3
Can't upload the graph because it was too large for the license.
STATUS_INVALID_GRAPH = 4
The graph or its anchoring are invalid. See the ValidationStatus for more details.
STATUS_INCOMPATIBLE_SENSORS = 5
The sensor data associated with this graph is incompatible with the current robot. A common example would be trying to upload a map recorded on a robot that had LIDAR to a robot that did not, or vice versa.
STATUS_AREA_CALLBACK_ERROR = 6
There is an error associated with one of the area callbacks in this graph.
message
graph_nav.proto:1196Detailed information about why STATUS_INVALID_GRAPH was returned. This will only contain information if the UploadGraph request could not be validated.
Used in:
repeated string missing_waypoint_ids_in_edges = 1
One or more edges references a waypoint that doesn't exist. There are the waypoint IDs referenced by edges that do not exist. This is an error. Fix the graph and re-upload.
repeated string missing_waypoint_ids_in_anchors = 2
The anchoring uploaded referenced waypoint IDs that do not exist. These are the missing IDs. This is a warning. The anchorings will be ignored.
repeated edge_ids_invalid_transform = 3
One or more edges had an invalid from_tform_to transform. These are the edge IDs uploaded that have an invalid transform. Valid transforms have quaternion rotations that are normalized. This is a warning. Edges with invalid transforms will be fixed on upload.
repeated string waypoint_anchors_invalid_transform = 4
One or more waypoint anchors in the anchoring have an invalid transform. These are the waypoint IDs that have an invalid transform. Valid transforms have quaternion rotations that are normalized. This is a warning. Anchors with invalid transforms will be fixed on upload.
repeated string object_anchors_invalid_transform = 5
One or more of the object anchors in the anchoring have an invalid transform. These are the object IDs that have an invalid transform. Valid transforms have quaternion rotations that are normalized. This is a warning. Anchors with invalid transforms will be fixed on upload.
repeated string duplicate_waypoint_ids = 6
The Graph in the UploadGraph request contained more than one waypoint with the same ID. These are the waypoint IDs which occur in the UploadGraph request more than once. Note that IDs are duplicated in this list the same number of times they are duplicated in the request. This is an error. Fix the graph and re-upload.
repeated string duplicate_waypoint_anchor_ids = 7
The anchoring contains one or more anchor IDs that are duplicated. Note that IDs are duplicated in this list the same number of times they are duplicated in the request. This is a warning. Only the first anchor will be used.
repeated string duplicate_object_anchor_ids = 8
The anchoring contains one or more object anchor IDs that are duplicated. Note that IDs are duplicated in this list the same number of times they are duplicated in the request. This is a warning. Only the first anchor will be used.
repeated duplicate_edge_ids = 9
The Graph in the UploadGraph request contained more than one edge with the equivalent ID. These are the edge IDs which occur in the UploadGraph request more than once. Note that IDs are duplicated in this list the same number of times that they are duplicated in the request. Note that edges are *not* directional, and it is impossible to have both a->b *and* b->a in the same map. This is an error. Fix the graph and re-upload.
repeated string invalid_waypoint_ids_self_edges = 10
Edges are not allowed to have the same "from" and "to" waypoint. These are the waypoint IDs which have self edges in the UploadGraph request. This is an error. Fix the graph and re-upload.
bool has_empty_waypoint_ids = 11
At least one waypoint in the graph has an empty ID. This is an error. Fix the graph and re-upload.
bool has_empty_edge_ids = 12
At least one edge in the graph references a waypoint with an empty ID. This is an error. Fix the graph and re-upload.
bool has_empty_waypoint_anchor_ids = 13
At least one waypoint anchor in the anchoring has an empty ID. This is a warning. Empty anchors will be ignored.
bool has_empty_object_anchor_ids = 14
At least one object anchor in the anchoring has an empty ID. This is a warning. Empty anchors will be ignored.
repeated malformed_staircase_edge_ids = 15
One or more edges had a malformed staircase annotation. This is an error. Remove, rerecord, or fix the annotation.
Used in:
STATUS_UNKNOWN = 0
Unset.
STATUS_OK = 1
Success.
STATUS_INCOMPATIBLE_SENSORS = 2
The data in this waypoint snapshot is not compatible with the current configuration of the robot. Check sensor_status for more details.
Used in:
STATUS_UNKNOWN = 0
STATUS_OK = 1
STATUS_INCOMPATIBLE_SENSORS = 5
STATUS_AREA_CALLBACK_ERROR = 6
message
visual_features.proto:25Represents a visual descriptor of a feature, usually a sparse visual feature.
Used in: ,
oneof visual_descriptor
bytes orb = 1
Oriented Brief (ORB) sparse visual feature.
other = 100
Place to put other descriptors not explicitly captured above.
message
visual_features.proto:55Represents a set of visual features collected at a particular time from a particular camera source. Associates an image geometry + pixel data with visual features extracted there.
Used in:
repeated keypoints = 1
The visual features extracted at the camera image.
optional image_capture_and_source = 2
Contains the actual data in the image capture (may be compressed), and information about the source. Note that the raw data may be omitted if visual features are already extracted.
optional bundle_tform_image = 3
Transformation from a bundle frame to the image. Depending on the context, the bundle frame may be the body, odometry, etc.
message
visual_features.proto:69Represents a bundle of visual KeyFrames taken around the same time. For example, if the robot has many cameras, this represents all of the cameras captured at around the same time/location.
repeated key_frames = 1
A number of key frames, possibly from different sources.
string bundle_frame_name = 2
Reference frame that the keyframes' poses are expressed in.
optional frame_tree_snapshot = 3
Frame tree snapshot mapping common poses at record time (odom, body, etc.) to each other and the bundle frame.
message
visual_features.proto:35Represents a 2d (pixel-based) detection of a feature in an image.
Used in:
optional visual_descriptor = 1
The descriptor of the sparse feature, used to match it to other features.
optional position = 2
Position (pixels) in the image.
float size_pixels = 3
Size of the feature in pixels. If the feature is circular, this is the radius of the circle. If the feature is square, this is the side length of the square.
float orientation = 4
Orientation of the feature in the image plane, radians. Counterclockwise.
optional depth_measurement = 5
The depth (in meters) from the camera if it exists, or empty otherwise.
optional position_covariance = 6
2x2 Covariance matrix of the position measurement's uncertainty.
optional depth_variance = 7
Expected variance of the depth measurement, if it exists.
message
visual_features.proto:123Represents a 3D landmark that has some visual descriptor attached to it.
Used in:
int64 id = 1
Unique ID of the landmark. Ids of landmarks are unique only in a particular instance of a graph nav map. Ids of landmarks may change as maps update.
optional position_with_covariance = 2
The landmark may either be a full 3D landmark (in which case it is a point), or an orientation-only landmark (in which case it is a normalized direction). The frame of the landmark is left ambiguous here; generally the container of the landmark will specify which frame it is in. Note that landmarks may have *both* position and direction. A 3D position with covariance.
optional direction_with_covariance = 3
The vector is to be interpreted as a normalized 3D direction in the landmark frame. This represents the direction "into" the landmark from where it was first observed.
optional visual_descriptor = 4
The canonical descriptor associated with this landmark. If a landmark looks different from different angles, then multiple landmarks are likely to be created for it. This will be set whenever the first observation is made of a landmark to create it.
repeated landmark_observations = 5
Indices of the observations that support this landmark.
message
visual_features.proto:146A group of 3D landmarks. These landmarks may be associated with a single waypoint, or with groups of waypoints.
repeated landmarks = 1
Unorganized 3d landmark cloud.
string landmark_frame = 2
Name of the reference frame that the landmarks are in.
optional frame_tree_snapshot = 3
The frame tree must contain, at minimum, the landmark_frame and some other frame that the waypoint or current robot body knows about (for example, "odom" or "vision").
message
graph_nav.proto:33Used in:
bool verify_refinement_quality = 1
Whether to return a STATUS_VISUAL_ALIGNMENT_FAILED if refine_with_visual_features fails.
message
map.proto:43A base element of the graph nav map. A waypoint consists of a reference frame, a name, a unique ID, annotations, and sensor data.
Used in: , ,
string id = 1
Identifier of the waypoint. Unique across all maps. This identifier does not have to be updated when its fields change.
string snapshot_id = 2
Identifier of this waypoint's Snapshot data.
optional waypoint_tform_ko = 3
Transform from the KO frame (at time of recording) to the waypoint.
optional annotations = 4
Annotations specific to the current waypoint.
message
map.proto:65Annotations understood by BostonDynamics systems.
Used in: ,
string name = 1
Human-friendly name of the waypoint. For example, "Kitchen Fridge"
optional creation_time = 4
The time that the waypoint was created while recording a map.
optional icp_variance = 2
Estimate of the variance of ICP when performed at this waypoint, collected at record time.
optional scan_match_region = 3
Options for how to localize to a waypoint (if at all).
WaypointSource waypoint_source = 5
How this waypoint was made.
optional client_metadata = 6
Information about the state of the client when this waypoint was created.
optional loop_closure_settings = 7
This waypoint may have specific settings to help with loop closure. This Is useful for example when trying to ensure that a loop closure occurs at a particular intersection or near a dock.
optional gps_settings = 8
Optional GPS navigation settings for this waypoint.
repeated regions = 9
Regions may be defined around the waypoint which affect how scan matching or other parameters work.
LostDetectorStrictness lost_detector_strictness = 10
Strictness of the lost detector to use while traversing this waypoint. If unset, the default strictness will be used.
message
map.proto:136Waypoints can optionally define where they are in an Earth-Centered-Earth-Fixed (ECEF) frame, which can aid in localization.
Used in:
AnnotationState state = 1
If the annotation state is set, the GPS settings will be applied. Otherwise, they will be ignored. If ignored, GPS will only be used at this waypoint if data from a GPS exists in the waypoint snapshot, and the robot has a GPS payload installed and running. Set the annotation state to override this behavior.
optional ecef_tform_waypoint = 2
This defines the pose of the waypoint in the Earth-Centered-Earth-Fixed (ECEF) frame.
bool disable_gps_localization = 5
If true, GPS localization will be disabled at this waypoint. If false, the robot will use GPS when available to localize to this waypoint.
message
map.proto:76Used in:
AnnotationState state = 1
Check this before reading other fields.
oneof region
default_region = 2
Oneof field that describes the waypoint's location as a default region (no special features/traits).
empty = 3
Oneof field that describes the waypoint's location as a empty/featureless region.
circle = 4
Oneof field that describes the waypoint's location as a circular region.
message
map.proto:92Indicates the number of meters away we can be from this waypoint we can be before scan matching. - If zero, the default value is used. - If less than zero, no scan matching will be performed at this waypoint. - If greater than zero, scan matching will only be performed if the robot is at most this far away from the waypoint. Distance calculation is done in the 2d plane with respect to the waypoint.
Used in:
double dist_2d = 1
meters.
message
map.proto:81Use the default region to localize in.
Used in:
(message has no fields)
message
map.proto:83Do not localize to this waypoint.
Used in:
(message has no fields)
message
map.proto:115Used in:
bool disable_loop_closure = 1
If true, loop closure will be fully disabled at this waypoint.
bool disable_collision_check = 2
If true, collision checking will be disabled for loop closures from or to this waypoint.
double max_edge_length = 3
If nonzero, edges are allowed to be this long when making loop closures to this waypoint. If zero, global/default settings will be used.
double max_odometry_path_length = 4
If nonzero, loop closures to this waypoint may shortcut this amount of path length. If zero, global/default settings will be used.
Used in:
WAYPOINT_SOURCE_UNKNOWN = 0
WAYPOINT_SOURCE_ROBOT_PATH = 1
Waypoints from the robot's location during recording.
WAYPOINT_SOURCE_USER_REQUEST = 2
Waypoints with user-requested placement.
WAYPOINT_SOURCE_ALTERNATE_ROUTE_FINDING = 3
Waypoints that may help find alternate routes.
message
map_processing.proto:235Waypoints may be anchored to a particular seed frame. The user may request that a waypoint be anchored in a particular place with some Gaussian uncertainty. Note on gravity alignment: optimization is sensitive to bad alignment with respect to gravity. By default, the orientation of the seed frame assumes gravity is pointing in the negative z direction. Take care to ensure that the orientation of the waypoint is correct with respect to gravity. By convention, waypoints' orientation is defined as: Z up, X forward, Y left. So, if the robot is flat on the ground, the waypoint's z axis should align with the seed frame's z axis. z z ^ ^ | | | | | | +------>x | Waypoint Seed
Used in: ,
optional waypoint_anchor = 1
This is to be interpreted as the mean of a Gaussian distribution, representing the pose of the waypoint in the seed frame.
optional seed_tform_waypoint_uncertainty = 2
This is the uncertainty of the anchor's pose in the seed frame. If left empty, a reasonable default uncertainty will be generated.
optional seed_tform_waypoint_constraint = 3
Normally, the optimizer will move the anchorings of waypoints based on context, to minimize the overall cost of the optimization problem. By providing a constraint on pose, the user can ensure that the anchors stay within a certain region in the seed frame. Leaving this empty will allow the optimizer to move the anchoring from the hint as far as it likes.
message
map.proto:184Relevant data collected at the waypoint. May be used for localization or automatically generating annotations, for example. Should be indexed by a waypoint's "snapshot_id" field.
Used in:
string id = 1
Identifier of this snapshot. Snapshots are immutable -- if any of the other fields change, this ID must also change.
repeated images = 2
Any images captured at the waypoint.
optional point_cloud = 3
Aggregated point cloud data.
repeated objects = 4
Perception objects seen at snapshot time.
optional robot_state = 5
Full robot state during snapshot.
repeated robot_local_grids = 6
Robot grid data.
bool is_point_cloud_processed = 8
If true, the point cloud of this snapshot has been processed.
string version_id = 9
If this snapshot is a modified version of the raw snapshot with the given ID (for example, it has been processed), a new unique ID will we assigned to this field. If the field is empty, this is the raw version of the snapshot.
bool has_remote_point_cloud_sensor = 10
If true, the point cloud contains data from a remote point cloud service, such as LIDAR.
optional body_tform_remote_point_cloud_sensor = 11
Transform from the robot body to the remote point cloud sensor's reference frame.
repeated payloads = 12
Defines the payloads attached to the robot at this waypoint.
optional robot_id = 14
Identifiers (software, nickname, etc.) of the robot that created this waypoint.
optional recording_started_on = 15
Information about when the recording session started in robot time basis. This will be filled out by the recording service when StartRecording is called.
message
map_processing.proto:266World objects (such as fiducials) may be anchored to a particular seed frame. The user may request that an object be anchored in a particular place with some Gaussian uncertainty. Note on gravity alignment: optimization is sensitive to bad alignment with respect to gravity. By default, the orientation of the seed frame assumes gravity is pointing in the negative z direction. Take care to ensure that the orientation of the world object is correct with respect to gravity. By convention, fiducials' orientation is defined as: Z out of the page, X up and Y left (when looking at the fiducial). So, if a fiducial is mounted perfectly flat against a wall, its orientation w.r.t the seed frame would have the top of the fiducial facing positive Z. +-----------+ z | ^x | ^ | | | | | | | | | <----+ | | | y | Seed | | +-----------+ Fiducial (on wall)
Used in: ,
optional object_anchor = 1
This is to be interpreted as the mean of a Gaussian distribution, representing the pose of the object in the seed frame.
optional seed_tform_object_uncertainty = 2
This is the uncertainty of the anchor's pose in the seed frame. If left empty, a reasonable default uncertainty will be generated.
optional seed_tform_object_constraint = 3
Normally, the optimizer will move the anchorings of object based on context, to minimize the overall cost of the optimization problem. By providing a constraint on pose, the user can ensure that the anchors stay within a certain region in the seed frame. Leaving this empty will allow the optimizer to move the anchoring from the hint as far as it likes.