Karana.KUtils.kdpy_assets ========================= .. py:module:: Karana.KUtils.kdpy_assets .. autoapi-nested-parse:: 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 ------- .. autoapisummary:: Karana.KUtils.kdpy_assets.MeshDefinition Functions --------- .. autoapisummary:: Karana.KUtils.kdpy_assets.parsePointingTarget Karana.KUtils.kdpy_assets.parseSkyColor Karana.KUtils.kdpy_assets.configureGraphics Karana.KUtils.kdpy_assets.parseGeometryParameters Karana.KUtils.kdpy_assets.createPrimitiveGeometry Karana.KUtils.kdpy_assets.geometryTextureExtents Karana.KUtils.kdpy_assets.colorToPixels Karana.KUtils.kdpy_assets.contrastingColor Karana.KUtils.kdpy_assets.createGridTexture Karana.KUtils.kdpy_assets.createChequeredTexture Karana.KUtils.kdpy_assets.collectNamedOptions Karana.KUtils.kdpy_assets.resolveResourceFile Karana.KUtils.kdpy_assets.createMeshMaterial Karana.KUtils.kdpy_assets.createWireframeMaterial Karana.KUtils.kdpy_assets.mergeMeshLayers Karana.KUtils.kdpy_assets.applyMaterialRecursively Karana.KUtils.kdpy_assets.applyIntrinsicScaleRecursively Karana.KUtils.kdpy_assets.configureMeshes Karana.KUtils.kdpy_assets.retainTerrainGrid Karana.KUtils.kdpy_assets.configureCelestialTerrains Karana.KUtils.kdpy_assets.configureGeotiffTerrains Karana.KUtils.kdpy_assets.configureTerrains Module Contents --------------- .. py:class:: MeshDefinition 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. .. py:attribute:: name :type: str .. py:attribute:: geometry_type :type: str .. py:attribute:: parameters :type: str .. py:function:: parsePointingTarget(value: str) -> str | numpy.ndarray Parse a frame name or a comma/space-delimited three-value target. .. py:function:: parseSkyColor(value: str) -> Karana.Scene.Color Convert a CSS color name or three/six-digit hexadecimal string. .. py:function:: configureGraphics(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) -> None 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. .. py:function:: parseGeometryParameters(definition: MeshDefinition) -> tuple[float, Ellipsis] | pathlib.Path 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. .. py:function:: createPrimitiveGeometry(geometry_type: str, parameters: tuple[float, Ellipsis]) Create one supported non-file kdFlex primitive geometry. .. py:function:: geometryTextureExtents(geometry_type: str, parameters: tuple[float, Ellipsis]) -> tuple[float, float] Return approximate physical UV extents for synthetic primitive textures. .. py:function:: colorToPixels(color: Karana.Scene.Color) -> numpy.ndarray Convert a kdFlex color to one uint8 RGB pixel. .. py:function:: contrastingColor(color: Karana.Scene.Color) -> numpy.ndarray Choose a black or white grid-line color against a background. .. py:function:: createGridTexture(name: str, background: Karana.Scene.Color, extents: tuple[float, float], spacing: tuple[float, float]) -> Karana.Scene.Texture Create a square RGB texture containing a physically spaced grid. .. py:function:: createChequeredTexture(name: str, first_color: Karana.Scene.Color, second_color: Karana.Scene.Color, extents: tuple[float, float], spacing: tuple[float, float]) -> Karana.Scene.Texture Create a square RGB texture containing physically spaced checks. .. py:function:: collectNamedOptions(entries: Any, option_name: str) -> dict[str, tuple[Any, Ellipsis]] Index one repeatable named option and reject duplicate mesh entries. .. py:function:: resolveResourceFile(path: pathlib.Path) -> pathlib.Path Resolve a relative mesh or texture file through ResourceFinder. .. py:function:: 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 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. .. py:function:: createWireframeMaterial(material: Karana.Scene.PhysicalMaterial) -> Karana.Scene.WireframeMaterial Create a wireframe material retaining the selected material's base color. .. py:function:: mergeMeshLayers(layer_names: Any) -> int Combine repeated scene-layer names into one bitmask. .. py:function:: applyMaterialRecursively(node: Any, material: Any) -> int Apply a material to every ScenePart below an imported file object. .. py:function:: applyIntrinsicScaleRecursively(node: Any, scale: numpy.ndarray) -> int Apply non-uniform intrinsic scale to every imported ScenePart. .. py:function:: configureMeshes(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) -> dict[str, Any] 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. .. py:function:: retainTerrainGrid(sim: Karana.KUtils.Sim.Sim, terrain_grid: Karana.Scene._Terrain_pybind11_Py.TerrainGrid) -> None 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. .. py:function:: configureCelestialTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) -> dict[str, Karana.Scene._Terrain_pybind11_Py.GeographicTerrainGrid] Create requested analytic celestial GeographicTerrainGrid instances. .. py:function:: configureGeotiffTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) -> dict[str, Karana.Scene._Terrain_pybind11_Py.GeoTiffTerrainGrid] Create requested named GeoTiffTerrainGrid instances. .. py:function:: configureTerrains(sim: Karana.KUtils.Sim.Sim, options: dict[str, Any]) -> dict[str, Karana.Scene._Terrain_pybind11_Py.GeoTiffTerrainGrid | Karana.Scene._Terrain_pybind11_Py.GeographicTerrainGrid] Create celestial grids before GeoTIFF grids for compatibility callers.