fix: obstruction masks and cell-centred slice planes

[m-fehr]

Fixes #132.

What masked=True means

masked=True keeps its original meaning: it hides where the obstructions are, now without the errors described in #132. A new option, mask="placeholders", hides only the values FDS did not compute but filled with the ambient value, and keeps the gas values FDS writes on the faces of an obstruction:

slc.to_global(masked=True)                       # the obstructions (default, as before)
slc.to_global(masked=True, mask="placeholders")  # only values FDS did not compute

The option exists for slices, Plot3D and Smoke3D (to_global, Smoke3D.to_physical) and as Mesh.get_obstruction_mask(..., mode=...) / get_obstruction_mask_slice(..., mode=...).

Fixed

	before	now
Cell-centred mask	cells x1 … x2 on every axis (one too many)	cells x1 … x2-1 inside the obstruction
Node-based mask	nodes x1 … x2-1: lower face masked, upper face not	nodes x1 … x2, both faces
Plane of a cell-centred 2D slice	one of the two cells next to node k, chosen by float rounding	the cell below node k, as FDS writes SLCC … k k; the integer indices from the .smv file are kept on SubSlice (bound_indices, index_ranges())
to_global(return_coordinates=True) for cell-centred slices	node positions	cell centres (e.g. PBZ=0.4 → z = 0.45, as Smokeview labels it)
Several obstruction parts with the same ID in a mesh	only the first masked	all (Obstruction.get_subobstructions)
get_2d_slice_from_3d	cut slices defined with XB at the mesh's index; cell-centred cuts on a node chosen by rounding	cuts at the slice's own index; on a node takes the cell above it, like FDS for PBZ

The placeholder mode follows FDS's own rule (CORNER_VALUE in dump.f90): a node gets the ambient value if all cells of its mesh around it are solid.

Checked against Smokeview and FDS

New test case slcf_masks_fds611 (FDS 6.11.1, input in tests/cases/fds_inputs/slcf_masks.fds, so the release and nightly checks run it too): three meshes, one adjoining another only partly, and obstructions inside a mesh, across a mesh boundary, at the outside of the domain, two sharing a face, one with a hole, and ones ending at a mesh boundary.

• Smokeview: three slices were read off by hand in Smokeview 6.11.2 (node-based PBZ=0.7 and PBY=0.8, cell-centred PBZ=0.4 through to_global(masked=True)); all 600 areas agree with fdsreader (master: 181/200 on the cell-centred one). The readings are tests.
• Obstruction mask agrees with the obstruction coordinates in the .smv file on every slice and mesh.
• Placeholder mask blocks exactly the values FDS wrote as ambient (20 °C) after 10 s of fire, on every slice and mesh; every placeholder lies inside the obstruction mask.
• The tests with fake obstructions in tests/test_slice_to_global.py keep their expectations from master.

Behaviour changes (for the release notes)

• masked=True gives different arrays: cell-centred masks are one cell smaller per side, node-based masks are no longer shifted towards the lower corner, cell-centred planes may move to the other cell layer.
• Obstructions without thickness block no cells any more (no cell lies inside them; Smokeview does not blank them), but still the nodes on them.
• Mesh.get_obstruction_mask_slice() returns the mask in the shape of the subslice's data.
• Results without masked=True are unchanged.

Not included

• extent of a cell-centred plane still lies on node k, while its coordinates now are the cell centre.
• Solids defined with &GEOM are not part of either mask; velocity slices (face values) follow a different rule in FDS.

The slices, Plot3D and Smoke3D example notebooks were run again; the slices example no longer needs the known-issue note.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.18182% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
fdsreader/slcf/slice.py	98.14%	0 Missing and 1 partial ⚠️
fdsreader/smoke3d/smoke3d.py	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!