obdeect-sources 0.8.0__tar.gz

obdeect_sources-0.8.0/CMakeLists.txt

@@ -0,0 +1,101 @@
+cmake_minimum_required(VERSION 3.20)
+project(obdeect_sources LANGUAGES CXX)
+
+option(OBDEECT_SOURCES_BUILD_TESTING "Build the C++ tests" ON)
+if(DEFINED SKBUILD_PLATLIB_DIR)
+  set(OBDEECT_SOURCES_BUILD_PYTHON_API_DEFAULT ON)
+else()
+  set(OBDEECT_SOURCES_BUILD_PYTHON_API_DEFAULT OFF)
+endif()
+option(OBDEECT_SOURCES_BUILD_PYTHON_API "Build the Python extension" ${OBDEECT_SOURCES_BUILD_PYTHON_API_DEFAULT})
+
+# The stream component: the target of the combined build, else the stream sources next to
+# this component (builds from the repository), else an installed package (sdist builds).
+if(NOT TARGET obdeect::stream)
+  if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/../stream/CMakeLists.txt)
+    set(OBDEECT_STREAM_BUILD_TESTING OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_TOOLS OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_CAPI OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_BUILD_PYTHON_API OFF CACHE BOOL "" FORCE)
+    set(OBDEECT_STREAM_INSTALL OFF CACHE BOOL "" FORCE)
+    add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../stream ${CMAKE_CURRENT_BINARY_DIR}/stream)
+    message(STATUS "obdeect sources: using the stream sources in ../stream")
+  else()
+    find_package(Python 3.14 COMPONENTS Interpreter)
+    if(Python_Interpreter_FOUND AND NOT obdeect_stream_DIR)
+      execute_process(COMMAND "${Python_EXECUTABLE}" -m obdeect.stream --cmake-dir
+                      OUTPUT_VARIABLE obdeect_stream_DIR OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_QUIET)
+    endif()
+    find_package(obdeect_stream CONFIG REQUIRED)
+    message(STATUS "obdeect sources: using the installed stream package ${obdeect_stream_VERSION} (${obdeect_stream_DIR})")
+  endif()
+endif()
+
+# Header-only, standard-library-only core. Photon chunks use the obdeect stream headers.
+add_library(obdeect_sources_core INTERFACE)
+target_include_directories(obdeect_sources_core INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/cpp/include)
+target_compile_features(obdeect_sources_core INTERFACE cxx_std_20)
+target_link_libraries(obdeect_sources_core INTERFACE obdeect::stream)
+# Identical floating-point results for any thread count and chunk size on one
+# platform: no implicit fused multiply-add contraction.
+target_compile_options(obdeect_sources_core INTERFACE -ffp-contract=off)
+
+function(obdeect_sources_enable_warnings target)
+  target_compile_options(${target} PRIVATE -Wall -Wextra -Wpedantic -Werror)
+  # GCC 13 reports false maybe-uninitialized warnings inside std::variant at -O3.
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    target_compile_options(${target} PRIVATE -Wno-error=maybe-uninitialized)
+  endif()
+endfunction()
+
+if(OBDEECT_SOURCES_BUILD_PYTHON_API)
+  find_package(Python 3.14 COMPONENTS Interpreter Development.Module REQUIRED)
+  execute_process(COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
+                  OUTPUT_VARIABLE nanobind_DIR OUTPUT_STRIP_TRAILING_WHITESPACE
+                  COMMAND_ERROR_IS_FATAL ANY)
+  find_package(nanobind CONFIG REQUIRED)
+  nanobind_add_module(_core NB_STATIC cpp/bindings/core.cpp)
+  target_link_libraries(_core PRIVATE obdeect_sources_core)
+  obdeect_sources_enable_warnings(_core)
+  install(TARGETS _core LIBRARY DESTINATION obdeect/sources)
+endif()
+
+if(OBDEECT_SOURCES_BUILD_TESTING)
+  enable_testing()
+  foreach(test_name version density source stream_contract)
+    add_executable(obdeect_sources_test_${test_name} cpp/tests/test_${test_name}.cpp)
+    target_link_libraries(obdeect_sources_test_${test_name} PRIVATE obdeect_sources_core)
+    # check.hpp lives with the stream tests; tests are built from the repository only, never from an sdist.
+    target_include_directories(obdeect_sources_test_${test_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../stream/cpp/tests)
+    obdeect_sources_enable_warnings(obdeect_sources_test_${test_name})
+    add_test(NAME ${test_name} COMMAND obdeect_sources_test_${test_name})
+  endforeach()
+endif()
+
+# Light-source programs: tool and test sources share the program name.
+option(OBDEECT_SOURCES_BUILD_TOOLS "Build the light-source command-line tools" ON)
+set(OBDEECT_SOURCES_LIGHT_SOURCE_PROGRAMS
+    flasher led point-source beam-scan laser-beam night-sky muon-track)
+if(OBDEECT_SOURCES_BUILD_TESTING)
+  foreach(test_name ${OBDEECT_SOURCES_LIGHT_SOURCE_PROGRAMS} sky_args)
+    add_executable(obdeect_sources_test_${test_name} cpp/tests/test_${test_name}.cpp)
+    target_link_libraries(obdeect_sources_test_${test_name} PRIVATE obdeect_sources_core)
+    # check.hpp lives with the stream tests; tests are built from the repository only, never from an sdist.
+    target_include_directories(obdeect_sources_test_${test_name} PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../stream/cpp/tests)
+    obdeect_sources_enable_warnings(obdeect_sources_test_${test_name})
+    add_test(NAME ${test_name} COMMAND obdeect_sources_test_${test_name})
+  endforeach()
+endif()
+if(OBDEECT_SOURCES_BUILD_TOOLS)
+  foreach(tool ${OBDEECT_SOURCES_LIGHT_SOURCE_PROGRAMS})
+    add_executable(obdeect-sources-${tool} cpp/tools/${tool}.cpp)
+    target_link_libraries(obdeect-sources-${tool} PRIVATE obdeect_sources_core)
+    obdeect_sources_enable_warnings(obdeect-sources-${tool})
+  endforeach()
+  # Wheels: inside the package, run through `obdeect sources <program>`.
+  if(DEFINED SKBUILD_PLATLIB_DIR)
+    foreach(tool ${OBDEECT_SOURCES_LIGHT_SOURCE_PROGRAMS})
+      install(TARGETS obdeect-sources-${tool} RUNTIME DESTINATION obdeect/sources/bin)
+    endforeach()
+  endif()
+endif()

obdeect_sources-0.8.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: obdeect-sources
+Version: 0.8.0
+Summary: Artificial light sources for Cherenkov telescopes
+Author: obdeect contributors
+License-Expression: BSD-3-Clause
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.14
+Requires-Dist: numpy>=2.3
+Requires-Dist: obdeect-stream==0.8.0
+Provides-Extra: dev
+Requires-Dist: nanobind>=3.1; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: pyyaml; extra == "docs"
+Requires-Dist: sphinx; extra == "docs"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Description-Content-Type: text/markdown
+
+# obdeect-sources
+
+Artificial light sources for Cherenkov-telescope simulations: flashers, illuminators, lasers,
+LEDs and stars. Sources emit photons at sky, telescope-sphere, telescope or camera level. The
+C++20 core uses only the standard library. It has a Python API and writes photon streams.
+
+```sh
+pip install obdeect-sources     # this component only (also installs obdeect-stream)
+pip install obdeect             # all obdeect components
+```
+
+Requires Python 3.14 or higher.
+
+## Commands
+
+```sh
+obdeect sources flasher --type dish --photons 1e6     # also --type secondary, --frame camera
+obdeect sources led --camera-file cam.dat --photons 500
+obdeect sources point-source
+obdeect sources beam-scan
+obdeect sources laser-beam
+obdeect sources night-sky
+obdeect sources muon-track
+```
+
+Full documentation and the repository README: https://github.com/gammasim/obdeect

obdeect_sources-0.8.0/README.md

@@ -0,0 +1,26 @@
+# obdeect-sources
+
+Artificial light sources for Cherenkov-telescope simulations: flashers, illuminators, lasers,
+LEDs and stars. Sources emit photons at sky, telescope-sphere, telescope or camera level. The
+C++20 core uses only the standard library. It has a Python API and writes photon streams.
+
+```sh
+pip install obdeect-sources     # this component only (also installs obdeect-stream)
+pip install obdeect             # all obdeect components
+```
+
+Requires Python 3.14 or higher.
+
+## Commands
+
+```sh
+obdeect sources flasher --type dish --photons 1e6     # also --type secondary, --frame camera
+obdeect sources led --camera-file cam.dat --photons 500
+obdeect sources point-source
+obdeect sources beam-scan
+obdeect sources laser-beam
+obdeect sources night-sky
+obdeect sources muon-track
+```
+
+Full documentation and the repository README: https://github.com/gammasim/obdeect

obdeect_sources-0.8.0/cpp/bindings/core.cpp

@@ -0,0 +1,228 @@
+// nanobind extension obdeect.sources._core: the only C++ file that depends on Python.
+
+#include <nanobind/nanobind.h>
+#include <nanobind/ndarray.h>
+#include <nanobind/stl/string.h>
+#include <nanobind/stl/vector.h>
+
+#include "obdeect/sources/density.hpp"
+#include "obdeect/sources/source.hpp"
+#include "obdeect/sources/streams.hpp"
+#include "obdeect/sources/version.hpp"
+
+#include "obdeect/stream/format.hpp"
+#include "obdeect/stream/photons.hpp"
+
+#include <cmath>
+#include <cstdint>
+#include <memory>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace nb = nanobind;
+using namespace obdeect::sources;
+
+namespace {
+
+Vec3 to_vec3(const std::vector<double> &v, const char *what) {
+  if (v.size() != 3)
+    throw std::invalid_argument(std::string(what) + " needs three components");
+  const Vec3 out{v[0], v[1], v[2]};
+  if (!is_finite(out))
+    throw std::invalid_argument(std::string(what) + " must be finite");
+  return out;
+}
+
+void need(const std::vector<double> &params, std::size_t n, const char *kind) {
+  if (params.size() != n)
+    throw std::invalid_argument(std::string(kind) + ": wrong number of parameters");
+}
+
+LinearDensity table(const std::vector<double> &x, const std::vector<double> &y) {
+  return LinearDensity(x, y);
+}
+
+Spectrum make_spectrum(const std::string &kind, const std::vector<double> &p,
+                       const std::vector<double> &x, const std::vector<double> &y) {
+  if (kind == "fixed") {
+    need(p, 1, "fixed spectrum");
+    return Fixed{p[0]};
+  }
+  if (kind == "uniform") {
+    need(p, 2, "uniform spectrum");
+    return UniformRange{p[0], p[1]};
+  }
+  if (kind == "inverse_square") {
+    need(p, 2, "inverse_square spectrum");
+    return InverseSquare{p[0], p[1]};
+  }
+  if (kind == "table") {
+    need(p, 0, "table spectrum");
+    return Tabulated{table(x, y)};
+  }
+  throw std::invalid_argument("unknown spectrum kind '" + kind + "'");
+}
+
+Pulse make_pulse(const std::string &kind, const std::vector<double> &p,
+                 const std::vector<double> &x, const std::vector<double> &y) {
+  if (kind == "fixed") {
+    need(p, 1, "fixed pulse");
+    return Fixed{p[0]};
+  }
+  if (kind == "tophat") {
+    need(p, 2, "tophat pulse");
+    return UniformRange{p[1] - 0.5 * p[0], p[1] + 0.5 * p[0]};
+  }
+  if (kind == "gauss") {
+    need(p, 2, "gauss pulse");
+    return GaussianShape{p[1], p[0]};
+  }
+  if (kind == "exponential") {
+    need(p, 2, "exponential pulse");
+    return Exponential{p[1], p[0]};
+  }
+  if (kind == "complex") {
+    need(p, 4, "complex pulse");
+    return ComplexPulse{p[0], p[1], p[2], p[3]};
+  }
+  if (kind == "table") {
+    need(p, 0, "table pulse");
+    return Tabulated{table(x, y)};
+  }
+  throw std::invalid_argument("unknown pulse kind '" + kind + "'");
+}
+
+double cone_u0(double angle_deg) {
+  if (!(std::isfinite(angle_deg) && angle_deg >= 0.0 && angle_deg <= 180.0))
+    throw std::invalid_argument("angle_deg must be finite and in [0, 180]");
+  return 1.0 - std::cos(angle_deg * pi / 180.0);
+}
+
+Angular make_angular(const std::string &kind, const std::vector<double> &p,
+                     const std::vector<double> &x, const std::vector<double> &y) {
+  if (kind == "isotropic" || kind == "lambertian" || kind == "rayleigh" || kind == "table")
+    need(p, 0, kind.c_str());
+  if (kind == "isotropic")
+    return Isotropic{};
+  if (kind == "lambertian")
+    return Lambertian{};
+  if (kind == "rayleigh")
+    return TabulatedAngular{rayleigh_angular_table()};
+  if (kind == "cone") {
+    need(p, 1, "cone");
+    return FixedAngle{cone_u0(p[0])};
+  }
+  if (kind == "filled_cone") {
+    need(p, 1, "filled_cone");
+    return FilledCone{cone_u0(p[0])};
+  }
+  if (kind == "gauss") {
+    need(p, 1, "gauss");
+    return TabulatedAngular{gaussian_angular_table(p[0] * pi / 180.0)};
+  }
+  if (kind == "table")
+    return TabulatedAngular{table(x, y)};
+  throw std::invalid_argument("unknown angular kind '" + kind + "'");
+}
+
+// A float32 numpy array that owns a copy of the values.
+nb::object to_array(const std::vector<float> &values) {
+  auto *data = new float[values.size()];
+  std::copy(values.begin(), values.end(), data);
+  nb::capsule owner(data, [](void *p) noexcept { delete[] static_cast<float *>(p); });
+  return nb::cast(nb::ndarray<nb::numpy, float>(data, {values.size()}, owner));
+}
+
+} // namespace
+
+NB_MODULE(_core, m) {
+  m.doc() = "obdeect sources native core";
+  m.def("core_version", [] { return nb::make_tuple(version_major, version_minor, version_patch); });
+  m.def("stream_contract", [] {
+    nb::dict d;
+    d["format_major"] = obdeect::stream::format_major;
+    d["format_minor"] = obdeect::stream::format_minor;
+    d["max_chunk_rows"] = obdeect::stream::max_chunk_rows;
+    d["sources_format_major"] = photon_stream_format_major;
+    nb::dict frames;
+    frames["sky"] = static_cast<int>(obdeect::stream::Frame::sky);
+    frames["telescope"] = static_cast<int>(obdeect::stream::Frame::telescope);
+    frames["camera"] = static_cast<int>(obdeect::stream::Frame::camera);
+    d["frames"] = frames;
+    nb::list columns;
+    for (std::uint32_t c = 0; c < obdeect::stream::n_columns; ++c)
+      if ((source_columns >> c) & 1U)
+        columns.append(obdeect::stream::column_name(static_cast<obdeect::stream::Column>(c)));
+    d["emitted_columns"] = columns;
+    return d;
+  });
+
+  nb::class_<Spectrum>(m, "Spectrum");
+  nb::class_<Pulse>(m, "Pulse");
+  nb::class_<Angular>(m, "Angular");
+  m.def("make_spectrum", &make_spectrum, nb::arg("kind"), nb::arg("params"), nb::arg("x"),
+        nb::arg("y"));
+  m.def("make_pulse", &make_pulse, nb::arg("kind"), nb::arg("params"), nb::arg("x"), nb::arg("y"));
+  m.def("make_angular", &make_angular, nb::arg("kind"), nb::arg("params"), nb::arg("x"),
+        nb::arg("y"));
+
+  nb::class_<Emitter>(m, "Emitter")
+      .def("__init__", [](Emitter *self, const std::vector<double> &position,
+                          const std::vector<double> &pointing, const Angular &angular) {
+        new (self) Emitter{to_vec3(position, "position"), to_vec3(pointing, "pointing"), angular};
+      });
+  nb::class_<Star>(m, "Star").def("__init__", [](Star *self, const std::vector<double> &towards,
+                                                 double distance_m, double disk_radius_m,
+                                                 double disk_z_m, double start_z_m) {
+    new (self)
+        Star{to_vec3(towards, "towards_source"), distance_m, disk_radius_m, disk_z_m, start_z_m};
+  });
+
+  nb::class_<Source>(m, "Source")
+      .def("__init__",
+           [](Source *self, int frame, nb::object geometry, const Spectrum &spectrum,
+              const Pulse &pulse, double photons) {
+             if (frame != 0 && frame != 2 && frame != 3)
+               throw std::invalid_argument("frame must be 0 (sky), 2 (telescope) or 3 (camera)");
+             new (self) Source();
+             self->frame = static_cast<obdeect::stream::Frame>(frame);
+             if (nb::isinstance<Emitter>(geometry))
+               self->geometry = nb::cast<Emitter>(geometry);
+             else if (nb::isinstance<Star>(geometry))
+               self->geometry = nb::cast<Star>(geometry);
+             else
+               throw std::invalid_argument("geometry must be an Emitter or a Star");
+             self->spectrum = spectrum;
+             self->pulse = pulse;
+             self->photons = photons;
+             validate(*self);
+           })
+      .def("set_disc_target",
+           [](Source &s, const std::vector<double> &centre, const std::vector<double> &normal,
+              double radius) {
+             s.target = DiscTarget{to_vec3(centre, "centre"), to_vec3(normal, "normal"), radius};
+           })
+      .def("set_sphere_target",
+           [](Source &s, const std::vector<double> &centre, double radius) {
+             s.target = SphereTarget{to_vec3(centre, "centre"), radius};
+           })
+      .def("validate", [](const Source &s) { validate(s); })
+      .def("expected_count", [](const Source &s) { return expected_count(s); })
+      .def("photon_count",
+           [](const Source &s, std::uint64_t seed, std::uint32_t event, std::uint32_t telescope) {
+             return photon_count(s, seed, event, telescope);
+           })
+      .def("emit", [](const Source &s, std::uint64_t seed, std::uint32_t event,
+                      std::uint32_t telescope, std::uint64_t first_index, std::size_t rows) {
+        obdeect::stream::PhotonChunk chunk;
+        emit(s, seed, event, telescope, first_index, rows, chunk);
+        nb::dict out;
+        for (std::uint32_t c = 0; c < obdeect::stream::n_columns; ++c)
+          if ((source_columns >> c) & 1U) {
+            const auto column = static_cast<obdeect::stream::Column>(c);
+            out[obdeect::stream::column_name(column)] = to_array(chunk[column]);
+          }
+        return out;
+      });
+}

obdeect_sources-0.8.0/cpp/include/obdeect/sources/background.hpp

@@ -0,0 +1,102 @@
+#pragma once
+
+// Night-sky background: photons start on the sphere of one telescope and travel inwards, with
+// directions uniform in solid angle inside a cone (docs/spec/background.md).
+
+#include "obdeect/sources/density.hpp"
+#include "obdeect/sources/source.hpp"
+#include "obdeect/sources/vec3.hpp"
+
+#include "obdeect/stream/photons.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstddef>
+#include <cstdint>
+#include <stdexcept>
+
+namespace obdeect::sources {
+
+struct BackgroundSource {
+  Vec3 centre{};
+  double radius_m{};
+  Vec3 pointing{0.0, 0.0, -1.0};
+  double viewcone_rad{pi / 2.0};
+  Spectrum spectrum{Fixed{400.0}};
+  double pulse_width_ns{};
+  double pulse_delay_ns{};
+};
+
+// Rotation about the y axis and about the z axis.
+inline Vec3 rotate_y(const Vec3 &v, double a) {
+  return {v.x * std::cos(a) + v.z * std::sin(a), v.y, v.z * std::cos(a) - v.x * std::sin(a)};
+}
+inline Vec3 rotate_z(const Vec3 &v, double a) {
+  return {v.x * std::cos(a) - v.y * std::sin(a), v.x * std::sin(a) + v.y * std::cos(a), v.z};
+}
+
+inline std::uint64_t background_count(double mean_bunches, std::uint64_t seed, std::uint32_t event,
+                                      std::uint32_t telescope) {
+  return round_count(mean_bunches, seed, event, telescope);
+}
+
+inline Photon sample_background(const BackgroundSource &s, std::uint64_t seed, std::uint32_t event,
+                                std::uint32_t telescope, std::uint64_t index) {
+  const Uniforms ud = philox_draw(seed, event, telescope, index, Stream::direction);
+  const Vec3 axis = normalised(s.pointing);
+  const Basis basis = orthonormal_basis(axis);
+  const double cos_theta = 1.0 - ud[0] * (1.0 - std::cos(s.viewcone_rad));
+  const double sin_theta = std::sqrt(std::max(0.0, (1.0 - cos_theta) * (1.0 + cos_theta)));
+  const Vec3 d = direction_about(axis, basis, cos_theta, sin_theta, two_pi * ud[1]);
+
+  const Uniforms ut = philox_draw(seed, event, telescope, index, Stream::target);
+  const double ri = 1.0 - std::sqrt(ut[0]);
+  const double phi = two_pi * ut[1];
+  const double zi = std::sqrt(std::max(0.0, 1.0 - ri * ri));
+  const Vec3 local{ri * std::cos(phi), ri * std::sin(phi), zi};
+  const double za = std::acos(std::clamp(-d.z, -1.0, 1.0));
+  const double az = std::atan2(-d.y, -d.x);
+  const Vec3 unit = rotate_z(rotate_y(local, za), az);
+
+  Photon p;
+  p.position = s.centre + unit * s.radius_m;
+  p.direction = d;
+  double jitter = 0.0;
+  if (s.pulse_width_ns > 0.0) {
+    const double u = philox_draw(seed, event, telescope, index, Stream::pulse)[0];
+    jitter = s.pulse_width_ns / fwhm_per_sigma * (u - 0.5);
+  }
+  p.time_ns = s.pulse_delay_ns - zi * s.radius_m / speed_of_light_m_per_ns + jitter;
+  p.wavelength_nm =
+      sample(s.spectrum, philox_draw(seed, event, telescope, index, Stream::wavelength));
+  p.weight = 1.0;
+  return p;
+}
+
+inline void emit_background(const BackgroundSource &s, std::uint64_t seed, std::uint32_t event,
+                            std::uint32_t telescope, std::uint64_t first, std::size_t rows,
+                            double weight, obdeect::stream::PhotonChunk &chunk) {
+  detail::require(s.radius_m > 0.0 && std::isfinite(s.radius_m), "background: radius must be > 0");
+  detail::require(s.viewcone_rad > 0.0 && s.viewcone_rad <= pi,
+                  "background: viewcone must lie in (0, pi]");
+  detail::require(rows <= obdeect::stream::max_chunk_rows, "a chunk holds at most 65536 rows");
+  chunk.resize(rows, source_columns);
+  chunk.telescope_id = telescope;
+  chunk.frame = obdeect::stream::Frame::sky;
+  chunk.first_index = first;
+  using obdeect::stream::Column;
+  for (std::size_t i = 0; i < rows; ++i) {
+    const Photon p = sample_background(s, seed, event, telescope, first + i);
+    chunk[Column::x][i] = static_cast<float>(p.position.x);
+    chunk[Column::y][i] = static_cast<float>(p.position.y);
+    chunk[Column::z][i] = static_cast<float>(p.position.z);
+    chunk[Column::cx][i] = static_cast<float>(p.direction.x);
+    chunk[Column::cy][i] = static_cast<float>(p.direction.y);
+    chunk[Column::cz][i] = static_cast<float>(p.direction.z);
+    chunk[Column::t][i] = static_cast<float>(p.time_ns);
+    chunk[Column::w][i] = static_cast<float>(weight);
+    chunk[Column::wavelength][i] = static_cast<float>(p.wavelength_nm);
+  }
+}
+
+} // namespace obdeect::sources

obdeect_sources-0.8.0/cpp/include/obdeect/sources/cli.hpp

@@ -0,0 +1,115 @@
+#pragma once
+
+// Option parsing shared by the sky tools (docs/spec/cli-conventions.md). Errors are
+// std::invalid_argument with the option name first.
+
+#include "obdeect/sources/vec3.hpp"
+
+#include <cctype>
+#include <cerrno>
+#include <cmath>
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace obdeect::sources::cli {
+
+// True when strtod consumes the whole text (so "4e2" and "-5" are numbers, "4e2x" is not).
+inline bool is_number(const std::string &text) {
+  if (text.empty())
+    return false;
+  char *end = nullptr;
+  (void)std::strtod(text.c_str(), &end);
+  return end != text.c_str() && *end == '\0';
+}
+
+// A finite real number; the whole text must be a number.
+inline double parse_number(const std::string &text, const std::string &option) {
+  if (!is_number(text))
+    throw std::invalid_argument(option + ": not a number: " + text);
+  errno = 0;
+  const double value = std::strtod(text.c_str(), nullptr);
+  if (errno == ERANGE || !std::isfinite(value))
+    throw std::invalid_argument(option + ": number out of range: " + text);
+  return value;
+}
+
+// A signed decimal integer (digits only).
+inline long long parse_integer(const std::string &text, const std::string &option) {
+  std::size_t i = (!text.empty() && (text[0] == '+' || text[0] == '-')) ? 1 : 0;
+  bool digits = i < text.size();
+  for (std::size_t k = i; k < text.size(); ++k)
+    digits = digits && std::isdigit(static_cast<unsigned char>(text[k]));
+  if (!digits)
+    throw std::invalid_argument(option + ": not an integer: " + text);
+  errno = 0;
+  const long long value = std::strtoll(text.c_str(), nullptr, 10);
+  if (errno == ERANGE)
+    throw std::invalid_argument(option + ": integer out of range: " + text);
+  return value;
+}
+
+inline double to_double(const std::string &text, const std::string &option) {
+  return parse_number(text, option);
+}
+
+// An event count: integer in 0..4294967295.
+inline std::uint32_t to_count(const std::string &text, const std::string &option) {
+  bool digits = !text.empty();
+  for (const char c : text)
+    digits = digits && std::isdigit(static_cast<unsigned char>(c));
+  errno = 0;
+  const unsigned long long value = digits ? std::strtoull(text.c_str(), nullptr, 10) : 0;
+  if (!digits || errno == ERANGE || value > std::numeric_limits<std::uint32_t>::max())
+    throw std::invalid_argument(option + ": must be an integer in 0..4294967295: " + text);
+  return static_cast<std::uint32_t>(value);
+}
+
+// Comma separated items (an empty item is an error).
+inline std::vector<std::string> split_items(const std::string &text, const std::string &option) {
+  std::vector<std::string> items;
+  std::size_t start = 0;
+  while (true) {
+    const std::size_t comma = text.find(',', start);
+    const std::string item = text.substr(start, comma == std::string::npos ? comma : comma - start);
+    if (item.empty())
+      throw std::invalid_argument(option + ": empty item in list: " + text);
+    items.push_back(item);
+    if (comma == std::string::npos)
+      break;
+    start = comma + 1;
+  }
+  return items;
+}
+
+inline std::vector<double> parse_list(const std::string &text, const std::string &option) {
+  std::vector<double> values;
+  for (const auto &item : split_items(text, option))
+    values.push_back(parse_number(item, option));
+  return values;
+}
+
+// "x,y,z" with exactly three items.
+inline Vec3 parse_vector(const std::string &text, const std::string &option) {
+  const auto items = split_items(text, option);
+  if (items.size() != 3)
+    throw std::invalid_argument(option + ": needs three comma-separated values");
+  return {parse_number(items[0], option), parse_number(items[1], option),
+          parse_number(items[2], option)};
+}
+
+inline std::string lower_case(std::string text) {
+  for (char &c : text)
+    c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
+  return text;
+}
+
+// True when `text` starts with `prefix`, ignoring case.
+inline bool starts_with_nocase(const std::string &text, const std::string &prefix) {
+  return text.size() >= prefix.size() && lower_case(text.substr(0, prefix.size())) == prefix;
+}
+
+} // namespace obdeect::sources::cli