3D Charts (Visual WebGL)

vizb supports three 3D modes for bar, line, and scatter charts. Both render in a WebGL scene you can rotate, zoom, and pan in the browser. Other chart types (pie, radar, heatmap) receive z-axis data differently — they don’t render a 3D scene.

Scatter also supports continuous 3D from auto-value (all-numeric columns, no flags). Bar and line do the same when the data has 3+ numeric columns. See the Scatter Chart page for auto-value mode.

Three 3D Modes

Mode	How to enable	X (width)	Y (depth)	Z (height)
Grouped	Add z to --group-pattern / --group-regex	categories	categories	metric value (stacked per z group)
Value (pseudo-3D)	vizb bar / vizb line / vizb scatter with --3d on x+y-only data	categories	categories (former 2D legend)	metric value (single series, visualMap)
Value (continuous 3D)	All-numeric CSV/JSON with 3+ columns (auto-value)	numeric	numeric	numeric

Grouped 3D takes precedence: if your data already has a z dimension, --3d is ignored.

Grouped 3D (z in the pattern)

A chart renders in grouped 3D when a data point has all three plotting axes present:

• XAxis — categories along the width
• YAxis — categories along the depth’s base
• ZAxis — grouping values for stacked layers / legend (not the vertical axis title)

In grouped 3D the vertical axis is the metric (chart title). The z column name is still set on the axis for layout, but rendered transparent so it does not read as a categorical height label. The pattern slot z drives the legend and ChartCard badge. Value mode (--3d) still names the vertical axis with the metric.

The Name dimension stays optional — it still groups points into separate charts. Without a z-axis, charts render as the usual 2D bar/line/pie.

Note

The z-axis (z) is only valid alongside both x and y. A 3D chart needs an x/y floor to stand on.

Generating 3D Data

Add a z segment to your grouping pattern or a (?<z>…) capture to your regex.

Sample sales data for the CSV commands below (copy → sales.csv). Full file: examples/csv/sales.csv (10,000 rows, 2024–2025).

sales.csvCopy CSV

order_date	region	category	product	quantity	amount
2024-01-01	Central	Hardware	Connector	16	2488.24
2024-01-02	East	Tools	Gear	42	207.08
2024-01-03	North	Mechanical	Sensor	20	3465.22
2024-01-04	West	Electronics	Valve	24	7633.44
2024-03-12	South	Industrial	Widget	31	5088.10
2024-06-18	East	Electronics	Relay	12	2214.50
2024-09-05	North	Hardware	Bolt	28	1724.27
2024-12-20	West	Tools	Gadget	19	2938.82
2025-02-08	Central	Mechanical	Valve	27	7350.26
2025-04-14	South	Electronics	Widget	41	3278.77
2025-07-22	East	Industrial	Connector	15	5093.42
2025-10-03	North	Tools	Gear	33	4102.15
2025-11-19	West	Hardware	Sensor	22	2890.40
2025-12-28	South	Mechanical	Gadget	26	611.32

Pattern — CSV (x,y,z) or benchmarks (x/y/z):

CSV/JSON — region × product floor, category as z layers:

CLI

vizb bar sales.csv -g region,product,category -p x,y,z -o output.html

HTTP

POST / on vizb serve. The API takes inlineinput, not a file path.

{
  "input": "order_date,region,category,product,quantity,amount\n2024-01-01,Central,Hardware,Connector,16,2488.24\n2024-01-02,East,Tools,Gear,42,207.08\n2024-01-03,North,Mechanical,Sensor,20,3465.22\n2024-01-04,West,Electronics,Valve,24,7633.44\n2024-03-12,South,Industrial,Widget,31,5088.10\n2024-06-18,East,Electronics,Relay,12,2214.50\n2024-09-05,North,Hardware,Bolt,28,1724.27\n2024-12-20,West,Tools,Gadget,19,2938.82\n2025-02-08,Central,Mechanical,Valve,27,7350.26\n2025-04-14,South,Electronics,Widget,41,3278.77\n2025-07-22,East,Industrial,Connector,15,5093.42\n2025-10-03,North,Tools,Gear,33,4102.15\n2025-11-19,West,Hardware,Sensor,22,2890.40\n2025-12-28,South,Mechanical,Gadget,26,611.32\n",
  "parser": "csv",
  "grouping": {
    "columns": [
      "region",
      "product",
      "category"
    ],
    "pattern": "x,y,z"
  },
  "charts": {
    "types": [
      "bar"
    ]
  },
  "output": {
    "format": "html"
  }
}

Action

GitHub Action step. Same conversion as the CLI.

- uses: goptics/vizb@v0
  with:
    file: sales.csv
    group: region,product,category
    group-pattern: x,y,z
    charts: bar
    output-html: output.html

# Benchmarks — slash-separated names
go test -bench . | vizb -p x/y/z -o output.html

Source	Label example	XAxis	YAxis	ZAxis
CSV row	alpha,beta,gamma	alpha	beta	gamma
Benchmark	BenchmarkSort/1024/QuickSort/warm	1024	QuickSort	warm

Pass each CSV/JSON column as a --group field in pattern order. See the Tabular Data guide.

Regex — named z capture:

CLI

vizb bar data.csv -g category,metric,group,series --group-regex "(?<n>.*)/(?<x>.*)/(?<y>.*)/(?<z>.*)" -o output.html

HTTP

POST / on vizb serve. The API takes inlineinput, not a file path.

{
  "input": "<contents of data.csv>",
  "parser": "csv",
  "grouping": {
    "columns": [
      "category",
      "metric",
      "group",
      "series"
    ],
    "regex": "(?<n>.*)/(?<x>.*)/(?<y>.*)/(?<z>.*)"
  },
  "charts": {
    "types": [
      "bar"
    ]
  },
  "output": {
    "format": "html"
  }
}

Action

GitHub Action step. Same conversion as the CLI.

- uses: goptics/vizb@v0
  with:
    file: data.csv
    group: category,metric,group,series
    group-regex: "(?<n>.*)/(?<x>.*)/(?<y>.*)/(?<z>.*)"
    charts: bar
    output-html: output.html

If you supply a z without both x and y, vizb rejects the pattern:

zAxis (z) requires both xAxis (x) and yAxis (y)

See the Group guide for full pattern and regex syntax.

Value (pseudo) 3D (--3d on x+y data)

When you have only x and y dimensions, a 2D bar/line/scatter chart puts every y category in the legend — hard to read with many series. Pass --3d on vizb bar, vizb line, or vizb scatter to project the same data into 3D: y categories move to depth, and the metric value becomes bar/line/point height. With --3d, a visualMap gradient colors the geometry by metric value (on by default).

CSV with x+y columns — no z grouping needed:

CLI

vizb bar sales.csv -g region,category -p x,y --3d -o output.html

HTTP

POST / on vizb serve. The API takes inlineinput, not a file path.

{
  "input": "order_date,region,category,product,quantity,amount\n2024-01-01,Central,Hardware,Connector,16,2488.24\n2024-01-02,East,Tools,Gear,42,207.08\n2024-01-03,North,Mechanical,Sensor,20,3465.22\n2024-01-04,West,Electronics,Valve,24,7633.44\n2024-03-12,South,Industrial,Widget,31,5088.10\n2024-06-18,East,Electronics,Relay,12,2214.50\n2024-09-05,North,Hardware,Bolt,28,1724.27\n2024-12-20,West,Tools,Gadget,19,2938.82\n2025-02-08,Central,Mechanical,Valve,27,7350.26\n2025-04-14,South,Electronics,Widget,41,3278.77\n2025-07-22,East,Industrial,Connector,15,5093.42\n2025-10-03,North,Tools,Gear,33,4102.15\n2025-11-19,West,Hardware,Sensor,22,2890.40\n2025-12-28,South,Mechanical,Gadget,26,611.32\n",
  "parser": "csv",
  "grouping": {
    "columns": [
      "region",
      "category"
    ],
    "pattern": "x,y"
  },
  "charts": {
    "types": [
      "bar"
    ],
    "configs": [
      {
        "type": "bar",
        "threeD": true
      }
    ]
  },
  "output": {
    "format": "html"
  }
}

Action

GitHub Action step. Same conversion as the CLI.

- uses: goptics/vizb@v0
  with:
    file: sales.csv
    group: region,category
    group-pattern: x,y
    charts: bar
    chart: "bar:3d"
    output-html: output.html

CLI

vizb line sales.csv -g region,category -p x,y --3d -o output.html

HTTP

POST / on vizb serve. The API takes inlineinput, not a file path.

{
  "input": "order_date,region,category,product,quantity,amount\n2024-01-01,Central,Hardware,Connector,16,2488.24\n2024-01-02,East,Tools,Gear,42,207.08\n2024-01-03,North,Mechanical,Sensor,20,3465.22\n2024-01-04,West,Electronics,Valve,24,7633.44\n2024-03-12,South,Industrial,Widget,31,5088.10\n2024-06-18,East,Electronics,Relay,12,2214.50\n2024-09-05,North,Hardware,Bolt,28,1724.27\n2024-12-20,West,Tools,Gadget,19,2938.82\n2025-02-08,Central,Mechanical,Valve,27,7350.26\n2025-04-14,South,Electronics,Widget,41,3278.77\n2025-07-22,East,Industrial,Connector,15,5093.42\n2025-10-03,North,Tools,Gear,33,4102.15\n2025-11-19,West,Hardware,Sensor,22,2890.40\n2025-12-28,South,Mechanical,Gadget,26,611.32\n",
  "parser": "csv",
  "grouping": {
    "columns": [
      "region",
      "category"
    ],
    "pattern": "x,y"
  },
  "charts": {
    "types": [
      "line"
    ],
    "configs": [
      {
        "type": "line",
        "threeD": true
      }
    ]
  },
  "output": {
    "format": "html"
  }
}

Action

GitHub Action step. Same conversion as the CLI.

- uses: goptics/vizb@v0
  with:
    file: sales.csv
    group: region,category
    group-pattern: x,y
    charts: line
    chart: "line:3d"
    output-html: output.html

# Disable the gradient while keeping value 3D
vizb bar sales.csv -g region,category -p x,y --3d --3d-visualmap=false -o output.html

# Grouped z 3D with visualMap only
vizb bar sales.csv -g region,product,category -p x,y,z --3d-visualmap -o output.html

The HTML bundles 3D view and 3D visual map toggles in settings (both on by default when --3d was passed). Turn 3D view off to return to the flat 2D chart without re-running the CLI.

Note

--3d on vizb bar / vizb line is separate from vizb ui --3d, which only opts in to bundling the 3D engine for remote --data-url pages.

Continuous 3D (auto-value)

When your CSV/JSON data has 3+ numeric columns, auto-value renders continuous 3D — no --3d flag needed. This works on bar, line, and scatter:

All-numeric CSV — auto-detects x, y, z → bar3D:

CLI

vizb bar spiral.csv -o bar.html

HTTP

POST / on vizb serve. The API takes inlineinput, not a file path.

{
  "input": "<contents of spiral.csv>",
  "parser": "csv",
  "charts": {
    "types": [
      "bar"
    ]
  },
  "output": {
    "format": "html"
  }
}

Action

GitHub Action step. Same conversion as the CLI.

- uses: goptics/vizb@v0
  with:
    file: spiral.csv
    charts: bar
    output-html: bar.html

# Same for line and scatter
vizb line spiral.csv -o line.html
vizb scatter spiral.csv -o scatter.html

See Group vs Select → Auto-value for the full inference rules. In short: 3 coordinate columns auto-enable 3D, and solo --select (or limiting it to 2 columns) keeps the chart 2D.

When a CSV/JSON has four numeric columns, vizb treats the first three as x, y, z positions and the fourth as a visual metric — 3d-visualmap is enabled automatically so point color and size follow the metric.

Continuous 3D uses the same WebGL scene as grouped 3D — rotate, zoom, pan, and the auto-rotate toggle all apply.

3D Chart Types

3D Bar

Stacked 3D bars — each z value stacks on the (x, y) cell. The bar-top label shows the stacked total when value labels are on.

3D Line

3D polylines across the x/y grid, with scatter markers at each vertex so individual points stay readable.

3D Scatter

scatter3D points — grouped z series or auto-value continuous coordinates.

Auto-Rotate

3D charts gain an Auto rotate toggle in the settings panel (it only appears for 3D data). Enable it to continuously spin the scene for a hands-free walkaround.

Axis-Sum Tooltips

Hover any cell to see its breakdown plus marginal sums — each marginal is the sum over the other axes:

• Σ z — the stacked height at this (x, y) cell (sum over z)
• Σ x — total for this x value (sum over the other axes)
• Σ y — total for this y value (sum over the other axes)

Sums honor the legend: toggle a z series off and the totals recompute to reflect only what’s visible. Tooltips follow light/dark mode automatically.

Tip

2D charts get axis sums too — per-series totals after each name and a labeled x-marginal at the bottom of the tooltip.

Next Steps

HeatmapX × Y colored grid — works great with or without z, never renders WebGL.

Bar ChartBar chart in all three dimensions — 1D, 2D, and 3D.

Line ChartLine chart in all three dimensions — 1D, 2D, and 3D.

Scatter ChartCoordinate plotting with grouped, value, and hybrid modes.

Axis SwappingSwap z in and out interactively to toggle between 3D and 2D.

SettingsAuto-rotate and other runtime controls.