How to display custom 3D models in the 3D Viewer
Supported object types
The 3D viewer currently only supports four files formats to define custom objects:
- BSSCFG file format (see displaying a variable number of objects section)
- JPEG or PNG file formats (used for flat texured walls)
- Wavefront OBJ file format (used for complex polygonal models)
- XYZRGB file format (used to represent point clouds)
XYZRGB file format
This is a simple ASCII file format used to represent point clouds. Each line represents a single point. Each line contains six values separated by whitespaces. The first three values indicate the X, Y and Z coordinates of the point in the scene. They are considered as floating point value. The last three values represent the color of the point . They are considered as integer values between 0 and 255.
Displaying a single object
The easiest way to do this is to create an object which uses the File object type. This kind of object supports image files, OBJ files and XYZRGB files.
Displaying a variable number of objects
Several object types in the 3D viewers let you display a variable number of object instances (PointCloud, Lines, Triangles, Quads, etc...). Most of them provide the 3D model geometry on an input of the 3D viewer. Here we want the 3D viewer to use custom models so the only data we want on the input are an object type identifier that we can use to map the object to a 3D model and a 3D transformation to be able to move the object in the scene. To do this, we need to use the RealObjects type.
Starting with the 3D viewer v1.20, creating a RealObjects object let you specify a configuration file. This is where the BSSCFG file format is used. It is a configuration file which lets you associate 3D models (defined with other files) with identifiers.
BSSCFG file format
The BSSCFG file format is a relatively simple ASCII file format. You can find an example in the samples provided with rtmaps_ibeo.pck in RTMaps 4.2.3 (packages/rtmaps_ibeo\samples/3d_models/ibeo_real_objects.bsscfg).
Each line contains an identifier, a 3D model and optionally a 3D transformation. It looks like this:
identifier 1<TAB>3D model 1[<TAB>3D transformation]<LF>
identifier 2<TAB>3D model 2[<TAB>3D transformation]<LF>
identifier 3<TAB>3D model 3[<TAB>3D transformation]<LF>
<TAB> must be replaced with one or more tabulations. <LF> must be replace with an end of line (either \r\n or\n).
It can be either a keyword, an integer values which can be stored in a 32bit integer or a string enclosed in double quotes. The only keyword currently recognized is Default. It lets you specify the 3D model used when no other identifier is valid. Integer identifiers are used for Custom RealObject. The identifier is matched against the userKind field. String identifiers are used to override the model drawn for Vehicles, Signs and Trees. Here is a list of the recognized identifiers:
- "Sign/SpeedLimit" (default for speed limit signs when limit value is not found)
- "Sign/SpeedLimit/[limit value]"
- "Sign/EndOfSpeedLimit" (default for end of speed limit signs when limit value is not found)
- "Sign/EndOfSpeedLimit/[limit value]"
- "Sign/TextOnly" (default for text signs when the text is not recognized)
- "Sign/TextOnly/[text field of the structure]"
It can be a keyword or a path (enclosed in double quotes) to an obj file describing the 3D model. When it is a keyword, it can be either Cube, Pyramid or Sphere and must be followed by 3 floating point values separated by tabulations which indicate the shape color. When it is a path, it must be either relative to the configuration file location or absolute.
This part is optionnal. It is used to normalize the model origin and orientation. Please not that if you want to change the orientation of the object you must also specify the model origin. The origin is decribed by three floating point values (X, Y and Z coordinates) expressed in the 3D model coordinate system. They are separated with tabulations. The orientation is also described with three coefficients. This time they represent euler angles expressed in degrees.