raisim::Sensor

abstract class · #include <raisim/sensors/Sensors.hpp>

Derived by: raisim::DepthCamera, raisim::InertialMeasurementUnit, raisim::RGBCamera, raisim::SegmentationCamera, raisim::SpinningLidar, raisim::WrenchSensor

Base class of all sensors attached to an ArticulatedSystem frame (RGBCamera, DepthCamera, SegmentationCamera, InertialMeasurementUnit, SpinningLidar, ForceSensor, TactileSensor).

Sensors are owned by a SensorSet, which belongs to a body of an ArticulatedSystem. Every sensor is attached to a fixed frame of that system (see getFrameId()); its world pose is read from that frame. When the measurement source is MeasurementSource::RAISIM, the owning ArticulatedSystem refreshes the measurement during World::integrate() on a fixed grid of physics time: one sample per 1/getUpdateRate() seconds of simulated steps, taken at the first step that reaches each deadline. Deadlines a step skips over are dropped without shifting the grid, so up to one sample per step the long-run rate equals the update rate even when the period is not a multiple of the time step. The grid counts steps, not world time: World::setWorldTime() between steps does not move it, except that a step ending before the last counted one (the world time set back by more than a step) starts a new grid with a sample at once. The grid also starts again when the update rate changes. IMUs expose the acquisition time even when delivery is delayed. With MeasurementSource::MANUAL, user code (or a renderer) writes the measurement buffers.

Public types

Type

enum class Type : int

Concrete sensor type. Each subclass also provides a static getType() returning its value.

Enumerator	Value	Description
UNKNOWN	0	Not a known sensor type.
RGB		RGBCamera.
DEPTH		DepthCamera.
IMU		InertialMeasurementUnit.
SPINNING_LIDAR		SpinningLidar.
FORCE		Joint force/torque load cell.
TACTILE		Surface contact-force grid.
SEGMENTATION		SegmentationCamera.

MeasurementSource

enum class MeasurementSource : int

Who writes the sensor's measurement buffers.

Enumerator	Value	Description
RAISIM	0	RaiSim updates the measurement from the physics world.
MANUAL		User code or an in-process renderer writes the measurement buffer.

Constructors & destructor

Sensor

Sensor(
    std::string name,
    std::string fullName,
    Type type,
    class ArticulatedSystem *as,
    const Vec<3> &pos,
    const Mat<3, 3> &rot,
    MeasurementSource source)

Parameters

Parameter	Description
name (in)	Sensor name (unique within its SensorSet).
fullName (in)	Name including the sensor-set prefix.
type (in)	Concrete sensor type.
as (in)	Owning articulated system (may be null until attached).
pos (in)	Sensor position relative to the body (link) it is defined on.
rot (in)	Sensor orientation relative to the body (link) it is defined on.
source (in)	Initial measurement source.

~Sensor

virtual ~Sensor() = default

Public member functions

getPosition

const Vec<3> &getPosition()

The pose is refreshed by updatePose() (which the user may call) and by every RaiSim-sourced measurement update. It is not refreshed automatically for MANUAL sensors.

Returns The position of the sensor frame in the world frame

getOrientation

const Mat<3, 3> &getOrientation()

The pose is refreshed by updatePose() (which the user may call) and by every RaiSim-sourced measurement update. It is not refreshed automatically for MANUAL sensors.

Returns The orientation of the sensor frame in the world frame (sensor-to-world rotation)

getFramePosition

const Vec<3> &getFramePosition()

Returns The position of the frame w.r.t. the nearest moving parent. It is used to compute the frame position in the world frame

getFrameOrientation

const Mat<3, 3> &getFrameOrientation()

Returns The orientation of the frame w.r.t. the nearest moving parent. It is used to compute the frame position in the world frame

getPosInSensorFrame

const Vec<3> &getPosInSensorFrame()

Returns The position given at construction, relative to the body (link) the sensor was defined on (i.e., its parent joint frame). Unlike getFramePosition(), it is not re-expressed when fixed bodies are merged into their moving parent.

getOriInSensorFrame

const Mat<3, 3> &getOriInSensorFrame()

Returns The orientation given at construction, relative to the body (link) the sensor was defined on (i.e., its parent joint frame). See getPosInSensorFrame().

getName

const std::string &getName() const

Returns The name of the sensor, as given in the robot/sensor description file

getFullName

const std::string &getFullName() const

Returns The full name of the sensor, including the sensor set's name (e.g. "link_name:sensor_name" for sensors defined in URDF)

getSensorSetModel

const std::string &getSensorSetModel()

Returns The sensor model identifier from the sensor set.

getSerialNumber

const std::string &getSerialNumber()

Returns The serial number of the sensor (copied from the SensorSet when the sensor is added)

setSerialNumber

void setSerialNumber(const std::string &serialNumber)

Set the serial number of the sensor.

Parameters

Parameter	Description
serialNumber (in)	Serial number string.

getType

Type getType()

Returns The type of the sensor

getUpdateRate

double getUpdateRate() const

Returns The update frequency in Hz

getUpdateTimeStamp

double getUpdateTimeStamp() const

This method returns a negative value if the sensor has never been updated

Returns The world time (s) when the last sensor measurement was recorded

isUpdateDue

bool isUpdateDue(double worldTime) const

Whether a manual update is due on the grid anchored at its first measurement. Late updates retain the grid's phase and skip missed deadlines. Polling does not consume a deadline; setUpdateTimeStamp() acknowledges it. A backward timestamp or a rate/source change starts a new grid. The server counts simulated physics time for rendered cameras.

Parameters

Parameter	Description
worldTime (in)	the world time (s)

Returns true if the sensor should be updated at worldTime

setUpdateRate

void setUpdateRate(double rate)

change the update rate of the sensor. Fatal error if the rate is not finite and positive.

Parameters

Parameter	Description
rate (in)	the update rate in Hz

setUpdateTimeStamp

void setUpdateTimeStamp(double time)

Set the acquisition timestamp and acknowledge a manual measurement without shifting its nominal sample grid. RaiSim-sourced updates keep their own grid of physics steps.

Parameters

Parameter	Description
time (in)	the time stamp in seconds (world time)

serializeProp

virtual server::BoundedWriter serializeProp(server::BoundedWriter data) const = 0

Used by the server. Do not use it if you don't know what it does. It serializes the sensor properties

Parameters

Parameter	Description
data (in)	where the property is written; throws server::SerializationError if it does not fit

Returns where the next data should be written

serializeMeasurements

virtual server::BoundedWriter serializeMeasurements(server::BoundedWriter data) const

Used by the server. Do not use it if you don't know what it does. It serializes sensor measurements.

Parameters

Parameter	Description
data (in)	where the measurements are written; throws server::SerializationError if they do not fit

Returns where the next data should be written

updatePose

void updatePose()

update the world pose of the sensor (getPosition(), getOrientation()) from its attachment frame in the articulated system. Fatal error if the sensor is not attached to a valid frame.

getMeasurementSource

MeasurementSource getMeasurementSource()

Returns The measurement source.

setMeasurementSource

void setMeasurementSource(MeasurementSource source)

change the measurement source

Parameters

Parameter	Description
source (in)	The measurement source.

getFrameId

size_t getFrameId() const

Get the id of the frame on which the sensor is attached

Returns frame id (index into ArticulatedSystem::getFrames()); size_t(-1) if not attached yet

getArticulatedSystem

class ArticulatedSystem *getArticulatedSystem() const

Returns The articulated system the sensor is attached to, or nullptr for a detached sensor.

setAttachmentFrame

void setAttachmentFrame(
    const Vec<3> &pos,
    const Mat<3, 3> &rot,
    size_t frameId)

Attach this sensor to an existing articulated-system frame. This is primarily useful for editor or procedural scene builders that create sensors after an articulated system has already been instantiated. The supplied pose must match the registered frame. Register a separate frame for a custom offset instead of modifying a frame shared with other sensors.

Parameters

Parameter	Description
pos (in)	Registered frame position relative to its parent body.
rot (in)	Registered frame orientation relative to its parent body.
frameId (in)	Index of the frame in ArticulatedSystem::getFrames().

lockMutex

void lockMutex()

locks the sensor mutex. This can be used if you use raisim in a multi-threaded environment.

lock

void lock()

Same as lockMutex(); makes Sensor usable with std::lock_guard / std::unique_lock.

try_lock

bool try_lock()

Try to lock the sensor mutex without blocking.

Returns true if the lock was acquired.

unlockMutex

void unlockMutex()

unlock the sensor mutex. This can be used if you use raisim in a multi-threaded environment.

unlock

void unlock()

Same as unlockMutex(); for std::lock_guard / std::unique_lock compatibility.