Common

Common macros are the basic functionality xacro macros for Configuring and creating scenes. This macros create the most common XML blocks such as oceanState, simParams, vehicles, sensors, objects, ... . This macros should be used as a starting point to create your own libraries to be used in scenes. If you want to know how parameters work visit the XML description in the corresponding block. This are the macros currently available at common.xacro. Most macros are preceded by an underscore _ as xacro does not allow to create a macro with the same name as any defined XML tag.

How to

Here we have a really brief tutorial on how to use macros in UWSim, but we recommend visiting ros website to learn more about xacro. Every macro can be called using its name and parameters, for instance _color macro can be called using:

<xacro:_color r="1" g="0" b="0" />

This line will automatically be expanded to:

 <color>
   <r>1</r>
   <g>0</g>
   <b>0</b>
 </color>

Some macros take special parameters preceded by "**", such as **trajectory. This means the parameter is an XML block and must be set inside the macro tag. as the following example shows.

 <xacro:_macroWithXMLArgument >
   <insertXMLBlock>
     <a>1</a>
     <b>1</b>
   </insertXMLBlock>
 </xacro:_macroWithXMLArgument >

In this example a and b tag will be taken as arguments for the first, and unique in this example, starred parameter of the macro.

Basic macros

This macros create XML blocks that are repeated in different places such as position, orientation or color.

• pi: Defines the Pi value. Actually this is a property, not a macro, and can be called just using {pi} to use Pi value in any parameter.
• _color: Creates color XML block. It takes 3 parameters (r,g,b).
• _offsetp: Creates a position offset XML block. Requires x,y,z parameters.
• _offsetr: Creates a rotation offset XML block. Requires x,y,z parameters.
• _offset: Use position and rotation offset to create both kinds of offset. Requires position and rotation offset parameters: x,y,z,rx,ry,rz.
• _position: Builds a position XML block. It takes 3 parameters (x,y,z).
• _orientation: Expands an orientation XML block using r,p,y parameters.
• _scale: Creates a scale XML block. x,y,z required.

Ocean state macros

This macros create oceanState blocks, as ocean state usually does not require too much changes, there are only two available macros.

• _oceanState: It allows to configure every parameter in ocean state XML block. Requires the whole set of parameters: windx, windy, windSpeed, depth, reflectionDamping, waveScale, isNotChoppy, choppyFactor, crestFoamHeight, oeanSurfaceHeight, fogDensity, fogr, fogg, fogb, r, g, b, attenuationr, attenuationg, attenuationb.
• default_oceanState: Creates the default oceanState, the same as cirs.xml scene, with common values.

Simulation parameters macros

The following macros create XML blocks contained in simParams XML block.

• _showTrajectory: This macro creates a showTrajectory tag for one object. If you need more than one, you will need to use it more than one time. Required parameters are target, r, g, b, lineStyle and timeWindow.
• simple_showTrajectory: Simplified version of showTrajectory. It only requires target and r,g,b.
• full_simParams: This macro allows to configure every parameter available at simulation parameters block. To know: disableShaders, resw, resh, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz, enablePhysics, gravityx, gravityy, gravityz, physicsFrequency, physicsSubSteps, physicsSolver, **trajectory, lightRate.
• defaultFull_simParams: Uses the preceding macro to setup the most common parameters but let the user add trajectories. Default parameters are setting the positive z to be down (seafloor) and physics disabled. It requires a **trajectory parameter.
• simple_simParams: Simplified version of the full simulation parameters. This macro requires only the most commonly used parameters: disableShaders, resw, resh, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz, enablePhysics, **trajectory.
• defaultSimple_simParams: Uses the preceding macro to create an XML block with the default parameters. World's positive z axis pointing to the seafloor and disabled physics. It requires a **trajectory parameter.
• defaultSimpleNoTrajectory_simParams: Same macros as the preceding but does not require any parameter.

For instance we can use the following macros to create the simulation parameters of cirs scene using:

<xacro:simple_simParams disableShaders="0" resw="800" resh="600" offsetpx="0" offsetpy="0" offsetpz="0" offsetrx="${pi}" offsetry="0" offsetrz="${-pi/2}" enablePhysics="1" >
 <trajectory>
   <showTrajectory>
     <target>girona500</target>
   </showTrajectory>
 </trajectory>
</xacro:simple_simParams>

Furthermore, we can get rid of the showTrajectory block and use the macro for it:

<xacro:simple_simParams disableShaders="0" resw="800" resh="600" offsetpx="0" offsetpy="0" offsetpz="0" offsetrx="${pi}" offsetry="0" offsetrz="${-pi/2}" enablePhysics="1" >
 <trajectory>
   <xacro: simple_showTrajectory target="girona500" r="1.0" g="0" b="0" />
 </trajectory>
</xacro:simple_simParams>

camera macros

We have created a few macros to configure the camera of the main window in UWSim.

• _camera: This macro permits to configure every parameter available in the XML block. It requires freeMotion, objectToTrack, fov, aspectRatio, near, far, positionx, positiony, positionz, lookAtx, lookAty, lookAtz.
• default_camera: Configures a simple free motion camera without requiring any parameters.
• track_camera: Configures a camera that tracks an object in the scene looking at its centre. Requires a few parameters: objectToTrack, x, y, z.
• freemotion_camera: Creates a free motion camera in the desired position (x,y,z).

vehicle macros

This section will cover the macros available for vehicle XML block.

• _vehicle: Macro for creating a generic vehicle. It takes the following parameters: name, file, **joints, x, y, z, roll, pitch, yaw, scalex, scaley, scalez, **sensors.
• simple_vehicle: Simplifies the preceding macro with the most commonly used parameters, to know: name, file, x, y, z, roll, pitch, yaw, **sensors.
• raw_vehicle: Creates a raw vehicle with no sensors, using name, file, x, y, z, roll, pitch and yaw parameters.

The previous macros allows us to add vehicles, but we missed the most important part of them, sensors. Sensors have their own macros that can be included inside the **sensors parameter of _vehicle. Although it is possible to create the sensors calling sensors macro inside each vehicle, we recommend creating your own device library with macros for sensors. If you do so it is easier to create different vehicle configurations. The following macros are available for sensors:

• _virtualCamera: Creates a simulated virtualCamera. The following parameters are required to configure it: name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw, baseline, frameId, fovy, showpath, grayscale, std.
• _virtualCameraParams: If you prefer to configure a camera using its intrinsic parameters you can use this macro. It requires to configure name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw, baseline, frameId, showpath, grayscale, std, fx, fy, x0, y0, f, n, k.
• simple_Vcam: Simplified version of virtual camera with only the main attributes as parameters. To know: name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw.
• simple_VcamParams: Simplified version of virtual camera configured using intrinsic parameters. Requires this attributes: name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw, fx, fy, x0, y0, f, n, k.

• _structuredLightProjector: This macro creates an structuredLightProjector using: name, relativeTo, fov, image_name, laser, x, y, z, roll, pitch, yaw.

• _rangeSensor: Creates a rangeSensor device using: name, relativeTo, range, x, y, z, roll, pitch, yaw.

• _objectPicker: Creates a objectPicker device using: name, relativeTo, range, x, y, z, roll, pitch, yaw.

• _imu: Creates a imu device using: name, relativeTo, x, y, z, roll, pitch, yaw, std.

• _pressureSensor: Creates a pressureSensor device using: name, relativeTo, x, y, z, roll, pitch, yaw, std.

• _gpsSensor: Creates a gpsSensor device using: name, relativeTo, x, y, z, roll, pitch, yaw.

• _dvlSensor: Creates a dvlSensor device using: name, relativeTo, x, y, z, roll, pitch, yaw.

• _virtualRangeImage: Creates a virtualRangeImage device using: name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw, frameId, fovy.
• _virtualRangeImageParams: If you prefer to configure a range image device using intrinsic parameters of the camera, it can be done using this macro. The required parameters are: name, relativeTo, resw, resh, x, y, z, roll, pitch, yaw, frameId, fx, fy, x0, y0, f, n, k.

• _multibeamSensor: Creates a multibeamSensor device using: name, relativeTo, visible, x, y, z, roll, pitch, yaw, initAngle, finalAngle, angleIncr, range.

• _ForceSensor: Creates a ForceSensor device using: name, target, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz.

• _DredgeTool: Creates a DredgeTool device using: name, target, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz.

Object macros

In this section we will sum up the available macros for object XML tag. Once again, we highly recommend using this macros to create you own object macro library with most common objects used in your scenes, so you can just add them setting its pose as it is done in the object library example.

• _object: This generic macro requires every parameter available for objects. Which are: name, file, x, y, z, roll, pitch, yaw, scalex, scaley, scalez, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz, mass, inertiax, inertiay, inertiaz, collisionShapeType, collisionShape, linearDamping, angularDamping, isKinematic, minLinearLimitx, minLinearLimity, minLinearLimitz, maxLinearLimitx, maxLinearLimity, maxLinearLimitz, minAngularLimitx, minAngularLimity, minAngularLimitz, maxAngularLimitx, maxAngularLimity, maxAngularLimitz.
• _kinObject: Simplifies the previous macro for kinematic objects, will not react to forces but they will generate them in other objects. A typical example of this kind of object is the terrain or a big rock. This are the required parameters: name, file, x, y, z, roll, pitch, yaw, scalex, scaley, scalez, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz, collisionShapeType.
• _dynObject: Simplifies the generic object macro for dynamic objects. These objects will be controlled by the physics engine, such as the blackbox. This kind of objects require the following parameters name, file, x, y, z, roll, pitch, yaw, scalex, scaley, scalez, offsetpx, offsetpy, offsetpz, offsetrx, offsetry, offsetrz, mass, collisionShapeType.
• simple_object: Simplified version of the generic object macro, that allows to add kinematic or dynamic objects, setting mass to 0. The required parameters are: name, file, x, y, z, roll, pitch, yaw, scalex, scaley, scalez, mass, collisionShapeType.

ROS interface macros

We also created basic macros for each rosInterfaces XML block. As this blocks are quite simple we will just list them with the parameters.

• _ROSOdomToPAT: topic, vehicle.
• _PATToROSOdom: topic, vehicle.
• _PATToROSOdomRate: topic, vehicle, rate.
• _WorldToROSTF: topic, vehicle.
• _WorldToROSTFRate: topic, vehicle, rate.
• _ArmToROSJointState: topic, vehicle.
• _ArmToROSJointStateRate: topic, vehicle, rate.
• _ROSJointStateToArm: topic, vehicle.
• _VirtualCameraToROSImage: cameraName, imageTopic, infoTopic.
• _VirtualCameraToROSImageRate: cameraName, imageTopic, infoTopic, rate, depth.
• _ROSImageToHUD: width, height, posx, posy, scale, blackWhite, imageTopic, infoTopic.
• _ROSImageToHUDShort: width, height, imageTopic, infoTopic.
• _ROSTwistToPAT: topic, vehicle.
• _RangeSensorToROSRange: topic, vehicle.
• _RangeSensorToROSRangeRate: topic, vehicle, rate.
• _ROSPoseToPAT: topic, vehicle, rate.
• _ImuToROSImu: name, topic.
• _ImuToROSImuRate: name, topic, rate.
• _PressureSensorToROS: name, topic.
• _PressureSensorToROSRate: name, topic, rate.
• _GPSSensorToROS: name, topic.
• _GPSSensorToROSRate: name, topic, rate.
• _DVLSensorToROS: name, topic.
• _DVLSensorToROSRate: name, topic, rate.
• _RangeImageSensorToROSImage: cameraName, imageTopic, infoTopic.
• _RangeImageSensorToROSImageRate: cameraName, imageTopic, infoTopic, rate, depth.
• _multibeamSensorToLaserScan: name, topic.
• _multibeamSensorToLaserScanRate: name, topic, rate.
• _contactSensorToROS: name, topic.
• _contactSensorToROSRate: name, topic, rate.
• _ForceSensorROS: name, topic.
• _ForceSensorROSRate: name, topic, rate.
• _ROSPointCloudLoader: topic.