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). |
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.
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 |
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 | ||
| .... |
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;} |
| ... | ||
| channel (numChannels-1) checksum |
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 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 (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.
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.
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 |
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. |