raisim::RaisimServer

final class · #include <raisim/RaisimServer.hpp>

Streams a raisim::World (plus server-side visual-only objects and charts) over TCP to a visualizer such as the rayrai TCP viewer, and accepts interaction / sim-control requests (pause, step, force, pose) from it.

Typical use: construct with a World, call launchServer() (spawns one network thread), advance the simulation with integrateWorldThreadSafe(), and call killServer() before the server is destroyed. Only one client is served at a time.

Threading: the network thread reads the world and every visual container while holding the World mutex. Any other thread that mutates the world or adds/removes visuals while the server is running must hold lockVisualizationServerMutex() (integrateWorldThreadSafe() does this).

Security: there is no authentication. By default the server binds to 127.0.0.1 only; see setBindLoopbackOnly().

Public types

ClientMessageType

enum ClientMessageType : int

Internal: message type sent by the client at the start of each request frame (wire format).

Enumerator	Value
REQUEST_UPDATE	0
REQUEST_SENSOR_UPDATE

ServerMessageType

enum ServerMessageType : int

Internal: server message type (wire format).

Enumerator	Value
UPDATE_ALL	0
No_MESSAGE

ServerRequestType

enum class ServerRequestType : int

One-shot requests the server sends to the viewer in the next frame. They are queued by startRecordingVideo(), stopRecordingVideo(), focusOn(), setCameraPositionAndLookAt() and requestSaveScreenshot(). (Wire format.)

Enumerator	Value
NO_REQUEST	0
START_RECORD_VIDEO	1
STOP_RECORD_VIDEO	2
FOCUS_ON_SPECIFIC_OBJECT	3
SET_CAMERA_TO	4
GET_SCREEN_SHOT	5
SET_SCREEN_SIZE	6

ClientRequestType

enum class ClientRequestType : int

Internal: requests a client can send to the server (wire format). The CR_SPAWN_*, CR_ATTACH_WIRE, CR_DRAG_OBJECT, CR_REMOVE_OBJECT and CR_SAVE_THE_WORLD requests are interactive editing commands; CR_PAUSE (100) to CR_SET_GC (106) are sim-control requests, accepted only when PROTOCOL_FEATURE_SIM_CONTROL was negotiated; CR_SCENE_MANIFEST (200) and CR_SCENE_FILE_CHUNK (201) need PROTOCOL_FEATURE_SCENE_FILES. Their payloads are listed next to each value in the source.

Enumerator	Value
CR_SPAWN_BOX	0
CR_SPAWN_SPHERE
CR_SPAWN_CYLINDER
CR_SPAWN_CAPSULE
CR_SPAWN_HEIGHT_MAP
CR_SPAWN_MESH
CR_SPAWN_PLANE
CR_SPAWN_AS
CR_ATTACH_WIRE
CR_DRAG_OBJECT
CR_REMOVE_OBJECT
CR_SAVE_THE_WORLD
CR_PAUSE	100
CR_RESUME	101
CR_STEP_N	102
CR_APPLY_FORCE	103
CR_APPLY_TORQUE	104
CR_SET_POSE	105
CR_SET_GC	106
CR_SCENE_MANIFEST	200
CR_SCENE_FILE_CHUNK	201

Status

enum Status : int

Server state, sent in every frame header. STATUS_RENDERING streams the world; STATUS_HIBERNATING keeps the connection but sends no world update (see hibernate()); STATUS_TERMINATING tells the client to disconnect.

Enumerator	Value
STATUS_RENDERING	0
STATUS_HIBERNATING	1
STATUS_TERMINATING	2

Masking

enum Masking : int

Internal: visual category tag sent with each streamed object (wire format).

Enumerator	Value
AS_VISUAL_OBJ	0
AS_COL_OBJ	1
SB_OBJ	2
VIS_OBJ	3
CONSTRAINTS	4
CONTACT_FORCE	5
CONTACT_POINT	6
EXT_FORCE	7
EXT_TORQUE	8

Constructors & destructor

RaisimServer

explicit RaisimServer(World *world)

Create a server for a world. Does not open a socket; call launchServer() to start serving. Allocates the send and receive buffers (32 MiB each).

Parameters

Parameter	Description
world (in)	the world to visualize. Not owned; it must outlive the server.

~RaisimServer

~RaisimServer() = default

Public member functions

setBindLoopbackOnly

void setBindLoopbackOnly(bool loopbackOnly)

If true (default), the server only listens on 127.0.0.1. Set to false to listen on all interfaces (INADDR_ANY). This also changes discovery beacons from loopback to LAN broadcast. The bind address is the only access control the server provides — if you open it to the network, any reachable client can drive the sim. The bind address takes effect at the next setupSocket()/launchServer() call.

Parameters

Parameter	Description
loopbackOnly (in)	true to bind to 127.0.0.1 only, false to bind to all interfaces.

setSceneFileSharing

void setSceneFileSharing(bool enabled)

Share the files of a world built from a .rscene file with viewers (on by default). A viewer that does not find the scene file and its assets locally (at the server's paths, in its resource directories or its download cache) asks its user, then downloads them and draws the scene as rayrai does locally. Only the files the scene uses are served: see raisim::rscene::referencedFiles(). Files edited while the server runs are hashed again for the next client. Share only trusted scenes: explicit absolute paths and parent references can expose files outside the scene directory, and extensions do not validate image contents.

Parameters

Parameter	Description
enabled (in)	false to report the scene's files as unavailable

getPort

int getPort() const

The TCP port the server is actually listening on. If the requested port was already in use, setupSocket() walks forward to the next free port — call this after launchServer() to discover which port clients should connect to.

Returns the bound port (8080 before any socket has been set up).

pauseSimulation

void pauseSimulation()

Pause the simulation. integrateWorldThreadSafe() will skip world_->integrate() while paused, unless a step has been queued (see stepSimulation()). Client pose-sets (CR_SET_POSE / CR_SET_GC) are still applied each tick; client forces are queued but only applied to bodies on ticks that actually step. A viewer with sim control can also pause the server (CR_PAUSE). Thread-safe to call from any thread.

resumeSimulation

void resumeSimulation()

Resume a paused simulation (see pauseSimulation()). Thread-safe.

isSimulationPaused

bool isSimulationPaused() const

Returns true if the simulation is paused, by pauseSimulation() or by the viewer. Thread-safe.

stepSimulation

void stepSimulation(int n=1)

Queue single-step integrations to run while paused. Each paused integrateWorldThreadSafe() call consumes one. Has no effect on an unpaused simulation other than leaving the steps queued for a later pause. Thread-safe.

Parameters

Parameter	Description
n (in)	number of steps to queue; values <= 0 are ignored.

setupSocket

void setupSocket(int port=8080)

Create, bind and listen on the server socket so that acceptConnection() can accept clients. If the port is in use, the next ports are tried (up to 64 in total); getPort() reports the port actually bound. Binds to 127.0.0.1 unless setBindLoopbackOnly(false) was called. launchServer() calls this for you. On Linux/macOS a failure is fatal; on Windows it is printed and the function returns without a listening socket.

Parameters

Parameter	Description
port (in)	the first port number to try

acceptConnection

void acceptConnection(int microseconds)

Wait for and accept a client connection. Only one client can be connected at a time. On success the visual tags of all objects are reset so the new client receives the full scene, which locks the World mutex. The server thread started by launchServer() calls this.

Parameters

Parameter	Description
microseconds (in)	the number of microseconds to wait for a connection from a client

closeConnection

void closeConnection() const

Close the listening server socket (not the client socket). For new connections, the port has to be set up again with setupSocket(). On Windows this also calls WSACleanup().

launchServer

void launchServer(int port=8080)

Bind the socket (see setupSocket()) and start the server thread, which accepts one client at a time and streams the world to it. Returns immediately after binding, so getPort() is valid afterwards. While running, the server emits UDP discovery beacons on port 59312 so rayrai_tcp_viewer can list compatible endpoints. Call killServer() before the server is destroyed; destroying it with the thread still running terminates the program (std::thread semantics).

Parameters

Parameter	Description
port (in)	the first port number to try

integrateWorldThreadSafe

void integrateWorldThreadSafe()

Integrate the world while holding the World mutex, so the server thread never reads the world mid-step (otherwise, there can be a segfault). Honors pauseSimulation() / stepSimulation(): while paused the world is not advanced unless a single-step has been queued. Pose-sets pushed by clients are applied every call; the interaction wire force and client forces/torques are applied only when the world is actually stepped.

template <typename BeforeStep>
void integrateWorldThreadSafe(BeforeStep &&beforeStep)

Like integrateWorldThreadSafe() but invokes the supplied callable under the world mutex after interaction/sim-control requests are applied and before world_->integrate() runs. The callable is invoked on every call, including while paused (when no step follows). Use this when you need to spawn / move / modify world objects each tick — it keeps your mutation safely interleaved with the network thread while still honoring viewer pause/step/force/pose commands. An exception from the callable or the step propagates with the world mutex released.

Template parameters

Parameter	Description
BeforeStep	callable with signature void()

Parameters

Parameter	Description
beforeStep (in)	callback invoked inside the locked region

applyInteractionForce

void applyInteractionForce()

Apply the interaction-wire force (a spring set by the user dragging an object in the visualizer) as a constraint force on the attached body. This is automatically called in raisim::RaisimServer::integrateWorldThreadSafe on steps that advance the world. Caller must hold the World mutex.

hibernate

void hibernate()

Hibernate the server. The client stays connected, but frames carry only the server state and no world update, and the server thread sleeps 100 ms between frames. Undo with wakeup(). Locks the World mutex.

wakeup

void wakeup()

Wake the server from hibernation and resume streaming. Locks the World mutex.

killServer

void killServer()

Stop the server thread, disconnect the client and close the listening socket. Blocks until the thread has exited. Precondition: launchServer() was called and killServer() has not been called since; otherwise std::thread::join throws.

lockVisualizationServerMutex

void lockVisualizationServerMutex()

Lock the World mutex so that the server thread cannot read from the world or the visual containers. Hold it while modifying the world or adding/removing visuals from a thread other than the one calling integrateWorldThreadSafe(). Equivalent to World::lockMutex(); not recursive, so do not call integrateWorldThreadSafe() while holding it.

unlockVisualizationServerMutex

void unlockVisualizationServerMutex()

Unlock the World mutex locked by lockVisualizationServerMutex(). Briefly sleeps if the server thread is waiting for the lock, so it gets a chance to acquire it.

isTerminateRequested

bool isTerminateRequested()

Returns true while killServer() is shutting the server thread down

addVisualArticulatedSystem

ArticulatedSystemVisual *addVisualArticulatedSystem(
    const std::string &name,
    const std::string &urdfFile,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=0)

Parameters

Parameter	Description
name (in)	the name of the visual articulated system object
urdfFile (in)	the path to the urdf file
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns the articulated system visual. Owned by the server; valid until removeVisualArticulatedSystem(). Add an articulated system without physics. Fatal if the name is already used. A color with alpha 0 (the default) keeps the colors defined in the model. If the server is running, hold lockVisualizationServerMutex() while calling this.

removeVisualArticulatedSystem

void removeVisualArticulatedSystem(ArticulatedSystemVisual *as)

Remove and delete a visual articulated system. The pointer is invalid afterwards. If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
as (in)	ArticulatedSystemVisual to be removed (as returned by addVisualArticulatedSystem())

addInstancedVisuals

InstancedVisuals *addInstancedVisuals(
    const std::string &name,
    Shape::Type type,
    const Vec<3> &size,
    const Vec<4> &color1,
    const Vec<4> &color2)

Parameters

Parameter	Description
name (in)	the name of the instanced visual
type (in)	shape type for each instance
size (in)	base size for each instance
color1 (in)	first color used for interpolation
color2 (in)	second color used for interpolation

Returns the instanced visuals. Owned by the server and never removed. Add a set of visual-only instances that share one shape. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualSphere

Visuals *addVisualSphere(
    const std::string &name,
    double radius,
    double colorR=1,
    double colorG=1,
    double colorB=1,
    double colorA=1,
    const std::string &material="",
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual object
radius (in)	radius of the sphere
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)
material (in)	ignored (not stored or transmitted)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the sphere visual. Owned by the server; valid until removeVisualObject(). Add a sphere without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualBox

Visuals *addVisualBox(
    const std::string &name,
    double xLength,
    double yLength,
    double zLength,
    double colorR=1,
    double colorG=1,
    double colorB=1,
    double colorA=1,
    const std::string &material="",
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual object
xLength (in)	length of the box
yLength (in)	width of the box
zLength (in)	height of the box
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)
material (in)	ignored (not stored or transmitted)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the box visual. Owned by the server; valid until removeVisualObject(). Add a box without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualCylinder

Visuals *addVisualCylinder(
    const std::string &name,
    double radius,
    double length,
    double colorR=1,
    double colorG=1,
    double colorB=1,
    double colorA=1,
    const std::string &material="",
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual object
radius (in)	radius of the cylinder
length (in)	length of the cylinder
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)
material (in)	ignored (not stored or transmitted)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the cylinder visual. Owned by the server; valid until removeVisualObject(). Add a cylinder without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualCapsule

Visuals *addVisualCapsule(
    const std::string &name,
    double radius,
    double length,
    double colorR=1,
    double colorG=1,
    double colorB=1,
    double colorA=1,
    const std::string &material="",
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual object
radius (in)	radius of the capsule
length (in)	length of the capsule
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)
material (in)	ignored (not stored or transmitted)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the capsule visual. Owned by the server; valid until removeVisualObject(). Add a capsule without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualMesh

Visuals *addVisualMesh(
    const std::string &name,
    const std::string &file,
    const Vec<3> &scale={1, 1, 1},
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1,
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual mesh object
file (in)	file name of the mesh
scale (in)	scale of the mesh
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1). Ignore color when negative
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the mesh visual (a VisualMesh). Owned by the server; valid until removeVisualObject(). Add a mesh from a file without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

VisualMesh *addVisualMesh(
    const std::string &name,
    const std::vector<float> &vertexArray,
    const std::vector<uint8_t> &colorArray,
    const std::vector<int32_t> &indexArray,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=1,
    bool glow=false,
    bool shadow=false)

Add a mesh from raw vertex/color/index arrays without physics. Fatal if the name is already used or the array sizes are invalid. Update the geometry later with VisualMesh::updateMesh(). If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
name (in)	the name of the visual mesh object
vertexArray (in)	array of vertices (x, y, z per vertex). Size must be a multiple of 3
colorArray (in)	array of per-vertex colors in RGB (0-255). Must have the same size as vertexArray
indexArray (in)	array of triangle indices. Size must be a multiple of 3
colorR (in)	red color value (if colorArray is empty)
colorG (in)	green color value (if colorArray is empty)
colorB (in)	blue color value (if colorArray is empty)
colorA (in)	alpha color value (if colorArray is empty)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the mesh visual. Owned by the server; valid until removeVisualObject().

addVisualArrow

Visuals *addVisualArrow(
    const std::string &name,
    double radius,
    double height,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1,
    bool glow=false,
    bool shadow=false)

Parameters

Parameter	Description
name (in)	the name of the visual mesh object
radius (in)	radius of the arrow
height (in)	height of the arrow
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)
glow (in)	to glow or not (not supported)
shadow (in)	to cast shadow or not (not supported)

Returns the arrow visual. Owned by the server; valid until removeVisualObject(). Add an arrow without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addVisualHeightMap

HeightMapVisual *addVisualHeightMap(
    const std::string &name,
    const std::string &fileName,
    double centerX,
    double centerY,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1)

Parameters

Parameter	Description
name (in)	the name of the visual heightmap object
fileName (in)	the raisim text file which will be used to create the height map
centerX (in)	x coordinate of the center of the height map
centerY (in)	y coordinate of the center of the height map
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns pointer to the created visual height map. Owned by the server; valid until removeVisualHeightMap(). The RGBA arguments are stored in HeightMapVisual::color, which the server currently does not transmit; color the terrain via HeightMapVisual::setColor(const std::vector<raisim::ColorRGB>&) or the HeightMap appearance instead. If the server is running, hold lockVisualizationServerMutex() while calling this.

HeightMapVisual *addVisualHeightMap(
    const std::string &name,
    const std::string &pngFileName,
    double centerX,
    double centerY,
    double xScale,
    double yScale,
    double heightScale,
    double heightOffset,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1)

Parameters

Parameter	Description
name (in)	the name of the visual heightmap object
pngFileName (in)	the png file which will be used to create the height map
centerX (in)	x coordinate of the center of the height map
centerY (in)	y coordinate of the center of the height map
xScale (in)	x scale of the height map
yScale (in)	y scale of the height map
heightScale (in)	a png file (if 8-bit) has pixel values from 0 to 255. This parameter scales the pixel values to the actual height
heightOffset (in)	height of the 0-value pixel
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns pointer to the created visual height map. Owned by the server; valid until removeVisualHeightMap(). The RGBA arguments are stored in HeightMapVisual::color, which the server currently does not transmit; color the terrain via HeightMapVisual::setColor(const std::vector<raisim::ColorRGB>&) or the HeightMap appearance instead. If the server is running, hold lockVisualizationServerMutex() while calling this.

HeightMapVisual *addVisualHeightMap(
    const std::string &name,
    double centerX,
    double centerY,
    TerrainProperties &terrainProperties,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1)

Parameters

Parameter	Description
name (in)	the name of the visual heightmap object
centerX (in)	x coordinate of the center of the height map
centerY (in)	y coordinate of the center of the height map
terrainProperties (in)	perlin noise parameters which will be used to create the height map
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns pointer to the created visual height map. Owned by the server; valid until removeVisualHeightMap(). The RGBA arguments are stored in HeightMapVisual::color, which the server currently does not transmit; color the terrain via HeightMapVisual::setColor(const std::vector<raisim::ColorRGB>&) or the HeightMap appearance instead. If the server is running, hold lockVisualizationServerMutex() while calling this.

HeightMapVisual *addVisualHeightMap(
    const std::string &name,
    size_t xSamples,
    size_t ysamples,
    double xSize,
    double ySize,
    double centerX,
    double centerY,
    const std::vector<double> &height,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1)

Parameters

Parameter	Description
name (in)	the name of the visual heightmap object
xSamples (in)	how many points along x axis
ysamples (in)	how many points along y axis
xSize (in)	x width of the height map
ySize (in)	y length of the height map
centerX (in)	x coordinate of the center of the height map
centerY (in)	y coordinate of the center of the height map
height (in)	a vector of doubles representing heights. the size should be xSample X ySamples
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns pointer to the created visual height map. Owned by the server; valid until removeVisualHeightMap(). The RGBA arguments are stored in HeightMapVisual::color, which the server currently does not transmit; color the terrain via HeightMapVisual::setColor(const std::vector<raisim::ColorRGB>&) or the HeightMap appearance instead. If the server is running, hold lockVisualizationServerMutex() while calling this.

HeightMapVisual *addVisualHeightMap(
    const std::string &name,
    const HeightMap *hm,
    double colorR=0,
    double colorG=0,
    double colorB=0,
    double colorA=-1)

Parameters

Parameter	Description
name (in)	the name of the visual heightmap object
hm (in)	Another height map whose samples, size and center are copied. Fatal if null
colorR (in)	the red value of the color (max=1)
colorG (in)	the green value of the color (max=1)
colorB (in)	the blue value of the color (max=1)
colorA (in)	the alpha value of the color (max=1)

Returns pointer to the created visual height map. Owned by the server; valid until removeVisualHeightMap(). The RGBA arguments are stored in HeightMapVisual::color, which the server currently does not transmit; color the terrain via HeightMapVisual::setColor(const std::vector<raisim::ColorRGB>&) or the HeightMap appearance instead. If the server is running, hold lockVisualizationServerMutex() while calling this.

removeVisualHeightMap

void removeVisualHeightMap(HeightMapVisual *hm)

Remove and delete a visual height map. The pointer is invalid afterwards. If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
hm (in)	HeightMapVisual to be removed (as returned by addVisualHeightMap())

addVisualPolyLine

PolyLine *addVisualPolyLine(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the polyline

Returns the polyline. Owned by the server; valid until removeVisualPolyLine(). Add a polyline without physics. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

addPointCloud

PointCloud *addPointCloud(const std::string name)

Add a point cloud. Fatal if the name is already used. If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
name (in)	the name of the point cloud

Returns the point cloud. Owned by the server; valid until removePointCloud().

removePointCloud

void removePointCloud(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the point cloud to be removed Remove and delete an existing point cloud. Fatal if it does not exist. If the server is running, hold lockVisualizationServerMutex() while calling this.

getVisualPolyLine

PolyLine *getVisualPolyLine(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the polyline

Returns the polyline (owned by the server). Fatal if it does not exist.

getVisualArticulatedSystem

ArticulatedSystemVisual *getVisualArticulatedSystem(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the visual articulated system

Returns the visual articulated system (owned by the server). Fatal if it does not exist.

getVisualHeightMap

HeightMapVisual *getVisualHeightMap(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the visual height map

Returns the visual height map (owned by the server). Fatal if it does not exist.

removeVisualPolyLine

void removeVisualPolyLine(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the polyline to be removed Remove and delete an existing polyline. Fatal if it does not exist. If the server is running, hold lockVisualizationServerMutex() while calling this.

getVisualObject

Visuals *getVisualObject(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the visual object to be retrieved

Returns the visual object (owned by the server). Fatal if it does not exist. Only finds objects created by addVisualSphere/Box/Cylinder/Capsule/Mesh/Arrow.

removeVisualObject

void removeVisualObject(const std::string &name)

Parameters

Parameter	Description
name (in)	the name of the visual object to be removed Remove and delete a visual object created by addVisualSphere/Box/Cylinder/Capsule/Mesh/Arrow. Fatal if it does not exist. If the server is running, hold lockVisualizationServerMutex() while calling this.

startRecordingVideo

void startRecordingVideo(const std::string &videoName)

Parameters

Parameter

Description

videoName (in)

name of the video file to be saved. The videoName must be a valid file name (e.g., no spaces, ending in .mp4) Ask the connected visualizer to start recording a video. The request is queued and sent with the next frame; the visualizer chooses the output directory. The rayrai TCP viewer uses the file stem/extension, and writes a PNG sequence if no video encoder (ffmpeg) is available. Locks the World mutex.

stopRecordingVideo

void stopRecordingVideo()

Ask the visualizer to stop recording (queued for the next frame). Locks the World mutex.

setCameraPositionAndLookAt

void setCameraPositionAndLookAt(
    const Eigen::Vector3d &pos,
    const Eigen::Vector3d &lookAt)

Parameters

Parameter	Description
pos (in)	the position of the camera in world coordinates
lookAt (in)	the world-frame point the camera looks at (not a direction) Ask the visualizer to move its camera (queued for the next frame). Locks the World mutex.

focusOn

void focusOn(raisim::Object *obj)

Parameters

Parameter	Description
obj (in)	the object to look at. Fatal if null; ignored if it is not in the world. Ask the visualizer to focus its camera on the object (queued for the next frame). Locks the World mutex.

isConnected

bool isConnected() const

Returns true if a client is currently connected

waitForMessageFromClient

bool waitForMessageFromClient(int seconds)

Internal: wait until the connected client socket is readable.

Parameters

Parameter	Description
seconds (in)	the number of seconds to wait for the client (on Windows the timeout is fixed at about 20 s and this value is only used in the warning message)

Returns true if data from the client is available or its connection ended, so that processRequests() serves it or returns false (also at once when no client is connected, as after a processRequests() that failed: acceptConnection() then takes the next one), false on timeout or error

waitForMessageToClient

bool waitForMessageToClient(int seconds)

Internal: wait until the connected client socket is writable. Used by the server thread before sending.

Parameters

Parameter	Description
seconds (in)	the number of seconds to wait (on Windows the timeout is fixed at about 20 s and this value is only used in the warning message)

Returns true if the socket is writable, false on timeout or error

needsSensorUpdate

bool needsSensorUpdate()

Check whether a manual RGB/depth camera of a world robot or of a visual articulated system is due for an update from the visualizer. Locks each camera, and each visual articulated system.

Returns true when at least one supported camera needs an update

processRequests

bool processRequests()

Synchronous update method, called repeatedly by the server thread. Receive a request from the client, process it and return the requested data to the client. Locks the World mutex while applying requests and serializing the world. Malformed or oversized frames and exceptions from request handling are caught and reported as failure. The method return false if 1) the client failed to respond 2) the client protocol version is different 3) the client refused to receive the data 4) the client did not send the sensor data in time 5) no client is connected On false the connection is closed (and a drag in progress ended): a caller that serves the client itself accepts the next one with acceptConnection().

Returns if succeeded or not.

waitForNewClients

bool waitForNewClients(int microseconds)

Wait until a client is waiting to be accepted on the listening socket.

Parameters

Parameter	Description
microseconds (in)	how long to wait for a new client (negative waits indefinitely on Linux/macOS)

Returns if a new client was found or not

requestSaveScreenshot

void requestSaveScreenshot()

Ask the visualizer to save a screenshot (queued for the next frame; the directory is chosen by the visualizer). Locks the World mutex.

addTimeSeriesGraph

TimeSeriesGraph *addTimeSeriesGraph(
    std::string title,
    std::vector<std::string> names,
    std::string xAxis,
    std::string yAxis)

Only works with RaisimUnreal. Please read the "atlas" example to see how it works. Fatal if a chart with the same title exists. If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
title (in)	title of the chart, also its unique key
names (in)	name of the data curves to be plotted
xAxis (in)	title of the x-axis
yAxis (in)	title of the y-axis

Returns pointer to the created Time Series Graph. Owned by the server and never removed.

addBarChart

BarChart *addBarChart(std::string title, std::vector<std::string> names)

Only works with RaisimUnreal. Please read the "atlas" example to see how it works. Fatal if a chart with the same title exists. If the server is running, hold lockVisualizationServerMutex() while calling this.

Parameters

Parameter	Description
title (in)	title of the chart, also its unique key
names (in)	name of the data histogram to be plotted

Returns pointer to the created Bar Chart. Owned by the server and never removed.

Public attributes

SEND_BUFFER_SIZE

static constexpr int SEND_BUFFER_SIZE

Capacity in bytes (32 MiB) of one outgoing frame. A frame that would exceed it is rejected and the current client is disconnected.

MAXIMUM_PACKET_SIZE

static constexpr int MAXIMUM_PACKET_SIZE

Internal: size in bytes of a scratch buffer. Not a limit on frame size.

RECEIVE_BUFFER_SIZE

static constexpr int RECEIVE_BUFFER_SIZE

Capacity in bytes (32 MiB) of one incoming client frame. Larger frames are dropped and the client is disconnected.

PROTOCOL_FEATURE_EXPLICIT_HEADER

static constexpr uint64_t PROTOCOL_FEATURE_EXPLICIT_HEADER

Internal protocol feature bit, negotiated with the client (wire format).

PROTOCOL_FEATURE_DEFORMABLE_DELTA

static constexpr uint64_t PROTOCOL_FEATURE_DEFORMABLE_DELTA

Internal protocol feature bit, negotiated with the client (wire format).

PROTOCOL_FEATURE_SIM_CONTROL

static constexpr uint64_t PROTOCOL_FEATURE_SIM_CONTROL

Protocol feature bit for sim control. When negotiated, the client may send CR_PAUSE / CR_RESUME / CR_STEP_N / CR_APPLY_FORCE / CR_APPLY_TORQUE / CR_SET_POSE / CR_SET_GC. No auth — if the server is reachable, the client can drive it. Bind to loopback (the default) to keep an open server local; opt in to INADDR_ANY only when you trust the network.

PROTOCOL_FEATURE_CONTACT_OBJECT_TAGS

static constexpr uint64_t PROTOCOL_FEATURE_CONTACT_OBJECT_TAGS

Protocol feature bit for contact object tags. Adds the two participating visual tags after each contact position/force pair. This lets object-specific viewers distinguish selected-object contacts from the scene-wide contact visualization stream.

PROTOCOL_FEATURE_ACTUATOR_STATE

static constexpr uint64_t PROTOCOL_FEATURE_ACTUATOR_STATE

Protocol feature bit for actuator state. Appends the actuators of a selected articulated system after its COM block: motor parameters (for the motor operating region), the motor state of the last step, and the velocity and actuator torque of each driven joint.

PROTOCOL_FEATURE_SCENE_FILES

static constexpr uint64_t PROTOCOL_FEATURE_SCENE_FILES

Protocol feature bit for scene files. Adds a scene-file block after the server requests of every response and accepts CR_SCENE_MANIFEST / CR_SCENE_FILE_CHUNK, so a viewer can download the files of a world built from a .rscene file (format in raisim/server/SceneFileProtocol.hpp).

PROTOCOL_FEATURE_BODY_FRAME_OFFSETS

static constexpr uint64_t PROTOCOL_FEATURE_BODY_FRAME_OFFSETS

Adds each articulated/compound visual's body-relative position and wxyz rotation after its mask/body index, only in its initialization record.

PROTOCOL_SUPPORTED_FEATURES

static constexpr uint64_t PROTOCOL_SUPPORTED_FEATURES

All feature bits this server accepts. A client requesting any other bit is disconnected.