Docs / Get started

Quick start

Encode a VDB, check what you got, and go back to plain OpenVDB. Start with one volume and the Studio CLI. Houdini users can follow the node workflow.

1Install your build

Use the package and installation instructions supplied with your pilot. Keep the executable and its runtime libraries together, then add the folder containing vqfield to your PATH. Check that it starts:

vqfield --help

Need a build? Start a pilot. Approved testers can use the private downloads portal. Houdini packages must match your exact Houdini build; see current support.

2Encode a volume

Use your own scalar VDB and choose one rate-control mode. This example sets quality directly:

vqfield encode input.vdb --output output.vqfield --quality 50

3Look inside without decoding

vqfield inspect output.vqfield

Lists the frame count, start frame, grid names and file size. Add --json for machine-readable metadata.

4Go back to OpenVDB

vqfield decode output.vqfield --output reconstructed.vdb

5Encode a sequence

vqfield encode-sequence "sim.%04d.vdb" --range 1001:1100 --output sim.vqfield --quality 50 --gop 8
vqfield decode-sequence sim.vqfield --range 0:99 --output "reconstructed.%04d.vdb"

Encode uses your source frame numbers. Decode uses zero-based positions inside the file: 0:99 selects all 100 frames here, writing reconstructed.1001.vdb through reconstructed.1100.vdb. Keep the integer placeholder in the output pattern so each frame has its own file.

Blocks, GOPs and read paths

A block covers 8 × 8 × 8 voxels. A sampler reconstructs the blocks its requests touch and retains them in a cache. Interpolation can touch more than one block. A GOP is a group of sequence frames; seeking reconstructs the needed block history within that group.

Use sampling when your renderer or tool can ask for values in place. Use full decode when a tool needs a standard OpenVDB grid. The read-path illustration shows both ideas.

Docs / Houdini

A cache in your node graph

Use VQField File Cache for explicit export and playback, or decode to standard Houdini VDB primitives when the next node needs them.

1. Install the matching package. Follow its INSTALL.txt, disable older VQField packages, and restart Houdini. The current Windows beta builds are listed on Status.
2. Connect your VDB fields. Add VQField File Cache after your VDB source. It supports Float and Vec3S fields; it does not cache arbitrary Houdini geometry or all attributes.
3. Choose one output file. Set a .vqfield path, frame range, quality and GOP size. The whole sequence lives in this file: do not put $F or $T in its path.
4. Press Save to Disk. Ordinary cooks and playback do not export. The foreground save uses Houdini’s progress window; Escape requests cancellation.
5. Enable Load from Disk. Read the completed cache. Use VQField Decoder when you need standard VDB primitives and selected grids.

Rendering with Karma CPU

In Solaris, use VQField Compressed Volume to reference the compressed file and render with Karma CPU. The native volume runtime samples the compressed field. Keep that runtime installed wherever the scene renders.

Karma XPU is not supported by the current beta. Check representative frames, shading and memory use in your own scene; an implemented read path does not establish a universal rendering speed or memory ratio.

Background and farm setup

Save to Disk in Background runs one local TOP work item using an immutable scene copy and the same Houdini build. It needs a suitable Houdini license. The work item log reports worker startup and license errors.

Distributed farms are not qualified by this beta. Include your scheduler, operating system, Houdini build and shared-storage setup in the pilot request. Interrupted export resume and partial-file playback are not supported.

Docs / Studio CLI

The command line

The Studio CLI handles conversion, file metadata and evaluation reports. These examples use the current command names and flags.

Sequence commands

encode-sequence accepts a printf-style input pattern, an inclusive source --range start:end, rate control and --gop. decode-sequence accepts a zero-based file-local range and writes one VDB per frame. The CLI processes the grids discovered in the first source frame.

A basic .vqfield.json manifest is written alongside sequence encodes unless --no-manifest is set. Keep your original encode command and source inventory: the sidecar is not a complete record of encode settings or resumable state.

Inspect, benchmark and report

vqfield inspect output.vqfield --json
vqfield benchmark output.vqfield --json
vqfield report output.vqfield input.vdb --output report.html --json --preset production

The report command above writes HTML and a sibling JSON file. Report presets are preview, production and archive; they select error thresholds, not encoder settings.

Docs / SDK

Read a value through the C ABI

The SDK exposes readers and CPU samplers without OpenVDB types at the C boundary. This example selects a scalar grid named density and samples one index-space position.

#include <vqfield/vqfield_api.h>

VqfStatus sample_density(const char *path,
                        float x, float y, float z,
                        float *value) {
    if (!value) return VQF_ERROR_INVALID_ARG;

    VqfReader *reader = NULL;
    VqfSampler *sampler = NULL;
    VqfStatus status = vqfield_open_vqvdb(path, &reader);
    if (status != VQF_OK) return status;

    VqfSamplerDesc desc = {0};
    desc.struct_size = sizeof(desc);
    desc.grid = vqfield_reader_find_grid(reader, "density");
    desc.frame = 0;  /* file-local frame */
    desc.cache_bytes = 8u * 1024u * 1024u;

    if (desc.grid < 0) {
        vqfield_reader_close(reader);
        return VQF_ERROR_INVALID_ARG;
    }

    status = vqfield_sampler_create(reader, &desc, &sampler);
    if (status == VQF_OK) {
        status = vqfield_sample_components(
            sampler, x, y, z, VQF_SAMPLE_NEAREST, value, 1);
    }

    vqfield_sampler_destroy(sampler);
    vqfield_reader_close(reader);
    return status;
}

This is a lifecycle example. For repeated queries, open the file and create the sampler once, reuse them, and destroy the sampler before closing its reader. Handle every returned VqfStatus; a zero-valued sample alone cannot identify a failure.

Ownership, caches and errors

• Set struct_size on descriptors that declare it. Keep SDK headers and the runtime library from the same release.
• A sampler borrows its reader. Keep the file immutable and the reader alive until every borrowing sampler is destroyed.
• Each sampler belongs to one thread. Use separate samplers for concurrent callers.
• cache_bytes budgets decoded blocks; it is not a cap on all process memory. File metadata and working storage are separate.
• vqfield_sampler_set_frame selects a zero-based file-local frame. vqfield_sample_batch serves batches up to the sampler’s advertised batch capacity.
• VQF_SAMPLE_NEAREST and VQF_SAMPLE_TRILINEAR use index-space positions. Convert world-space coordinates before querying.
• Check status directly for prepared sampling calls. They do not update vqfield_last_error().

Linking and full-grid workflows

The standalone SDK package exposes the CMake target VQField::sdk through find_package(VQFieldSDK CONFIG REQUIRED). It does not require Houdini or OpenVDB.

For full-grid reconstruction, use the Studio CLI, the public C++ codec interfaces or the OpenVDB adapter. The current opaque full-grid C result does not provide a complete public access and release interface. Describe your integration in a pilot request so it uses the supported path.

Docs / Files

VQField files

VQField currently uses the .vqfield extension for compressed grids and their metadata. Single volumes and sequences use the same extension.

Compressed file

.vqfield

Contents

Single volumes and sequences

Ordinary grid output

Standard OpenVDB, .vdb

Keep the source VDBs and a validated build until the replacement workflow is accepted. Decoding recovers the reconstructed field, not detail discarded by lossy compression. Check grid names, frame range, transforms and values when moving a cache between tools.

Docs / Quality

Choose the trade-off, then check it

Quality is an encoder setting, not a percentage of retained detail. The same setting gives different sizes and errors on different fields.

Use one rate-control mode for each encode. For sequences, also test GOP length: shorter groups limit replay work when seeking; compression and access cost depend on the data.

Reports support a decision; they do not make it

Compare representative frames and all fields needed by the shot. Review silhouette, density detail, emission peaks, transforms and motion in the actual renderer. Record total source and output file bytes, plus cold load, prepared decode and cached access separately.

Agree acceptance criteria for your data before replacing production caches. Published results and their denominators are on Benchmarks; implementation and qualification limits are on Status.