siderust-cpp

Modern, header-only C++17 wrapper for siderust — a high-precision astronomical computation library written in Rust.

siderust-cpp provides idiomatic C++ types (RAII, exceptions, value semantics) on top of the C FFI layer generated by siderust-ffi and tempoch-ffi.

Features

Module	What you get
Time (time.hpp)	JulianDate, MJD, UTC, Period — value types with arithmetic and UTC round-trips
Coordinates (coordinates.hpp)	Modular typed API (coordinates/{geodetic,spherical,cartesian,types}.hpp) plus selective alias headers under coordinates/types/{spherical,cartesian}/...
Frames & Centers (frames.hpp, centers.hpp)	Compile-time frame/center tags and transform capability traits
Bodies (bodies.hpp)	Star (RAII, catalog + custom), Planet (8 planets), ProperMotion, Orbit
Observatories (observatories.hpp)	Named sites: Roque de los Muchachos, Paranal, Mauna Kea, La Silla
Altitude (altitude.hpp)	Sun / Moon / Star / ICRS altitude: instant, above/below threshold, crossings, culminations
Azimuth (azimuth.hpp)	Sun / Moon / Star / ICRS azimuth: instant, crossings, extrema, range windows
Targets (trackable.hpp, target.hpp, body_target.hpp, star_target.hpp)	Polymorphic tracking with Trackable, Target, BodyTarget, and StarTarget
Lunar Phase (lunar_phase.hpp)	Phase geometry/labels, principal phase events, illumination window search
Ephemeris (ephemeris.hpp)	VSOP87 Sun/Earth positions, ELP2000 Moon position

Quick Start

#include <siderust/siderust.hpp>
#include <iostream>

int main() {
    using namespace siderust;

    auto obs  = ROQUE_DE_LOS_MUCHACHOS;
    auto jd   = JulianDate::from_utc({2026, 7, 15, 22, 0, 0});
    auto mjd  = MJD::from_jd(jd);
    auto win  = Period(mjd, mjd + qtty::Day(1.0));

    qtty::Degree sun_alt = sun::altitude_at(obs, mjd).to<qtty::Degree>();
    qtty::Degree sun_az  = sun::azimuth_at(obs, mjd);
    std::cout << "Sun alt=" << sun_alt.value() << " deg"
              << " az=" << sun_az.value() << " deg\n";

    Target fixed(279.23473, 38.78369); // Vega-like ICRS target
    std::cout << "Target alt=" << fixed.altitude_at(obs, mjd).value() << " deg\n";

    auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
    std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";

    return 0;
}

Building

# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp

# Build
mkdir build && cd build
cmake ..
cmake --build .

# Run example
./siderust_demo
./coordinates_examples
./coordinate_systems_example
./solar_system_bodies_example
./altitude_events_example
./trackable_targets_example
./azimuth_lunar_phase_example

# Run tests
ctest --output-on-failure

Docker

The repository includes a root Dockerfile that installs all build dependencies (CMake, Rust, Doxygen), then runs configure/build/tests/docs during image build.

# Clone with submodules
git clone --recurse-submodules <url>
cd siderust-cpp

# Build image (validates build + tests + docs)
docker build -t siderust-cpp:dev .

# Open an interactive shell in the container
docker run --rm -it -v "$PWD":/workspace -w /workspace siderust-cpp:dev

Note: docker build writes generated docs inside the image layer, not your host filesystem.

To generate docs on the host, run the docs target in a bind-mounted container:

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$PWD":/workspace \
  -w /workspace \
  siderust-cpp:dev \
  bash -lc 'cmake -S . -B build -G Ninja && cmake --build build --target docs'

Generated HTML entry point on host:

• build/docs/doxygen/html/index.html

Generated HTML entry point inside container:

• /workspace/build/docs/doxygen/html/index.html

API Documentation (Doxygen)

If Doxygen is installed, CMake exposes a docs target:

cmake -S . -B build
cmake --build build --target docs

Generated HTML entry point:

• build/docs/doxygen/html/index.html

Prerequisites

• C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)
• CMake 3.15+
• Rust toolchain (cargo) — Rust FFI libraries are built automatically
• Internet connection for Google Test (fetched automatically)

Project Layout

siderust-cpp/
├── CMakeLists.txt
├── docs/
│   ├── Doxyfile.in
│   └── mainpage.md
├── cmake/
│   └── siderust_cppConfig.cmake.in
├── include/siderust/
│   ├── siderust.hpp          ← umbrella header
│   ├── ffi_core.hpp          ← error handling, enums
│   ├── time.hpp              ← JulianDate, MJD, Period, UTC
│   ├── coordinates.hpp       ← coordinate umbrella header
│   ├── coordinates/
│   │   ├── geodetic.hpp
│   │   ├── spherical.hpp
│   │   ├── cartesian.hpp
│   │   ├── types.hpp
│   │   └── conversions.hpp
│   ├── bodies.hpp            ← Star, Planet, ProperMotion
│   ├── observatories.hpp     ← named observatory locations
│   ├── altitude.hpp          ← sun/moon/star altitude API
│   ├── azimuth.hpp           ← azimuth queries and events
│   ├── lunar_phase.hpp       ← moon phase geometry and events
│   ├── trackable.hpp         ← polymorphic trackable interface
│   ├── target.hpp            ← fixed ICRS target (RAII)
│   ├── body_target.hpp       ← body enum trackable adapter
│   ├── star_target.hpp       ← star trackable adapter
│   └── ephemeris.hpp         ← VSOP87/ELP2000 positions
├── examples/demo.cpp
├── tests/
│   ├── main.cpp
│   ├── test_time.cpp
│   ├── test_observatories.cpp
│   ├── test_coordinates.cpp
│   ├── test_bodies.cpp
│   ├── test_altitude.cpp
│   └── test_ephemeris.cpp
├── siderust-ffi/             ← git submodule (contains `siderust` as nested submodule)
└── qtty-cpp/                 ← git submodule

Architecture

┌──────────────┐
│  C++ user    │   #include <siderust/siderust.hpp>
│  code        │
└──────┬───────┘
       │  header-only (inline)
┌──────▼───────┐
│ siderust-cpp │   C++17 types, RAII, exceptions
│ (headers)    │
└──────┬───────┘
       │  extern "C" calls
┌──────▼───────┐  ┌──────────────┐
│ siderust-ffi │──│ tempoch-ffi  │   C ABI (cbindgen-generated)
│ (.so/.dylib) │  │ (.so/.dylib) │
└──────┬───────┘  └──────┬───────┘
       │                 │
┌──────▼─────────────────▼──┐
│       siderust (Rust)     │
│  coordinates · altitude   │
│  bodies · ephemeris       │
│  tempoch · affn · qtty    │
└───────────────────────────┘

License

Same license as siderust. See LICENSE.