camsim 0.1.0__py3-none-any.whl

camsim/__init__.py

@@ -0,0 +1,65 @@
+"""camsim: deterministic camera sensor and ISP simulation with IQ metrics.
+
+The public namespace is deliberately lazy (PEP 562). Importing ``camsim`` loads
+only version metadata; public types are resolved on first attribute access.
+This keeps ``import camsim.metrics`` free of the sensor, ISP, scene, and optics
+packages, which the metrics harness is required not to depend on.
+
+Later phases register public names in ``_LAZY_EXPORTS`` as
+``name -> (module path, attribute name)`` pairs.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, Final
+
+from ._version import __version__
+
+if TYPE_CHECKING:
+    # Static analysers and the documentation builder cannot execute the lazy
+    # ``__getattr__`` below, so mirror the public map with type-checking-only
+    # aliases. This block is never imported at runtime and therefore adds no
+    # cost to ``import camsim``.
+    from camsim.camera.camera import Camera as Camera
+    from camsim.config.schema import LensConfig as LensConfig
+    from camsim.core.spectral import SpectralIrradiance as SpectralIrradiance
+    from camsim.core.spectral import WavelengthGrid as WavelengthGrid
+    from camsim.isp.pipeline import ISP as ISP
+    from camsim.sensor import Sensor as Sensor
+
+__all__: Final[list[str]] = [
+    "ISP",
+    "Camera",
+    "LensConfig",
+    "Sensor",
+    "SpectralIrradiance",
+    "WavelengthGrid",
+    "__version__",
+]
+
+# Public name -> (module path, attribute name). Populated as public types land.
+_LAZY_EXPORTS: Final[dict[str, tuple[str, str]]] = {
+    "Camera": ("camsim.camera.camera", "Camera"),
+    "ISP": ("camsim.isp.pipeline", "ISP"),
+    "LensConfig": ("camsim.config.schema", "LensConfig"),
+    "Sensor": ("camsim.sensor", "Sensor"),
+    "SpectralIrradiance": ("camsim.core.spectral", "SpectralIrradiance"),
+    "WavelengthGrid": ("camsim.core.spectral", "WavelengthGrid"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a lazily exported public name on first access."""
+    try:
+        module_path, attribute = _LAZY_EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    value = getattr(import_module(module_path), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Include lazily exported names in ``dir(camsim)`` and tab completion."""
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_EXPORTS))

camsim/_version.py

@@ -0,0 +1,7 @@
+"""Single source of truth for the package version.
+
+``pyproject.toml`` reads this file through hatchling, so installed distribution
+metadata and ``camsim.__version__`` cannot drift apart.
+"""
+
+__version__ = "0.1.0"

camsim/camera/__init__.py

@@ -0,0 +1,24 @@
+"""Camera orchestration and the opt-in auto-exposure policy.
+
+:class:`~camsim.camera.camera.Camera` binds a lens, a sensor, and an ISP into
+one object that can turn a rendered scene into a display image. The default
+capture is the fixed-exposure baseline from the sensor preset; auto-exposure is
+an explicit request that probes the real sensor, meters the black-corrected
+signal with a centre-weighted statistic, and reports every decision.
+
+The package re-exports the three public value types:
+
+* :class:`Camera` — capture and auto-exposure entry points.
+* :class:`ExposureSettings` — a fixed exposure, analog gain, and readout mode.
+* :class:`ExposureResult` — the measured settings and evidence from one
+  auto-exposure run.
+
+Importing the package loads the camera module, which in turn imports the
+sensor, ISP, and scene layers; ``import camsim`` itself remains lazy.
+"""
+
+from __future__ import annotations
+
+from camsim.camera.camera import Camera, ExposureResult, ExposureSettings
+
+__all__ = ["Camera", "ExposureResult", "ExposureSettings"]