Points3D
Solid spheres or cubes in a 3D plot, one per row.
Static previewStatic preview; loading the interactive plot
import hmplot as hm
data = {"x": [1, 2, 3, 4], "y": [3, 1, 4, 2], "z": [2, 4, 1, 3]}
with hm.Plot(data=data, type="3d", height=300, axes3d=True) as plot:
hm.Points3D(x="x", y="y", z="z")
plot
Options
Keywords are snake_case.
Options
datatable- A table for this mark alone: a mark with data displays on its own, in a Plot of its own.
Position
xchannel- The x position: a column, per-row values, or one value.
ychannel- The y position: a column, per-row values, or one value.
zchannel- The z position, in a 3D plot: a column, per-row values, or one value.
positionchannel- Positions as one column or an N x 2 (or N x 3) array, instead of x, y and z.
Appearance
fillchannel- The fill color: a CSS color, or a column of numbers or categories mapped to colors. Default: the theme's Points fill (#3478c7 in the default theme).
sizechannel- The diameter of each sphere (a cube's side is half of it): a number, or a column mapped to sizes through size_scale (its range in world units: continuous({ range: [2, 8] }) spans small to large spheres). A 3D plot's box is 100 world units across, so 4 is a twenty-fifth of it; a few hundred points read well at 2 to 6. Default:
4world units. opacitychannel- The opacity, 0 to 1: a number, or a column (categories map through opacity_scale). Default:
1.
Scales
fill_scalescale- The fill's scale, which marks can share: continuous({domain, colormap, transform}) for numbers, categorical({domain, range}) or ordinal() for categories.
colormapstring | color[] | object- The colormap of a numeric fill or color: a name, a list of colors, or {colors, space, positions}. Default: the theme's (Viridis).
size_scalescale- The size's scale, which marks can share: continuous({domain, range, transform}) for numbers (without a range, the automatic one), or categories with a numeric range.
opacity_scalescale- A categorical() scale from the opacity column's categories to opacities, 0 to 1.
Display
labelstring- The mark's name in the legend and the settings pane.
legendboolean- Whether the mark has a legend entry. Default:
True. visibleboolean- Whether the mark is drawn. Default:
True. domainsboolean- Whether the mark's data counts toward its axes' automatic domains; false leaves them to the other marks (a reference line, a decorative part). Default:
True. rows"auto"- "auto" draws one item when no channel reads a column (a line at a value, a label at a point), instead of one per row of the data; "@" view-state fields are not columns.
blend"normal" | "additive" | "multiply" | "screen" | "subtractive"- How the mark mixes with what is drawn under it; any mode but normal draws it transparent, and SVG and PDF exports draw additive and subtractive as an image. Default:
"normal". glownumber- How much the mark glows: its own color times glow blooms around it in the plot's presentation (0 does not glow); the Plot's bloom effect sets the bloom's strength and radius. SVG and PDF exports draw the whole plot as an image. Default:
0. shadeShadeSpec- A plugin's shade (registerPlugin): { kind, ...parameters }, as { kind: "hatch", spacing: 6 } (Python hm.shade("hatch", spacing=6)), recolors each fragment the mark draws; picking, tooltips, domains and legends are unchanged. SVG and PDF exports draw a shaded mark as an image.
optionsstring[]- The settings the settings pane shows for this mark, by name.
namestring- The mark's name in the settings pane, and the name facet.endpoint() and partition.endpoint() find it by.
Interaction
identityidentity- Whose rows these are for selections: an identity() shared by tables that show the same things. Default: its data's.
selectboolean | selection | object- Click to replace the selection; an exact repeat clears it. Shift/Meta/Ctrl-click toggles membership (whole series for Line, Area): true uses its data's selection, or give a selection(). input("root").set("id") writes an input instead: a click sets it to the clicked row's id (a drill-down's root), .set(literal(v)) to a constant, .reset() to its default, and a click on nothing restores its default (input("root", {default}), else a Select of that name's, else null); several marks may write one input.
hoverboolean | selection | object- Mark the row under the pointer as @hovered (a whole series for Line, Area), without fading the others: true uses its data's hover, or give a selection(). input("focus").set("series") writes an input instead: while the pointer is on a row the input shows its series (or .set(literal(v)), a constant), then its committed value again (a hover that would change this mark's own rows is an error).
tooltipboolean | field[] | object- Show the nearest row's values in a box by the pointer: true, a list of fields, or {fields, radius, content}. Default: the Plot's.
brushboolean | selection | object- Brush rows with Shift-drag (point marks; Line, Area brush whole series): true uses its data's brush, a selection() shares one, {selection, axis} picks the axes.
nearbyboolean | selection | object- Mark the rows near the pointer (point marks): true, a selection(), or {selection, radius, units, axis}.
nearestboolean | selection | object- Mark the row a tooltip shows as @nearest, with or without the tooltip: under the pointer, else the nearest drawn row within radius pixels (a whole series for Line, Area): true, a selection(), or {selection, radius}. Default: the Plot's.
respondboolean | "selected" | "brushed" | "hovered" | "nearby" | "nearest" | selection | array- Which interaction states fade this mark's other rows to selection_opacity; "hovered" fades them while hovering, "nearest" while a row is nearest. Default: the states it sets, except hover and nearest.
selection_opacitynumber- The opacity of the rows outside the selection while one is active. Default:
0.25. dragboolean | "x" | "y" | "z" | "xy" | "xz" | "yz" | "xyz"- Drag rows to move them (point marks): true along every numeric axis, or the axes to move along. Default:
False. enter_effectboolean | "fade" | object- How rows that arrive in a keyed update appear: "fade", or {effect, duration, easing}. animate()'s enter option is the value a channel starts from.
exit_effectboolean | "fade" | object- How rows that leave in a keyed update disappear, as enter_effect. animate()'s exit option is the value a channel ends at.
Animation
animationboolean- Animate changes to the mark's values. Default:
False. animation_durationnumber- How long an animated change takes. Default:
300ms. animation_easing"linear" | "quad-in" | "quad-out" | "quad-in-out" | "cubic-in" | "cubic-out" | "cubic-in-out" | "sine-in-out"- The animation's easing. Default:
"cubic-in-out".
Symbol
shape"sphere" | "cube"- The solid drawn at every point. Default:
"sphere". shape_scalescale- A categorical() scale from the shape column's categories to shape names.
Legend settings
legend_font_sizenumbersetting- The size of the mark's legend text. Default: the theme's (14 in the default theme). In px.
legend_font_familystringsetting- The font of the mark's legend text, a CSS font-family. Default: the plot's font.
legend_text_colorcolorsetting- The color of the mark's legend text. Default:
"#40505d". legend_tick_formatstringsetting- How a colorbar labels numbers: a d3-format string, or a %-pattern for dates. Default:
".3~g".
Color settings
quantizebooleansetting- Step a numeric fill or color into `levels` colors instead of a smooth gradient. Default:
False. levelsnumbersetting- How many colors quantize steps through. Default:
10.
Limits
max_elementsnumbersetting- The most rows the mark prepares on the GPU. Default:
250000.
The mark's own axes
x_transform"linear" | "log" | "sqrt" | "symlog"setting- This mark's own x transform, instead of its frame's. Default: its frame's.
x_invertbooleansetting- Reverse this mark's x direction. Default:
False. xbounds[number, number]setting- The x extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
xrange[number, number]setting- Where this mark's x extent lands, in its frame's world units. Default: its frame's.
y_transform"linear" | "log" | "sqrt" | "symlog"setting- This mark's own y transform, instead of its frame's. Default: its frame's.
y_invertbooleansetting- Reverse this mark's y direction. Default:
False. ybounds[number, number]setting- The y extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
yrange[number, number]setting- Where this mark's y extent lands, in its frame's world units. Default: its frame's.
z_transform"linear" | "log" | "sqrt" | "symlog"setting- This mark's own z transform, instead of its frame's. Default: its frame's.
z_invertbooleansetting- Reverse this mark's z direction. Default:
False. zbounds[number, number]setting- The z extent this mark maps, instead of its frame's domain (an image's or a grid's extent). Default: its frame's.
zrange[number, number]setting- Where this mark's z extent lands, in its frame's world units. Default: its frame's.
Geometry
detailnumbersetting- How finely each sphere is divided, 0 to 4: 3 is 320 triangles a sphere, 1 (80) draws a large dataset faster. Default:
3.
Shading
litbooleansetting- Shade the mark with the plot's lights. Default:
False. transparentbooleansetting- Draw the mark in the transparent pass, blended in depth order with other transparent marks. Default:
False.
3D settings
size_attenuationbooleansetting- Shrink far points in perspective, as three.js does. Default:
True.
Advanced renderer options
depth_writeboolean- Write visible point fragments to the depth buffer with normal blending; false leaves depth testing and nearest-point picking unchanged. Other blend modes disable depth writes. Default:
True. max_instancesnumber | null- The most rows drawn; past it the rows are sampled (null draws them all), though SVG and PDF exports draw every row. Default:
None.
Usage
Use a 3D Plot to see solid depth and optional lighting. Solid symbol shapes differ from the flat symbol choices on Points.
Without a fill, the points take the theme’s Points color. A sphere is an icosahedron divided detail times: 3 by default (320 triangles), round at the sizes a plot shows; with hundreds of thousands of points, a detail of 1 (80 triangles) draws faster. A cube is always flat.
depthWrite (depth_write in Python) defaults to true with normal blending. False draws the visible points without updating the depth buffer, so later points can cover nearer ones. Depth testing against other objects and nearest-point picking remain enabled. Additive, screen and other blend modes already disable depth writes.