Skip to main content

3D surface plot

A 3D surface plot turns a grid of z values into a quadrilateral mesh, projected orthographically and painted back to front. Each cell becomes a filled quad, optionally coloured by its own height, which is what makes a smooth function legible as a shape rather than as a heatmap.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/surface3d.tsv')),
grid AS (
SELECT y, list(z ORDER BY x) AS row_vals
FROM d GROUP BY y
)
SELECT kuva_render(to_json({
'title': 'Surface',
'series': [{
'type': 'surface3d',
'z_data': (SELECT list(row_vals ORDER BY y) FROM grid),
'x_coords': (SELECT list(x ORDER BY x) FROM (SELECT DISTINCT x FROM d)),
'y_coords': (SELECT list(y ORDER BY y) FROM (SELECT DISTINCT y FROM d)),
'z_colormap': 'viridis',
'x_label': 'X',
'y_label': 'Y',
'z_label': 'Z'
}]
})) AS chart;

Long-format input becomes z_data with a nested list: the inner one collects each row's values in x order, the outer one stacks those rows in y order. The two x_coords / y_coords lists then give the axes real coordinates — leave them out and the axes are labelled 0..n-1.

Generating a surface in SQL​

A grid generated straight from a formula is the clearest way to see what the chart does with a smooth function — and in SQL that is a generate_series and an expression rather than a closure.

WITH g AS (
SELECT i AS row, j AS col,
((j - 25) / 25.0 * 3)::DOUBLE AS x,
((i - 25) / 25.0 * 3)::DOUBLE AS y
FROM generate_series(0, 50) AS t(i), generate_series(0, 50) AS u(j)
),
grid AS (
SELECT row, list(sqrt(x * x + y * y) * sin(x * x + y * y) ORDER BY col) AS row_vals
FROM g GROUP BY row
)
SELECT kuva_render(to_json({
'title': 'Wave (50 × 50)',
'series': [{
'type': 'surface3d',
'z_data': (SELECT list(row_vals ORDER BY row) FROM grid),
'z_colormap': 'viridis',
'azimuth': -60,
'elevation': 35
}]
})) AS chart;

That is the same surface the library's own function-based example produces — sin(sqrt(x²+y²)) over [-3, 3]² — with the grid built by generate_series instead of a Rust closure.

Wireframe and transparency​

The wireframe is on by default and is what makes a surface read as a mesh rather than a blob of colour. wireframe: false gives a clean filled surface; a low alpha with a thin dark wireframe gives the ghosted look that lets you see the far side of a fold.

WITH d AS (SELECT * FROM read_csv_auto('{{DFK_BASE_URL}}data/surface3d.tsv')),
grid AS (
SELECT y, list(z ORDER BY x) AS row_vals
FROM d GROUP BY y
)
SELECT kuva_render(to_json({
'title': 'No wireframe',
'series': [{
'type': 'surface3d',
'z_data': (SELECT list(row_vals ORDER BY y) FROM grid),
'z_colormap': 'inferno',
'wireframe': false,
'x_label': 'X',
'y_label': 'Y',
'z_label': 'Z'
}]
})) AS chart;

Explicit coordinates​

FieldDefaultWhat it sets
x_coords0..ncolsOne x value per column — must match the column count
y_coords0..nrowsOne y value per row — must match the row count

Without them the axes are labelled by index, which is fine for a surface generated on an abstract grid and misleading for anything with real units.

WITH g AS (
SELECT i AS row, j AS col,
(j - 5) * 0.5 AS x,
(i - 5) * 0.5 AS y
FROM generate_series(0, 10) AS t(i), generate_series(0, 10) AS u(j)
),
grid AS (
SELECT row, list(sqrt(x * x + y * y) * sin(x * x + y * y) ORDER BY col) AS row_vals
FROM g GROUP BY row
)
SELECT kuva_render(to_json({
'title': 'Explicit coordinates',
'series': [{
'type': 'surface3d',
'z_data': (SELECT list(row_vals ORDER BY row) FROM grid),
'x_coords': [-2.5, -2.0, -1.5, -1.0, -0.5, 0, 0.5, 1.0, 1.5, 2.0, 2.5],
'y_coords': [-2.5, -2.0, -1.5, -1.0, -0.5, 0, 0.5, 1.0, 1.5, 2.0, 2.5],
'z_colormap': 'viridis',
'alpha': 0.9,
'wireframe_width': 0.3,
'wireframe_color': '#222222'
}]
})) AS chart;

Fields​

FieldTypeWhat it sets
z_datanumber[][]Required. Row-major heights; every row the same length, and at least 2×2.
x_coords / y_coordsnumber[]Real coordinates for the columns and rows.
colorstringUniform surface colour when no colour map is given.
z_colormapstringColour each face by its average height, and draw a colour bar.
wireframebooleanDraw the mesh edges (default on).
wireframe_color / wireframe_widthstring / numberTheir appearance.
alphanumberSurface opacity (default 1).
azimuth / elevationnumberCamera angles (defaults -60 / 30).
x_label / y_label / z_labelstringAxis labels; z_label also titles the colour bar.
show_grid / show_boxbooleanBack-wall grid and the bounding box.
grid_linesintegerDivisions per axis (default 5).
z_axis_right / z_axis_autobooleanWhere the z axis is drawn.
legendstringLegend label for the series.

Notes​

  • z_data must be rectangular and at least 2 × 2 — a single row or column has no faces to draw.
  • x_coords and y_coords must match the column and row counts exactly; a mismatch is an error.
  • There is no resolution field: the grid you pass is the resolution. generate_series decides it.
  • alpha below 1 with painting back-to-front produces visible ordering artefacts — the far faces are drawn first and then tinted through, which is not the same as true transparency.
  • z_colormap colours each face by its average height, so a coarse grid smooths the colour as well as the shape.

See also​