V-Ray mesh format description (.vrmesh)

General

File structure

Header

Voxel table

Voxel data

Channels

Vertex channels

Face channels

Face info channel

Maya info channel

Examples

General

The .vrmesh format can be used to store geometry information in a ready to render format by V-Ray. The secions below describe the format of .vrmesh files. The V-Ray SDK also includes a library for reading and writing of .vrmesh files. The ply2vrmesh tool can be used to convert a number of other geometry file formats (.obj, .geo, .ply, .bin) to .vrmesh files.

 

The geometry information in a .vrmesh file is organized into voxels. Each voxel is a mesh in its own right and can be loaded and rendered independently of other voxels. The ply2vrmesh tool and the .vrmesh exporters for the various modeling applications (3ds Max, Maya, Softimage etc) split heavy meshes into voxels of a few thousand faces, which can be loaded on demand as rendering progresses.

 

Below are some images of how the geometry in a single .vrmesh file is split into voxels. To show the voxels, the geometry in each of them is rendered with a different color.

 

A single .vrmesh with several objects. Each original object its stored in its own voxel. A single .vrmesh file with one large object (28,055,742 triangles). The initial mesh (from the Stanford scanning repository) is split into chunks of roughly 10,000 triangles each. The conversion from the original .ply file to .vrmesh file is done with the ply2vrmesh tool. Another .vrmesh file from the Stanford repository (about 1 million triangles).

 

File structure

The .vrmesh file consists of one or several frames (used for animation). Each frame contains one or more voxels, which contain the geometry information for that frame. Each voxel consists of one or more channels that represent the actual data (vertices, faces etc). In addition, the file contains a table to speed up the look-up of particular frames and voxels.

 

For additional information see the file mesh_file.h in the V-Ray SDK.

Header

The header is located at the start of a .vrmesh file.

 

Field name Field size Description
vray ID 7 bytes Contains the NUL-terminated ASCII string 'vrmesh' used to recognize the files.
file version 4 bytes One 32-bit unsigned integer with the file version (currently 0x1000)
look-up table offset 8 bytes One 64-bit unsigned integer with the position in the file (in bytes, since the start of the file) of the look-up table

 

Voxel table

The voxel table is typically written at the end of the file and contains information about the voxels for each frame of the animation. The table ends either at the end of the file, or with a frame that has zero voxels.

 

Field name Field size Description
numVoxels for frame 0 4 bytes One 32-bit unsigned integer with the number of voxels for this frame; if 0, this is the end of the look-up table. Different frames may have different number of voxels.
voxel 0 offset 8 bytes One 64-bit unsigned integer with the position in the file (in bytes, since the start of the file) of the data for this voxel
voxel 0 bounding box 24 bytes Six single-precision floating-point numbers that define the bounding box for this voxel, in object space for the proxy
voxel 0 flags 4 bytes One 32-bit unsigned integer with additional information for this voxel:
MVF_GEOMETRY_VOXEL (1) - the voxel contains actual geometry for rendering;
MVF_PREVIEW_VOXEL (2) - the voxel contains preview geometry for display in viewports, and/or other general information. There is typically only one preview voxel for each frame.
voxel 1 offset    
.....    
voxel (numVoxels-1) flags    
numVoxels for frame 1    
....    

 

Voxel data

The format of the data for each voxel is as follows:

 

Field name Field size Description
numChannels 4 bytes One 32-bit unsigned integer with the number of channels for this voxel
channel 0 element size 4 bytes One 32-bit integer with the size (in bytes) for the elements in this channel
channel 0 number of elements 4 bytes One 32-bit integer with the number of elements in this channel
channel 0 ID 2 bytes One 16-bit integer with the ID for the channel. See the Channels section for a list of the pre-defined channel IDs.
channel 0 dependency channel ID 2 bytes One 16-bit integer with the ID of the dependency channel ID for this channel. Vertex channels typically depend on a topology channel (e.g. vertices depend on faces, normals depend on normal faces etc). However different vertex channels often depend on the same topology channel. In this case, we can save disk (and memory) space by storing only one copy of the topology channel.
channel 0 flags 4 bytes One 32-bit integer with flags for this channel. These can include:
MF_VERT_CHANNEL (1)- a vertex channel;
MF_TOPO_CHANNEL (2) - a topology channel;
MF_INFO_CHANNEL (4) - a channel with other information;
MF_FACE_CHANNEL (8) - a channel with additional per-face information (like face IDs, edge visibility etc)
MF_COMPRESSED (16) - the channel data is compressed with zlib
MF_MAYA_INFO_CHANNEL (32) - only meaningful for preview voxels; contains information about the faceIDs, UV sets and color sets of the mesh
MF_POINTCLOUD_CHANNEL (64) - channel with point-cloud data
MF_POINTCLOUD_INFO_CHANNEL (128) - additional point-cloud information
channel 1 element size    
....    
channel 0 data varying If the MF_COMPRESSED flag is not specified for the voxel, then this field contains (element size x number of elements) bytes with the uncompressed channel data. If the MF_COMPRESSED flag is specified, then the first 4 bytes form a 32-bit integer with the length of the compressed data stream, followed by the compressed data. This can be passed directly to the zlib uncompress() function to return (element size x number of elements) bytes with the actual channel data.
....    
channel (numChannels-1) data    
channel 0 checksum 4 bytes One 32-bit unsigned integer with check sum for this channel, computed by adding together the element size, number of elements, channel ID, dependency channel ID, flags, and the uncompressed data:

 

uint32 MeshChannel::computeCheckSum(void) {
uint32 checkSum=0;
checkSum+=elementSize;
checkSum+=numElements;
checkSum+=channelID;
checkSum+=depChannelID;
checkSum+=flags; int nbytes=numElements*elementSize;
int nints=nbytes/4;
uint32 *iptr=(uint32*) data;
for (int i=0; i<nints; i++) checkSum+=iptr[i]; uint8 *bptr=(uint8*) data;
for (int i=nints*4; i<nbytes; i++) checkSum+=bptr[i];
return checkSum;
}
...    
channel (numChannels-1) checksum    

 

Channels

Channels can contain arbitrary data, but channels with some pre-defined IDs have special meanings:

 

Channel ID name ID number Element size Description
VERT_GEOM_CHANNEL 0 12 bytes Each element represents one vertex of the mesh with the three single-precision floating-point components in xyz order. Normally depends on the FACE_TOPO_CHANNEL.
FACE_TOPO_CHANNEL 1 12 bytes Each element represents the indices of the three vertices (as 32-bit integers) for a mesh triangle in the VERT_GEOM_CHANNEL.
VOXEL_INFO_CHANNEL 3 20 bytes Contains a voxel color (12 bytes, single-precision floating-point rgb), smoothed flag (4 bytes), flip normals flag (4 bytes). This channel typically has only one element.
VERT_NORMAL_CHANNEL 4 12 bytes Each element represents a vertex normal. Normally depends on the VERT_NORMAL_TOPO_CHANNEL or FACE_TOPO_CHANNEL channels.
VERT_NORMAL_TOPO_CHANNEL 5 12 bytes Each element represents the vertex normal indices for a mesh triangle in the VERT_NORMAL_CHANNEL. This channel must have the same number of elements as the FACE_TOPO_CHANNEL channel.
FACE_INFO_CHANNEL 6 12 bytes For each triangle face, this channel contains smoothing group flags (4 bytes), edge visibility flags (4 bytes), face material ID (4 bytes). This channel, if present, must have the same number of elements as the FACE_TOPO_CHANNEL channel.
VERT_VELOCITY_CHANNEL 7 12 bytes Vertex velocity for one frame. This channel, if present, must have the same number of elements as the VERT_GEOM_CHANNEL channel.
MAYA_INFO_CHANNEL 8 varying This channel typically has only one element of varying length and is only attached to preview voxels. It contains information about the number of face material IDs, UV and color set names etc. If this channel is missing from the preview voxel, the display of the respective proxy objects inside Maya might be significantly slower.
VERT_TEX_CHANNEL0 1000 12 bytes Each element represents UVW coordinages for the 0-th mapping channel with three single-precision floating-point numbers. Typically depends on the VERT_TEX_TOPO_CHANNEL0 channel.
VERT_TEX_CHANNEL1 1001 12 bytes The UVW coordinates for the 1-st mapping channel
....      
VERT_TEX_CHANNEL99 1099 12 bytes The UVW coordinates for the 99-th mapping channel
VERT_TEX_TOPO_CHANNEL0 2000 12 bytes Each element represents the UVW indices of the three vertices (as 32-bit integers) for a mesh triangle for UVW channel 0. This channel, if present, must have the same number of elements as the FACE_TOPO_CHANNEL channel.
VERT_TEX_TOPO_CHANNEL1 2001 12 bytes The UVW faces for the 1-st mapping channel.
....      
VERT_TEX_TOPO_CHANNEL99 2099 12 bytes The UVW faces for the 99-th mapping channel.
POINTCLOUD_INFO_CHANNEL 10   A channel with point cloud information.
POINTCLOUD_GEOM_CHANNEL 100   A channel with point cloud data.

 

Vertex channels

Vertex channels contain information about triangle vertex positions, normals, UVW coordinates and vertex velocity. Each element is composed of three single-precision floating-point numbers for the xyz or uvw coordinates respectively.

Face channels

Face (or topology) channels contain topology information for the geometric, normals, or uvw triangles of a voxel mesh. Each element is composed of three 32-bit integers which describe the indices of the three vertices in the respective vertex channel.

Face info channel

This channel contains additional information for each face. The most important part of this channel is the face material ID, which can be used to guide the shading of the mesh. For each face, this channel stores three 32-bit integers with the smoothing group bits (this is only used when rendering in 3ds Max), edge visibility flags (bits 0, 1, and 2 for each edge respectively), and the face material ID.

Maya info channel

This channel is usually present in .vrmesh files exported from Maya and contains information about color and UV sets, as well as a list of the possible face material IDs. This channel is normally only included as part of the preview voxel for a given frame. If this channel is missing from the preview voxel, the display of the respective proxy objects inside Maya might be significantly slower. This is because the .vrmesh loader in V-Ray for Maya needs to determine the number of distinct material IDs and the available UV/Color sets so that it can create the appropriate preview geometry and allow proper shader connections. If the Maya info channel is missing, the .vrmesh loader will be forced to read through the entire geometry to find out this information.

 

The format of the data in this channel (after decompression, if MF_COMRESSED is specified) is as follows:

 

Field name Field size Description
number of uv sets 4 bytes One 32-bit unsigned integer with the number of UV sets (UVW channels) in the mesh for this frame.
UV set 0 name length 4 bytes One 32-but unsigned integer with the length (in bytes) of the UV set name.
UV set 0 name varying The name of the 0-th UV set (the 0-th UVW channel)
UV set 1 name length    
UV set 1 name    
.....    
UV set (number of uv sets-1) name    
number of color sets 4 bytes The number of color sets in the mesh
color set 0 name length 4 bytes The length (in bytes) of the name for the 0-th color set
color set 0 name varying The name of the color set
....    
color set (number of color sets-1) name    
number of additional info blocks 4 bytes Number of additional blocks; usually this is 1 - for an additional block with shader sets (based on face material IDs for the mesh)
number of shader sets 4 bytes Number of shading sets
shader set 0 name length 4 bytes The length (in bytes) for the 0-th shader set (for faces with material ID 0)
shader set 0 name varying The name of the 0-th shader set
....    
shader set (number of shader sets-1) name    

 

Examples

Below is a list of several .vrmesh files that can be used to study the format.

 

Preview File Description
cube.vrmesh A single cube exported from Maya.
objects.vrmesh Several different objects exported in one .vrmesh file from 3ds Max.
armadillo.vrmesh The armadillo model from the Standford scanning repository converted with ply2vrmesh.
cylinder_bend.vrmesh A 20-frame animation of a bending cylinder exported from 3ds Max.