sylva.voxels.blocks¶
sylva.voxels.blocks ¶
Ray-traced voxel grids traced and stored block by block.
sylva.voxels.ray_voxelize with block_size= cuts the grid into
blocks and traces a few blocks at a time, so the memory taken while tracing
is set by max_memory rather than by the size of the grid. Each pass over
the blocks streams every pulse once and traces it into the blocks its line
passes through; a pulse is always walked through the whole grid, so every
voxel receives exactly what a whole-grid trace gives it (see the guide for
the exactness argument). With out= the finished blocks are written to a
directory as they complete, and the grid is returned as a
BlockedVoxelGrid, which reads blocks back on demand.
BlockedVoxelGrid ¶
A ray-traced voxel grid kept on disk block by block.
Made by sylva.voxels.ray_voxelize with out=, or opened with
open_blocked. The directory holds grid.json (placement,
block size, tracing options), ground_height.f64 when a DTM was given,
and one Parquet file per block with a row per voxel and a column per raw
field (blocks no pulse reached are not written and read as zeros).
Any block or box of voxels can be read as a ~sylva.voxels.RayVoxelGrid
with every derived field. Layer profiles, the occlusion summaries,
~sylva.voxels.tree_sampling and write run over the grid
one slab of blocks at a time; whole arrays by name (grid["pad_fpl"])
are assembled slab by slab and need the memory of one array.
block_size
property
¶
block_size: tuple[int, int, int]
Voxels per block along x, y and z (the last block of an axis may be shorter).
metrics
property
¶
metrics: list[str]
Names of the derived metrics, as for ~sylva.voxels.RayVoxelGrid.
observed
property
¶
observed: ndarray
Boolean (nz, ny, nx): voxels crossed by a pulse before its last echo.
blocks_present ¶
blocks_present() -> list[tuple[int, int, int]]
Blocks written to disk, (bx, by, bz); the others hold no pulse.
block ¶
block(index: tuple[int, int, int]) -> RayVoxelGrid
One block as a grid of its own.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
index
|
tuple[int, int, int]
|
|
required |
Returns:
| Type | Description |
|---|---|
RayVoxelGrid
|
With its origin at the block's corner. Voxel centres are computed from that origin, so they can differ from the whole grid's in the last bit. |
blocks ¶
blocks() -> Iterator[tuple[tuple[int, int, int], RayVoxelGrid]]
Every block, one at a time, as ((bx, by, bz), grid), z slowest.
read ¶
read(lo, hi) -> RayVoxelGrid
Voxels lo to hi as a grid of their own.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
lo
|
|
required | |
hi
|
|
required |
Returns:
| Type | Description |
|---|---|
RayVoxelGrid
|
|
profile ¶
profile(name: str = 'pad_fpl', min_beams: int = 1) -> np.ndarray
Mean of a field or metric per layer; see sylva.voxels.RayVoxelGrid.profile.
occlusion_profile ¶
occlusion_profile(min_height: float = 0.0, max_height: float | None = None) -> dict
What the scan saw of the canopy space; see sylva.voxels.RayVoxelGrid.occlusion_profile.
observed_map ¶
observed_map(min_height: float = 0.0, max_height: float | None = None) -> np.ndarray
Observed share of each column; see sylva.voxels.RayVoxelGrid.observed_map.
write ¶
write(path: str | Path, format: str | None = None, include_unobserved: bool = False, filled_only: bool = False) -> int
Write the grid as one .vox or text file, a slab of blocks at a time.
The rows are those sylva.voxels.RayVoxelGrid.write gives for
the whole grid; see there for the parameters.
Returns:
| Type | Description |
|---|---|
int
|
Number of voxels written. |
open_blocked ¶
open_blocked(path: str | Path) -> BlockedVoxelGrid
Open a grid written by sylva.voxels.ray_voxelize with out=.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
The grid's directory. |
required |
Returns:
| Type | Description |
|---|---|
BlockedVoxelGrid
|
|
Raises:
| Type | Description |
|---|---|
OSError
|
If the directory holds no complete blocked grid. |