Karana.KUtils.kdpy_assets

Karana.KUtils.kdpy_assets#

Configure kdpy graphics, meshes, materials, textures, and terrain.

This module converts declarative Kclick option dictionaries into live Scene objects. Parsing and validation helpers remain separate from construction so tests can exercise policy without creating a GUI or native graphics data.

Classes#

MeshDefinition

Describe one mesh before type-specific geometry validation.

Functions#

`parsePointingTarget`(→ str \| numpy.ndarray)	Parse a frame name or a comma/space-delimited three-value target.
`parseSkyColor`(→ Karana.Scene.Color)	Convert a CSS color name or three/six-digit hexadecimal string.
`configureGraphics`(→ None)	Apply scene-wide graphics settings after the GUI has been created.
`parseGeometryParameters`(→ tuple[float, ...)	Return validated primitive dimensions or an unresolved file path.
`createPrimitiveGeometry`(geometry_type, parameters)	Create one supported non-file kdFlex primitive geometry.
`geometryTextureExtents`(→ tuple[float, float])	Return approximate physical UV extents for synthetic primitive textures.
`colorToPixels`(→ numpy.ndarray)	Convert a kdFlex color to one uint8 RGB pixel.
`contrastingColor`(→ numpy.ndarray)	Choose a black or white grid-line color against a background.
`createGridTexture`(→ Karana.Scene.Texture)	Create a square RGB texture containing a physically spaced grid.
`createChequeredTexture`(→ Karana.Scene.Texture)	Create a square RGB texture containing physically spaced checks.
`collectNamedOptions`(→ dict[str, tuple[Any, Ellipsis]])	Index one repeatable named option and reject duplicate mesh entries.
`resolveResourceFile`(→ pathlib.Path)	Resolve a relative mesh or texture file through ResourceFinder.
`createMeshMaterial`(→ Karana.Scene.PhysicalMaterial)	Create one physical material from the mesh's exclusive color policy.
`createWireframeMaterial`(→ Karana.Scene.WireframeMaterial)	Create a wireframe material retaining the selected material's base color.
`mergeMeshLayers`(→ int)	Combine repeated scene-layer names into one bitmask.
`applyMaterialRecursively`(→ int)	Apply a material to every ScenePart below an imported file object.
`applyIntrinsicScaleRecursively`(→ int)	Apply non-uniform intrinsic scale to every imported ScenePart.
`configureMeshes`(→ dict[str, Any])	Create and configure all named meshes requested by the mesh command.
`retainTerrainGrid`(→ None)	Retain a TerrainGrid and register deterministic native cleanup.
`configureCelestialTerrains`(→ dict[str, ...)	Create requested analytic celestial GeographicTerrainGrid instances.
`configureGeotiffTerrains`(→ dict[str, ...)	Create requested named GeoTiffTerrainGrid instances.
`configureTerrains`(→ dict[str, ...)	Create celestial grids before GeoTIFF grids for compatibility callers.

Module Contents#

class Karana.KUtils.kdpy_assets.MeshDefinition[source]#

Describe one mesh before type-specific geometry validation.

The parameter string remains unparsed until every named mesh option has been indexed, allowing errors to identify the original --geometry entry.

name: str#

geometry_type: str#

parameters: str#

Karana.KUtils.kdpy_assets.parsePointingTarget(value: str) → str | numpy.ndarray[source]#: Parse a frame name or a comma/space-delimited three-value target.

Karana.KUtils.kdpy_assets.parseSkyColor(value: str) → Karana.Scene.Color[source]#: Convert a CSS color name or three/six-digit hexadecimal string.

Karana.KUtils.kdpy_assets.configureGraphics(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) → None[source]#

Apply scene-wide graphics settings after the GUI has been created.

The function returns when the optional graphics command was not invoked or GUI creation was disabled. If settings are applied, sim.gui.graphics must already exist; the launcher enforces that order.

Karana.KUtils.kdpy_assets.parseGeometryParameters(definition: MeshDefinition) → tuple[float, Ellipsis] | pathlib.Path[source]#

Return validated primitive dimensions or an unresolved file path.

Primitive dimensions must be positive and match the arity advertised by --geometry. File paths remain opaque until ResourceFinder lookup during scene-object construction.

Karana.KUtils.kdpy_assets.createPrimitiveGeometry(geometry_type: str, parameters: tuple[float, Ellipsis])[source]#: Create one supported non-file kdFlex primitive geometry.

Karana.KUtils.kdpy_assets.geometryTextureExtents(geometry_type: str, parameters: tuple[float, Ellipsis]) → tuple[float, float][source]#: Return approximate physical UV extents for synthetic primitive textures.

Karana.KUtils.kdpy_assets.colorToPixels(color: Karana.Scene.Color) → numpy.ndarray[source]#: Convert a kdFlex color to one uint8 RGB pixel.

Karana.KUtils.kdpy_assets.contrastingColor(color: Karana.Scene.Color) → numpy.ndarray[source]#: Choose a black or white grid-line color against a background.

Karana.KUtils.kdpy_assets.createGridTexture(name: str, background: Karana.Scene.Color, extents: tuple[float, float], spacing: tuple[float, float]) → Karana.Scene.Texture[source]#: Create a square RGB texture containing a physically spaced grid.

Karana.KUtils.kdpy_assets.createChequeredTexture(name: str, first_color: Karana.Scene.Color, second_color: Karana.Scene.Color, extents: tuple[float, float], spacing: tuple[float, float]) → Karana.Scene.Texture[source]#: Create a square RGB texture containing physically spaced checks.

Karana.KUtils.kdpy_assets.collectNamedOptions(entries: Any, option_name: str) → dict[str, tuple[Any, Ellipsis]][source]#: Index one repeatable named option and reject duplicate mesh entries.

Karana.KUtils.kdpy_assets.resolveResourceFile(path: pathlib.Path) → pathlib.Path[source]#: Resolve a relative mesh or texture file through ResourceFinder.

Karana.KUtils.kdpy_assets.createMeshMaterial(definition: MeshDefinition, geometry_parameters: tuple[float, Ellipsis] | pathlib.Path, material_kind: str, material_values: tuple[Any, Ellipsis], spacing: tuple[float, float], opacity: float) → Karana.Scene.PhysicalMaterial[source]#

Create one physical material from the mesh’s exclusive color policy.

Synthetic textures require primitive dimensions so their check or grid spacing approximates physical units. File textures resolve through the same resource search path used for model-relative assets.

Karana.KUtils.kdpy_assets.createWireframeMaterial(material: Karana.Scene.PhysicalMaterial) → Karana.Scene.WireframeMaterial[source]#: Create a wireframe material retaining the selected material’s base color.

Karana.KUtils.kdpy_assets.mergeMeshLayers(layer_names: Any) → int[source]#: Combine repeated scene-layer names into one bitmask.

Karana.KUtils.kdpy_assets.applyMaterialRecursively(node: Any, material: Any) → int[source]#: Apply a material to every ScenePart below an imported file object.

Karana.KUtils.kdpy_assets.applyIntrinsicScaleRecursively(node: Any, scale: numpy.ndarray) → int[source]#: Apply non-uniform intrinsic scale to every imported ScenePart.

Karana.KUtils.kdpy_assets.configureMeshes(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) → dict[str, Any][source]#

Create and configure all named meshes requested by the mesh command.

Mesh arguments arrive as parallel, repeatable, name-addressed option sets. Definitions establish valid names before appearance and transform options are joined to them, preventing partial native construction on input errors. Trail requests remain on sim until GUI setup creates graphical nodes.

Karana.KUtils.kdpy_assets.retainTerrainGrid(sim: Karana.KUtils.Sim.Sim, terrain_grid: Karana.Scene._Terrain_pybind11_Py.TerrainGrid) → None[source]#

Retain a TerrainGrid and register deterministic native cleanup.

Scene attachment alone does not express Python ownership. The explicit dictionary keeps the wrapper alive for scripts, while the callback releases its native object during normal kdFlex shutdown.

Karana.KUtils.kdpy_assets.configureCelestialTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) → dict[str, Karana.Scene._Terrain_pybind11_Py.GeographicTerrainGrid][source]#: Create requested analytic celestial GeographicTerrainGrid instances.

Karana.KUtils.kdpy_assets.configureGeotiffTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) → dict[str, Karana.Scene._Terrain_pybind11_Py.GeoTiffTerrainGrid][source]#: Create requested named GeoTiffTerrainGrid instances.

Karana.KUtils.kdpy_assets.configureTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) → dict[str, Karana.Scene._Terrain_pybind11_Py.GeoTiffTerrainGrid | Karana.Scene._Terrain_pybind11_Py.GeographicTerrainGrid][source]#: Create celestial grids before GeoTIFF grids for compatibility callers.