Skip to content

contour and slice of structured grids by flying edges (#316) - #401

Open
berkgeveci wants to merge 5 commits into
Kitware:mainfrom
berkgeveci:vis/flying-edges
Open

berkgeveci wants to merge 5 commits into
Kitware:mainfrom
berkgeveci:vis/flying-edges

Conversation

@berkgeveci

@berkgeveci berkgeveci commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #316: contour of structured grids by flying edges, solid grids' triangles and 2D grids' lines, and slice/slice_plane of structured grids by a plane cutter, hidden and refined cells (AMR boxes) left out in place.

A structured grid of solid cells with a point field and positions on the points is now contoured by flying edges, as VTK's vtkFlyingEdges3D and Viskores' flying edges. The grid can be an image, a rectilinear grid or a curvilinear one. Crossings are counted along the grid's rows, numbered by a scan and written once. There are no per-corner arrays, no per-cell arrays and no sort. The new code is in algorithms/_flying_edges.py. The old tack.deprecated implementation (removed in 55009d3) served as a reference for the passes; this is written afresh on the dataset API.

The same output as the general path

The triangles, points and carried values are the general path's, bit for bit, up to their order:

  • every crossing is read through the same views (an image's positions by get_ijk, as its cells read them);
  • it is placed from the end first by position;
  • it is named by the end it lands on (_end_hit);
  • every cell takes the hexahedron case table's triangles;
  • a triangle two of whose crossings land on one point is dropped.

The passes

  1. Classify the edges. One thread per point marks which of its edges along +x, +y and +z are crossed, per value, in a byte per point. The positions are not read here.
  2. Landings. Only the crossed edges are checked for landing on an end; this is where positions are read. It was folded into the first pass at first, and slowed that pass about ten times on the CPU even though it rarely runs.
  3. Counts. Each row of points counts what it emits and marks the points that crossings land on. Each row of cells counts its triangles; rows of cells whose four rows of points have no crossings are skipped.
  4. Write the points, row by row.
  5. Write the triangles, walking each row of cells along x with a running count for the four rows of points around it.

Rows that emit nothing are skipped. NaNs are flagged in the first pass, and a crossing whose cells all hold a NaN is compacted away, as the general path never makes it.

Measurements

M1 Max. Memory is the peak above the input (tracemalloc, CPU only).

image, values CPU, flying edges CPU, general Metal, flying edges Metal, general
224³ (11M cells), 10 values 219 ms, 0.32 GB 259 ms, 2.24 GB 136 ms 201 ms
224³, 1 value 36 ms, 0.07 GB 38 ms, 0.25 GB 25 ms 31 ms
432³ (80M cells), 2 values 263 ms, 0.30 GB 346 ms, 1.32 GB 139 ms 179 ms

The issue gives vtkFlyingEdges3D at 0.39 GB on the first case, and 0.270 s on the 432³ image at two values.

This is not VTK's full algorithm:

  • VTK reads each value once, building y- and z-edge and cell cases from x-edge cases;
  • it trims each row to its first and last crossing.

The time is already on par with VTK, and trimming saves little for surfaces that cross whole rows. On Metal the passes that walk rows dominate (107 of the 139 ms at 432³), so splitting rows into shorter pieces would help more there.

The plane cutter

The second commit adds the plane cutter. slice by a Plane through an image or a rectilinear grid of solid cells (and so slice_plane) goes by flying edges over each row's stretch near the plane only, as VTK's vtkFlyingEdgesPlaneCutter:

  • Windows. Each (row, value) has a window of points, outside which none of its points' edges is crossed, and only the windows' flags are kept. Along a row the plane's distance is affine in i on an image and monotone in the axis on a rectilinear grid. So the window is a few lines of arithmetic, or two binary searches, computed on the device. It is widened by the largest change of distance along an edge of the grid, plus rounding.
  • Values computed where read. The distance is Plane.value of the point's position, the expression implicit_values stores, so the bits are the same and nothing is kept for the other points.
  • Contour uses windows too. The flying-edges passes take the windows for contour as well, whose windows are whole rows.
slice_plane of a 432³ image (80M cells), CPU time peak above the input
general path 177 ms 0.71 GB
flying-edges contour of the plane's distance 142 ms 0.43 GB
plane cutter 14 ms 0.03 GB

The issue gives VTK's cutter at 8 ms; what remains here is mostly the launches of ten small kernels.

The cutter is checked against the general slice_plane, bit for bit, up to order, in f32 and f64:

  • tilted planes and three parallel planes in one pass;
  • planes through grid points, across and along the rows;
  • a negative normal and a rotated image;
  • an origin at 1e4 and rectilinear grids;
  • a plane missing the grid.

Other implicit functions, 2D grids and unmerged points go the old way.

Hidden cells and curvilinear planes

The third commit adds two things.

Hidden and refined cells (Ghosts.MASKED_CELLS, every AMR box with a finer level) are left out in place by both paths:

  • A masked cell makes no triangles.
  • Crossings only masked cells use are dropped afterwards, as for cells with a NaN corner.

Before, contour called visible(), which extracts the other cells into an unstructured mesh, so a box with one refined cell lost flying edges altogether. The output is still the general path's (which extracts first), bit for bit, up to order, the cells' ghost marks included.

A plane through a curvilinear grid takes the cutter too. Its points may lie anywhere, so every row is visited, but the distance is still computed where read rather than stored for every point.

at 256³, CPU new before
plane through an image with a tenth of its cells refined 12 ms, 0.01 GB 116 ms, 1.49 GB
plane through a curvilinear grid 7 ms, 0.01 GB 47 ms, 0.16 GB
contour of an image with a tenth of its cells refined (a noisy field, 42.7M triangles) 468 ms, 2.23 GB 916 ms, 11.4 GB

2D grids

The fourth commit adds 2D grids. A sheet's contour lines go by flying edges too.

  • The same point passes. They run with one layer of cells along z, reading points through the cells' (i, j) views.
  • Two line passes. One counts, one writes, and they pair each cell's crossings going round its sides, as the general path's _level_lines pairs them: each rising crossing with the next falling one, so the values above lie on the line's right.
  • Dropped and skipped lines. A line whose two ends land on one point is dropped. A cell none of whose sides is crossed is skipped from the points' codes.

The lines, points and values are the general path's, bit for bit, up to order, orientation included.

contour of a 4096² image, CPU flying edges general path
1 value 33 ms, 0.02 GB 53 ms, 2.01 GB
10 values 252 ms, 0.18 GB 251 ms, 14.1 GB

The general path derives and sorts the mesh's sides and keeps every side's crossing per value, which is where its memory goes.

Checked

  • New test_structured_contour.py (22 tests, quick tier), flying edges and the cutter against the general path, bit for bit: hidden, refined and duplicate cells on images, rectilinear and curvilinear grids, and 2D grids' lines (values on points, NaNs, hidden cells), as well as:
    • an image with a vector field, one value and four;
    • values landing exactly on grid points;
    • NaNs (no stray points);
    • rectilinear and curvilinear grids;
    • f32 and f64;
    • ghost marks carried;
    • and which grids and fields go the general way.
  • The quick tier (3183 passed), the slower modules that contour, slice or probe AMR (770 passed), and the 163 doc examples, on the CPU.
  • Ruff, changelog, SPDX, the reference-page check.
  • Metal: timed only, with the tests not run there.

🤖 Generated with Claude Code

A structured grid of solid cells -- an image, a rectilinear or a
curvilinear grid -- with a point field and positions on the points is
contoured by flying edges, as VTK's vtkFlyingEdges3D: each point's
edges along +x, +y and +z classified once per value (a byte a point), the
points each row emits and the triangles each row of cells makes counted
and scanned, then written once, the triangles' pass walking each row of
cells with a running count for the four rows of points around it. No
per-corner arrays, no per-cell arrays, no sort.

Crossings are read through the same views, placed from the end first by
position and named by the end they land on (_end_hit), as the general
path places them, so the triangles, points and carried values are its
own, bit for bit, up to their order. On an 11M-cell image at ten values
(CPU, M1 Max) the peak above the input falls from 2.24 to 0.32 GB and the
time from 259 to 219 ms; on Metal, 201 to 136 ms.
@berkgeveci berkgeveci added this to the 0.8 milestone Nov 9, 2026
slice by a Plane through an image or a rectilinear grid of solid cells
goes by flying edges over each row's stretch near the plane, as VTK's
vtkFlyingEdgesPlaneCutter. Each (row, value) has a window of points,
found from the plane's equation -- along a row the distance is affine in
i on an image and monotone in the axis on a rectilinear grid -- widened by
the largest change of distance along an edge and by rounding, so every
crossed edge is inside; only the windows' flags are kept. The distance is
computed where it is read, Plane.value of the point's position as
implicit_values stores it, so the output is the general path's, bit for
bit, up to its order.

The flying-edges passes take the windows for contour too, whose windows
are whole rows. A plane through a 432^3 image (80M cells, CPU, M1 Max)
took 177 ms and 0.71 GB above the input; it takes 14 ms and 0.03 GB.
@berkgeveci berkgeveci changed the title contour of structured grids by flying edges (#316) contour and slice of structured grids by flying edges (#316) Nov 9, 2026
Hidden and refined cells (Ghosts.MASKED_CELLS, an AMR box's) make no
triangles in the flying-edges contour and the plane cutter, and crossings
only they use are dropped afterwards, as for cells with a NaN corner. The
output is the general path's, which first extracts the other cells into
an unstructured mesh, bit for bit, up to order, ghost marks included;
contour no longer extracts them for a grid flying edges takes.

A plane through a curvilinear grid takes the cutter too: every row, the
distance computed where read rather than stored for every point.

At 256^3 (CPU, M1 Max): a plane through an image with a tenth of its
cells refined, 116 ms and 1.49 GB to 12 ms and 0.01 GB; through a
curvilinear grid, 47 ms to 7 ms.
A 2D structured grid (a sheet) takes the flying-edges points' passes, one
layer of cells along z, through an (i, j) reader of its cells' views
(_Sheet; _Solid for a solid grid), and two line passes, counting and
writing, that walk each row of cells with the first number of its two rows
of points. Each cell's lines are its crossings going round its sides
through its view, paired as contour._level_lines pairs them -- each rising
crossing with the next falling one, the values above on the line's right
-- and a line whose two crossings land on one point is dropped; a cell none
of whose sides is crossed is skipped from the points' codes. Hidden,
refined and NaN cells are left out as in 3D.

The lines, points and values are the general path's, bit for bit, up to
order, orientation included. On a 4096^2 image (CPU, M1 Max): at ten
values 0.18 GB above the input against 14.1, 252 ms against 251; at one
value 0.02 GB against 2.01, 33 ms against 53.
…arts on main: the flying-edges check stays in contour)
@berkgeveci

Copy link
Copy Markdown
Collaborator Author

Merged main in (82fc288). It needed a hand: main moved contour's shape path into _triangle_parts after this branch was made, and git placed the flying-edges check inside that function, where top, several and fields are not defined. The textual merge was clean, but the result would have raised. The check is back in contour(), before _triangle_parts is called. This branch's tests, every module that contours or slices (2896 passed) and the quick tier pass on the merge. #466 (the cut filters' memory plan, D4) is stacked on it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Contour and slice of structured data by arithmetic

1 participant