Principle:Iterative Dvc Plot Output Rendering

Knowledge Sources	DVC Documentation
Domains	Visualization, Output_Generation
Last Updated	2026-02-10 00:00 GMT

Overview

Plot output rendering is the process of converting filled Vega-Lite renderer objects into consumable output formats such as JSON payloads for programmatic consumption or HTML pages for interactive browser-based viewing.

Description

The final stage of the plot visualization pipeline takes the renderer objects -- each containing a complete Vega-Lite specification filled with data -- and serializes them into output formats that users or downstream tools can consume. This stage serves as the boundary between the internal data processing pipeline and the external world, and it must support multiple output modalities to accommodate different use cases.

The primary output format is JSON, which produces a structured payload containing the chart type, the list of revisions represented, and the filled Vega-Lite specification. This format is designed for programmatic consumption by IDE extensions (such as the VS Code DVC extension), web dashboards, and CI/CD pipelines that need to process plot data without rendering it visually. The JSON output supports an optional split mode where datapoints are partitioned by revision, enabling clients to render revision-specific views or lazy-load data.

The secondary output format is HTML, which produces a self-contained web page embedding the Vega-Lite specifications along with the Vega-Lite JavaScript runtime. Opening this file in a browser renders all plots as interactive charts with pan, zoom, and tooltip support. The HTML generation is delegated to the dvc_render library's render_html function, which accepts a list of renderer objects and an optional custom HTML template.

For image-type plots, the JSON output format is different: instead of a Vega-Lite specification, each datapoint produces a separate JSON entry with the image's src URL (either a base64 data URI or a file path) and the revision it came from.

The command-line interface (CmdPlots.run) orchestrates the output selection based on user flags: --json produces JSON output to stdout, --show-vega outputs the raw Vega-Lite spec for a single target, and the default behavior generates an HTML file and optionally opens it in the browser.

Usage

Use plot output rendering when:

• Filled renderer objects must be serialized to JSON for consumption by IDE extensions, APIs, or programmatic pipelines.
• An interactive HTML visualization page must be generated for browser-based chart viewing.
• The Vega-Lite specification must be split by revision for clients that render each revision separately.
• The system must handle both Vega-type chart renderers and image-type renderers in the same output payload.

Theoretical Basis

The output rendering process branches based on the renderer type and the requested output format:

FUNCTION to_json(renderer, split=False):
    IF renderer.TYPE == "vega":
        IF no datapoints:
            RETURN empty list

        revisions = renderer.get_revisions()

        IF split:
            // Partition spec: template without data + per-revision data arrays
            content, split_content = renderer.get_partial_filled_template()
        ELSE:
            // Complete spec with all data inline
            content = renderer.get_filled_template()
            split_content = {}

        RETURN [{
            "type": "vega",
            "revisions": revisions,
            "content": content,
            ...split_content
        }]

    IF renderer.TYPE == "image":
        // One entry per image datapoint
        RETURN [
            {
                "type": "image",
                "revisions": [datapoint.revision],
                "url": datapoint.src
            }
            FOR each datapoint in renderer.datapoints
        ]

The command-line orchestration follows a priority-based output selection:

FUNCTION run(args):
    // Step 1: Collect and resolve data
    plots_data = collect_and_resolve(args.targets, args.props)

    // Step 2: Match definitions to renderers
    renderers = match_defs_renderers(plots_data, output_dir, templates_dir)

    // Step 3: Select output format
    IF args.json:
        // JSON to stdout
        FOR each renderer in renderers:
            json_data[renderer.name] = to_json(renderer, args.split)
        write_json(json_data)
        RETURN

    IF args.show_vega:
        // Raw Vega-Lite spec for single target
        vega_renderer = find_first_vega_renderer(renderers)
        write_json(vega_renderer.get_filled_template())
        RETURN

    // Default: HTML output
    output_file = output_dir / "index.html"
    render_html(renderers, output_file, html_template)
    print(output_file.as_uri())
    IF args.open OR config.auto_open:
        open_browser(output_file)

The split mode for JSON output is particularly important for the VS Code extension integration. In split mode, the Vega-Lite specification is returned without the data array populated, and a separate per-revision data structure is provided alongside it. This allows the extension to dynamically toggle which revisions are visible without re-requesting the entire specification from DVC.

Related Pages

Implemented By

• Implementation:Iterative_Dvc_To_Json