KSLCore/ksl.modeling.agent/VoxelProjection

VoxelProjection

class VoxelProjection<A : AgentLike> @JvmOverloads constructor(val context: AgentModel.Context<A>, val columns: Int, val rows: Int, val layers: Int, val occupancy: VoxelOccupancy = VoxelOccupancy.MULTIPLE, val torus: Boolean = false, val name: String = "voxelGrid") : Projection<A> (source)

A 3D lattice projection: each agent in the context occupies an integer-coordinate Voxel. The grid has fixed columns, rows, and layers; voxels are addressed by (col, row, layer) with col ∈ [0, columns), row ∈ [0, rows), layer ∈ [0, layers). The 3D analog of GridProjection.

Occupancy semantics:

VoxelOccupancy.MULTIPLE (default) — multiple agents may share a voxel. Typical for swarm / flock / drone models with low altitude separation.
VoxelOccupancy.SINGLE — at most one agent per voxel. placeAt throws if the target voxel is already occupied by a different agent; use tryPlaceAt for the conditional case. Useful for warehouse-style storage models where each slot holds one item.

Boundary semantics:

Bounded (default) — coordinates outside the bounds throw.
Torus (torus = true) — coordinates wrap on all three axes. (A "ground+ceiling" model — wrap horizontally only, hard boundary vertically — should keep torus = false and clamp the vertical axis in the user's motion code.)

Spatial queries — neighborsOf, agentsAt, voxelsWithin — do linear scans over the occupancy map. Performance is fine for typical agent counts; for sphere-shaped continuous neighbor queries against many agents, use ContinuousVolume which has a spatial-hash index.

Constructors

VoxelProjection

@JvmOverloads

constructor(context: AgentModel.Context<A>, columns: Int, rows: Int, layers: Int, occupancy: VoxelOccupancy = VoxelOccupancy.MULTIPLE, torus: Boolean = false, name: String = "voxelGrid")

Types

Defaults

object Defaults

Mutable global defaults for VoxelProjection queries.

Properties

columns

val columns: Int

context

val context: AgentModel.Context<A>

layers

val layers: Int

name

open override val name: String

Display name for diagnostics.

occupancy

val occupancy: VoxelOccupancy

rows

val rows: Int

size

val size: Int

Number of agents currently placed on the grid.

torus

val torus: Boolean

Functions

agentsAt

fun agentsAt(voxel: Voxel): List<A>

All agents currently on voxel. Empty list if the voxel is unoccupied.

fun agentsAt(col: Int, row: Int, layer: Int): List<A>

agentsWithin

fun agentsWithin(voxel: Voxel, radius: Int, metric: VoxelMetric = VoxelMetric.CHEBYSHEV, includeCenter: Boolean = false): List<A>

All agents currently in voxels within radius of voxel under metric. Excludes occupants of voxel itself unless includeCenter is true.

isEmpty

fun isEmpty(voxel: Voxel): Boolean

True if voxel has no occupants.

moore26Neighborhood

fun moore26Neighborhood(voxel: Voxel, includeSelf: Boolean = false): List<Voxel>

The 26 voxels in the Moore-26 neighborhood (Chebyshev3D distance 1) around voxel. If includeSelf is true, voxel is included (27 total).

moveTo

fun moveTo(agent: A, voxel: Voxel)

Equivalent to placeAt; provided for symmetry with movement-style code.

fun moveTo(agent: A, col: Int, row: Int, layer: Int)

neighborsOf

fun neighborsOf(agent: A, radius: Int = Defaults.neighborhoodRadius, metric: VoxelMetric = VoxelMetric.CHEBYSHEV): List<A>

All other agents within radius of agent's voxel. Excludes agent itself but includes any co-occupants of its voxel.

onAgentLeft

open override fun onAgentLeft(agent: A)

Called by the AgentModel.Context when agent leaves. Default no-op — projections that track per-agent state (positions, edges) typically override to drop their bookkeeping for the departing agent.

placeAt

fun placeAt(agent: A, voxel: Voxel)

Place agent at the given voxel. For VoxelOccupancy.SINGLE grids, throws if the target voxel is already occupied by a different agent.

fun placeAt(agent: A, col: Int, row: Int, layer: Int)

tryPlaceAt

fun tryPlaceAt(agent: A, voxel: Voxel): Boolean

Conditional placement for single-occupancy grids: returns true if the voxel was free (or already held this agent) and the placement succeeded; false if the voxel was occupied by another agent. Always succeeds for multi-occupancy grids.

vonNeumann6Neighborhood

fun vonNeumann6Neighborhood(voxel: Voxel, includeSelf: Boolean = false): List<Voxel>

The 6 voxels in the Von-Neumann-6 neighborhood (Manhattan3D distance 1) around voxel. If includeSelf is true, voxel is included (7 total).

voxelOf

fun voxelOf(agent: A): Voxel?

Voxel currently occupied by agent, or null if not placed.

voxelsWithin

fun voxelsWithin(voxel: Voxel, radius: Int, metric: VoxelMetric = VoxelMetric.CHEBYSHEV, includeSelf: Boolean = false): List<Voxel>

All voxels within radius of voxel under the given metric. Excludes voxel itself unless includeSelf is true. Voxels outside the bounds are dropped for non-torus grids.