Skip to content

Reference Grid

This example adds a ground-plane reference grid to a 3D scene.

Preview

Reference Grid

Open the live WebGPU example.

Run And Adapt

Commands below assume a Datoviz source checkout and start at the repository root. Use your configured build environment; Python routes additionally require local bindings.

Route Availability Command or action
C Canonical native source just example-c features/reference_grid (build and run), or rerun ./build/examples/c/features/reference_grid
Python Available; direct-engine adaptation python3 -m examples.python.gallery.features.reference_grid
Browser Live WebGPU route Open live example

This example is approved as a starting point for user code and coding agents. Keep the object lifetimes and data shapes intact while adapting the data and styling.

What To Look For

The grid is attached to the XZ plane, shifted downward on Y, and configured with fixed size, spacing, and major-line cadence. Use the turntable controller in the live preview and compare object orientation against the grid plane. Reference grids are useful for judging scale, height, and horizontal position in sparse 3D scientific views.

Source

#!/usr/bin/env python3
"""Ground-plane reference grid in a 3D scene."""

from __future__ import annotations

import ctypes

import datoviz as dvz

from examples.python.gallery import common as ex


def _reference_grid_desc():
    desc = dvz.dvz_reference_grid_desc()
    desc.plane = dvz.DVZ_REFERENCE_GRID_XZ
    desc.origin[1] = -0.50
    desc.size[:] = (8.0, 8.0)
    desc.spacing = 0.25
    desc.major_every = 4
    return desc


def _add_reference_grid(panel) -> None:
    desc = _reference_grid_desc()
    grid = dvz.dvz_reference_grid(panel, ctypes.byref(desc))
    if not grid:
        raise RuntimeError("dvz_reference_grid() failed")


def main() -> None:
    scene, figure, panel = ex.scene_panel()
    camera = ex.manual_camera(panel)
    _add_reference_grid(panel)

    def configure(view) -> None:
        desc = dvz.dvz_turntable_desc()
        desc.controller_flags = dvz.DVZ_TURNTABLE_FLAGS_CLAMP_DISTANCE
        desc.initial_view = camera.view
        desc.min_distance = 0.03
        desc.max_distance = 24.0
        turntable = dvz.dvz_view_turntable(view, panel, ctypes.byref(desc))
        if not turntable:
            raise RuntimeError("dvz_view_turntable() failed")

    ex.run_with_view(scene, figure, "Reference Grid", configure)


if __name__ == "__main__":
    main()

/*
 * Copyright (c) 2021 Cyrille Rossant and contributors. All rights reserved.
 * Licensed under the MIT license. See LICENSE file in the project root for details.
 * SPDX-License-Identifier: MIT
 */

/* This example adds a ground-plane reference grid to a 3D scene.
 *
 * What to look for: the grid is attached to the XZ plane, shifted downward on Y, and configured
 * with fixed size, spacing, and major-line cadence. Use the turntable controller in the live
 * preview and compare object orientation against the grid plane. Reference grids are useful for
 * judging scale, height, and horizontal position in sparse 3D scientific views.
 *
 * Scenario: features_reference_grid
 * Style: features, graphite_cyan, 1280x720 window target
 *
 * Build:  just example-c features/reference_grid
 * Run:    ./build/examples/c/features/reference_grid --live
 * Smoke:  ./build/examples/c/features/reference_grid --png
 */



/*************************************************************************************************/
/*  Includes                                                                                     */
/*************************************************************************************************/

#include <stdbool.h>
#include <stdint.h>

#include "datoviz/scene.h"
#include "example_common.h"
#include "example_style.h"
#include "runner/scenario_runner.h"



/*************************************************************************************************/
/*  Forward declarations                                                                         */
/*************************************************************************************************/

DvzScenarioSpec dvz_example_reference_grid_scenario(void);



/*************************************************************************************************/
/*  Constants                                                                                    */
/*************************************************************************************************/

#define WIDTH  EXAMPLE_WINDOW_WIDTH
#define HEIGHT EXAMPLE_WINDOW_HEIGHT



/*************************************************************************************************/
/*  Scenario callbacks                                                                           */
/*************************************************************************************************/

/**
 * Initialize the reference-grid feature scenario.
 *
 * @param ctx scenario context
 * @param out_user scenario state output
 * @return true on success
 */
static bool _scenario_init(DvzScenarioContext* ctx, void** out_user)
{
    if (ctx == NULL)
        return false;
    if (out_user != NULL)
        *out_user = NULL;

    ctx->figure = dvz_figure(ctx->scene, ctx->width, ctx->height, 0);
    if (ctx->figure == NULL)
        return false;

    DvzPanel* panel = dvz_panel_full(ctx->figure);
    if (panel == NULL)
        return false;
    example_graphite_cyan_set_panel_background(panel);

    if (example_set_default_3d_camera(panel, 1.3f) == NULL)
        return false;

    DvzReferenceGridDesc grid = dvz_reference_grid_desc();
    grid.plane = DVZ_REFERENCE_GRID_XZ;
    grid.origin[1] = -0.50f;
    grid.size[0] = 8.0f;
    grid.size[1] = 8.0f;
    grid.spacing = 0.25f;
    grid.major_every = 4;
    if (dvz_reference_grid(panel, &grid) == NULL)
        return false;

    DvzController* controller = dvz_turntable(ctx->scene, NULL);
    if (controller == NULL)
        return false;
    if (dvz_scenario_bind_controller(ctx, panel, controller, DVZ_DIM_MASK_XYZ) != 0)
        return false;
    return true;
}


/**
 * Return the reference-grid scenario specification.
 *
 * @return scenario specification
 */
DvzScenarioSpec dvz_example_reference_grid_scenario(void)
{
    return (DvzScenarioSpec){
        .id = "features_reference_grid",
        .title = "Reference Grid",
        .width = WIDTH,
        .height = HEIGHT,
        .fps = 60.0,
        .init = _scenario_init,
    };
}



/*************************************************************************************************/
/*  Functions                                                                                    */
/*************************************************************************************************/

/**
 * Run the reference-grid feature example through the native scenario runner.
 *
 * @param argc command-line argument count
 * @param argv command-line argument vector
 * @return process exit code
 */
#ifndef DVZ_EXAMPLE_NO_MAIN
int main(int argc, char** argv)
{
    DvzScenarioSpec spec = dvz_example_reference_grid_scenario();
    return dvz_scenario_run_native_cli(&spec, argc, argv) == 0 ? 0 : 1;
}
#endif
Example details

Data

Field Value
kind synthetic