Add azimuth and lunar phase computations, enhance target handling

.clang-format

@@ -1,10 +1,13 @@
 ---
+Language: Cpp
 BasedOnStyle: LLVM
-IndentWidth: 4
-ContinuationIndentWidth: 4
-ColumnLimit: 0
-PointerAlignment: Left
-ReferenceAlignment: Left
-AlignConsecutiveAssignments: Consecutive
-AlignConsecutiveDeclarations: Consecutive
-...
+IndentWidth: 2
+ColumnLimit: 80
+AllowShortBlocksOnASingleLine: Never
+AllowShortFunctionsOnASingleLine: All
+AllowShortEnumsOnASingleLine: true
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortLambdasOnASingleLine: All
+AlwaysBreakTemplateDeclarations: MultiLine
+

.gitignore

@@ -2,9 +2,9 @@
 build/
 cmake-build-*/
 out/
-build-make/
-build-verify/
-build-ci-config-check/
+build-*
+coverage_html/
+coverage.xml
 
 # IDE files
 .vscode/

CMakeLists.txt

@@ -47,11 +47,14 @@ endif()
 # Build siderust-ffi (depends on tempoch-ffi via tempoch-cpp subdirectory)
 add_custom_target(
     build_siderust_ffi
-    COMMAND ${CARGO_BIN} build --release ${_SIDERUST_FEATURES_ARGS}
+    # Use `cargo rustc --crate-type cdylib` so that the shared library is
+    # produced even though Cargo.toml only lists rlib (which keeps coverage
+    # instrumentation clean during `cargo test`/`cargo llvm-cov`).
+    COMMAND ${CARGO_BIN} rustc --release --crate-type cdylib ${_SIDERUST_FEATURES_ARGS}
     WORKING_DIRECTORY ${SIDERUST_FFI_DIR}
     BYPRODUCTS ${SIDERUST_LIBRARY_PATH}
     DEPENDS build_tempoch_ffi
-    COMMENT "Building siderust-ffi via Cargo"
+    COMMENT "Building siderust-ffi via Cargo (cdylib override)"
     VERBATIM
 )
 
@@ -101,23 +104,27 @@ if(SIDERUST_BUILD_DOCS)
         set(SIDERUST_DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.siderust_cpp)
         configure_file(${SIDERUST_DOXYFILE_IN} ${SIDERUST_DOXYFILE_OUT} @ONLY)
 
-        add_custom_target(docs
-            COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen
-            COMMAND ${DOXYGEN_EXECUTABLE} ${SIDERUST_DOXYFILE_OUT}
-            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-            COMMENT "Generating API documentation with Doxygen"
-            VERBATIM
-        )
+        if(NOT TARGET docs)
+            add_custom_target(docs
+                COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen
+                COMMAND ${DOXYGEN_EXECUTABLE} ${SIDERUST_DOXYFILE_OUT}
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                COMMENT "Generating API documentation with Doxygen"
+                VERBATIM
+            )
+        else()
+            message(STATUS "Top-level 'docs' target already exists; skipping creation to avoid conflict with subprojects")
+        endif()
     else()
         message(STATUS "Doxygen not found; 'docs' target will not be available")
     endif()
 endif()
 
 # RPATH for shared library lookup at runtime
 if(APPLE)
-    set(_siderust_rpath "@loader_path/../siderust/target/release;@loader_path/../tempoch-cpp/tempoch/tempoch-ffi/target/release;@loader_path/../qtty-cpp/qtty/target/release")
+    set(_siderust_rpath "@loader_path/../siderust/siderust-ffi/target/release;@loader_path/../tempoch-cpp/tempoch/tempoch-ffi/target/release;@loader_path/../qtty-cpp/qtty/target/release")
 elseif(UNIX)
-    set(_siderust_rpath "$ORIGIN/../siderust/target/release:$ORIGIN/../tempoch-cpp/tempoch/tempoch-ffi/target/release:$ORIGIN/../qtty-cpp/qtty/target/release")
+    set(_siderust_rpath "$ORIGIN/../siderust/siderust-ffi/target/release:$ORIGIN/../tempoch-cpp/tempoch/tempoch-ffi/target/release:$ORIGIN/../qtty-cpp/qtty/target/release")
 endif()
 
 # ---------------------------------------------------------------------------
@@ -135,52 +142,35 @@ FetchContent_MakeAvailable(googletest)
 enable_testing()
 
 # ---------------------------------------------------------------------------
-# Example
+# Example helper: add an example only if its source file exists.
 # ---------------------------------------------------------------------------
-add_executable(siderust_demo examples/demo.cpp)
-target_link_libraries(siderust_demo PRIVATE siderust_cpp)
-if(DEFINED _siderust_rpath)
-    set_target_properties(siderust_demo PROPERTIES
-        BUILD_RPATH ${_siderust_rpath}
-        INSTALL_RPATH ${_siderust_rpath}
-    )
-endif()
-
-add_executable(coordinates_examples examples/coordinates_examples.cpp)
-target_link_libraries(coordinates_examples PRIVATE siderust_cpp)
-if(DEFINED _siderust_rpath)
-    set_target_properties(coordinates_examples PROPERTIES
-        BUILD_RPATH ${_siderust_rpath}
-        INSTALL_RPATH ${_siderust_rpath}
-    )
-endif()
-
-add_executable(coordinate_systems_example examples/coordinate_systems_example.cpp)
-target_link_libraries(coordinate_systems_example PRIVATE siderust_cpp)
-if(DEFINED _siderust_rpath)
-    set_target_properties(coordinate_systems_example PROPERTIES
-        BUILD_RPATH ${_siderust_rpath}
-        INSTALL_RPATH ${_siderust_rpath}
-    )
-endif()
+macro(siderust_add_example target_name source_file)
+    if(EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source_file}")
+        add_executable(${target_name} ${source_file})
+        target_link_libraries(${target_name} PRIVATE siderust_cpp)
+        if(DEFINED _siderust_rpath)
+            set_target_properties(${target_name} PROPERTIES
+                BUILD_RPATH ${_siderust_rpath}
+                INSTALL_RPATH ${_siderust_rpath}
+            )
+        endif()
+    endif()
+endmacro()
 
-add_executable(solar_system_bodies_example examples/solar_system_bodies_example.cpp)
-target_link_libraries(solar_system_bodies_example PRIVATE siderust_cpp)
-if(DEFINED _siderust_rpath)
-    set_target_properties(solar_system_bodies_example PROPERTIES
-        BUILD_RPATH ${_siderust_rpath}
-        INSTALL_RPATH ${_siderust_rpath}
-    )
-endif()
+# ---------------------------------------------------------------------------
+# Examples
+# ---------------------------------------------------------------------------
 
-add_executable(altitude_events_example examples/altitude_events_example.cpp)
-target_link_libraries(altitude_events_example PRIVATE siderust_cpp)
-if(DEFINED _siderust_rpath)
-    set_target_properties(altitude_events_example PROPERTIES
-        BUILD_RPATH ${_siderust_rpath}
-        INSTALL_RPATH ${_siderust_rpath}
-    )
-endif()
+# Numbered mirror examples (03–21, mirroring siderust Rust examples)
+siderust_add_example(03_all_frame_conversions_example   examples/03_all_frames_conversions.cpp)
+siderust_add_example(04_all_center_conversions_example  examples/04_all_center_conversions.cpp)
+siderust_add_example(05_target_tracking_example         examples/05_target_tracking.cpp)
+siderust_add_example(06_night_events_example            examples/06_night_events.cpp)
+siderust_add_example(07_moon_properties_example         examples/07_moon_properties.cpp)
+siderust_add_example(08_solar_system_example            examples/08_solar_system.cpp)
+siderust_add_example(09_star_observability_example      examples/09_star_observability.cpp)
+siderust_add_example(10_time_periods_example            examples/10_time_periods.cpp)
+siderust_add_example(11_serde_serialization_example     examples/11_serde_serialization.cpp)
 
 # ---------------------------------------------------------------------------
 # Tests
@@ -193,6 +183,8 @@ set(TEST_SOURCES
     tests/test_bodies.cpp
     tests/test_altitude.cpp
     tests/test_ephemeris.cpp
+    tests/test_bodycentric.cpp
+    tests/test_subject.cpp
 )
 
 add_executable(test_siderust ${TEST_SOURCES})

Dockerfile

@@ -17,6 +17,10 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     pkg-config \
     libssl-dev \
     graphviz \
+    rsync \
+    clang-format \
+    clang-tidy \
+    gcovr \
     && rm -rf /var/lib/apt/lists/*
 
 RUN curl -fsSL "https://github.com/doxygen/doxygen/releases/download/Release_1_16_1/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz" -o /tmp/doxygen.tar.gz && \

README.md

@@ -10,38 +10,39 @@ Modern, header-only C++17 wrapper for **siderust** — a high-precision astronom
 |--------|-------------|
 | **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
 
 ```cpp
 #include <siderust/siderust.hpp>
-#include <cstdio>
+#include <iostream>
 
 int main() {
     using namespace siderust;
-    using namespace qtty::literals;
 
     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));
 
-    // Sun altitude
-    qtty::Radian alt = sun::altitude_at(obs, mjd);
-    std::printf("Sun altitude: %.4f rad\n", alt.value());
+    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";
 
-    // Star from catalog
-    const auto& vega = VEGA;
-    qtty::Radian star_alt = star_altitude::altitude_at(vega, obs, mjd);
-    std::printf("Vega altitude: %.4f rad\n", star_alt.value());
+    Target fixed(279.23473, 38.78369); // Vega-like ICRS target
+    std::cout << "Target alt=" << fixed.altitude_at(obs, mjd).value() << " deg\n";
 
-    // Night periods (astronomical twilight)
-    auto nights = sun::below_threshold(obs, mjd, mjd + 1.0, -18.0_deg);
-    for (auto& p : nights)
-        std::printf("Night: MJD %.4f – %.4f\n", p.start_mjd(), p.end_mjd());
+    auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
+    std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";
 
     return 0;
 }
@@ -65,6 +66,8 @@ cmake --build .
 ./coordinate_systems_example
 ./solar_system_bodies_example
 ./altitude_events_example
+./trackable_targets_example
+./azimuth_lunar_phase_example
 
 # Run tests
 ctest --output-on-failure
@@ -153,6 +156,12 @@ siderust-cpp/
 │   ├── 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/

docs/mainpage.md

@@ -21,6 +21,9 @@ codebase without writing a single line of Rust.
 | **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 target tracking across bodies, stars, and fixed ICRS directions |
+| **Lunar Phase** (`lunar_phase.hpp`) | Moon phase geometry, labels, principal phase events, illumination windows |
 | **Ephemeris** (`ephemeris.hpp`) | VSOP87 Sun/Earth positions, ELP2000 Moon position |
 
 ---
@@ -29,29 +32,27 @@ codebase without writing a single line of Rust.
 
 ```cpp
 #include <siderust/siderust.hpp>
-#include <cstdio>
+#include <iostream>
+#include <iomanip>
 
 int main() {
     using namespace siderust;
-    using namespace qtty::literals;
 
     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));
 
-    // Sun altitude at the observatory
-    qtty::Radian alt = sun::altitude_at(obs, mjd);
-    std::printf("Sun altitude: %.4f rad\n", alt.value());
+    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";
 
-    // Star from built-in catalog
-    const auto& vega    = VEGA;
-    qtty::Radian star_alt = star_altitude::altitude_at(vega, obs, mjd);
-    std::printf("Vega altitude: %.4f rad\n", star_alt.value());
+    Target fixed(279.23473, 38.78369); // Vega-like fixed ICRS target
+    std::cout << "Target alt=" << fixed.altitude_at(obs, mjd).value() << " deg\n";
 
-    // Astronomical night periods (twilight < -18°)
-    auto nights = sun::below_threshold(obs, mjd, mjd + 1.0, -18.0_deg);
-    for (auto& p : nights)
-        std::printf("Night: MJD %.4f – %.4f\n", p.start_mjd(), p.end_mjd());
+    auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
+    std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";
 
     return 0;
 }
@@ -112,6 +113,8 @@ cmake --build .
 ./coordinate_systems_example
 ./solar_system_bodies_example
 ./altitude_events_example
+./trackable_targets_example
+./azimuth_lunar_phase_example
 
 # Run tests
 ctest --output-on-failure
@@ -130,6 +133,9 @@ ctest --output-on-failure
 - `siderust/bodies.hpp` — `Star`, `Planet`, and orbital / proper-motion types
 - `siderust/observatories.hpp` — known observatory locations and custom geodetic points
 - `siderust/altitude.hpp` — Sun / Moon / Star altitude queries and event search
+- `siderust/azimuth.hpp` — azimuth queries, crossings, extrema, and azimuth ranges
+- `siderust/trackable.hpp`, `siderust/target.hpp`, `siderust/body_target.hpp`, `siderust/star_target.hpp` — target abstractions and polymorphic tracking
+- `siderust/lunar_phase.hpp` — moon phase geometry, labels, phase events, illumination windows
 - `siderust/ephemeris.hpp` — VSOP87 / ELP2000 position queries
 
 ---