doc updates

CHANGELOG.md

@@ -56,15 +56,25 @@ Changes expected for the next feature release, expected around 1 February 2025.
    You can also set other standard directory variables, as prescribed in the 
    [GNU standard](https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) to further customize the
    install locations.
-
- - SuperNOVAS headers now include each other as system-headers, not local headers. This is unlikely to affect anything
-   really but it is more proper for an installation of the library, and works with our own `Makefile` too.
+
+ - #95: Added support for using orbital elements. `object.type` can now be set to `NOVAS_ORBITAL_OBJECT`, whose orbit
+   can be defined by the set of `novas_orbital_elements`, within a `novas_orbital_system`. You can initialize an 
+   `object` with a set of orbital elements using `make_orbital_object()`. For such objects, `ephemeris()` will now 
+   call on the new `novas_orbit_posvel()` to calculate positions. While orbital elements do not always yield precise 
+   positions, they can for shorter periods, provided that the orbital elements are up-to-date. For example, the Minor 
+   Planer Center (MPC) publishes orbital elements for all known asteroids and comets regularly. For newly discovered 
+   objects, this may be the only and/or most accurate information available anywhere.
 
  - #97: Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish
    from the planet center in calculations.
 
+ - SuperNOVAS headers now include each other as system-headers, not local headers. This is unlikely to affect anything
+   really but it is more proper for an installation of the library, and works with our own `Makefile` too.
+
 ### Changed
 
+ - #96: Changed `object` structure to include `novas_orbital_elements` for `NOVAS_ORBITAL_OBJECT` types.
+
  - #97: Updated `NOVAS_PLANETS`, `NOVAS_PLANET_NAMES_INIT` and `NOVAS_RMASS_INIT` macros to include the added planet 
    constants.
 

README.md

@@ -596,6 +596,24 @@ more generic ephemeris handling via a user-provided `novas_ephem_provider`. E.g.
  make_ephem_object("Ceres", 2000001, &ceres);
 ```
 
+As of version 1.2 you can also define solar system sources with orbital elements (such as the most up-to-date ones 
+provided by the [Minor Planet Center](https://minorplanetcenter.net/data) for asteroids, comets, etc.):
+
+```c
+  object NEA;		// e.g. a Near-Earth Asteroid
+
+  // Fill in the orbital parameters (pay attention to units!)
+  novas_orbital_elements orbit = NOVAS_ORBIT_INIT;
+  orbit.a = ...;
+  ...
+
+  // Create an object for that orbit
+  make_orbital_object("NEAxxx", -1, &orbit, object);
+```
+
+Note, that even with orbital elements, you will, in general, require a planet calculator, to provide precise
+positions for the Sun or planet, around which the orbit is defined.
+
 Other than that, it's the same spiel as before, e.g.:
 
 ```c
@@ -894,6 +912,14 @@ before that level of accuracy is reached.
 
  - Added `novas_planet_for_name()` function to return the NOVAS planet ID for a given (case insensitive) name.
 
+ - Added support for using orbital elements. `object.type` can now be set to `NOVAS_ORBITAL_OBJECT`, whose orbit
+   can be defined by the set of `novas_orbital_elements`, within a `novas_orbital_system`. You can initialize an 
+   `object` with a set of orbital elements using `make_orbital_object()`. For such objects, `ephemeris()` will now 
+   call on the new `novas_orbit_posvel()` to calculate positions. While orbital elements do not always yield precise 
+   positions, they can for shorter periods, provided that the orbital elements are up-to-date. For example, the Minor 
+   Planer Center (MPC) publishes orbital elements for all known asteroids and comets regularly. For newly discovered 
+   objects, this may be the only and/or most accurate information available anywhere.
+
  - Added `NOVAS_EMB` (Earth-Moon Barycenter) and `NOVAS_PLUTO_BARYCENTER` to `enum novas_planets` to distinguish
    from the corresponding planet centers in calculations.
 

include/novas.h

@@ -640,31 +640,32 @@ typedef struct {
 
 /**
  * Specification of an orbital system, in which orbital elements are defined. Systems can be defined around
- * all major planets (and Sun, Moon, SSB). They may be referenced to the GCRS, mean, or true equator or ecliptic
- * of date, or to a plane that is tilted relative to that.
+ * all major planets and barycenters (and Sun, Moon, SSB..). They may be referenced to the GCRS, mean, or true equator
+ * or ecliptic of date, or to a plane that is tilted relative to that.
  *
  * For example, The Minor Planet Center (MPC) publishes up-to-date orbital elements for asteroids and comets,
  * which are heliocentric and referenced to the GCRS ecliptic. Hence 'center' for these is `NOVAS_SUN`, the `plane`
  * is `NOVAS_ECLIPTIC_PLANE` and the `type` is `NOVAS_GCRS_EQUATOR`.
  *
  * The orbits of planetary satellites may be parametrized in their local Laplace planes, which are typically close
  * to the host planet's equatorial planes. You can, for example, obtain the RA/Dec orientation of the planetary
- * North poles of planets from JPL Horizons, and use them as a proxy for the Laplace planes of their satellite orbits.
+ * North poles of planets from JPL Horizons, and use them as a proxy for the Laplace planes for their satellite orbits.
  * In this case you would set the `center` to the host planet (e.g. `NOVAS_SATURN`), the reference plane to
- * `NOVAS_EQUATORIAL_PLANE` and the `type` to `NOVAS_GCRS_EQUATOR` (since the equator's orientation is defined in
- * GCRS equatorial RA/Dec). The obliquity is then 90° - Dec (in radians), and `phi` is RA (in radians).
+ * `NOVAS_EQUATORIAL_PLANE` and the `type` to `NOVAS_GCRS_EQUATOR` (since the plane is defined by the North pole
+ * orientation in GCRS equatorial RA/Dec). The obliquity is then 90&deg; - Dec<sub>pole</sub> (in radians), and `phi`
+ * is RA<sub>pole</sub> (in radians).
  *
  * @author Attila Kovacs
  * @since 1.2
  *
  * @sa novas_orbital_elements
  */
 typedef struct {
-  enum novas_planet center;          ///< major body at the center of the orbit (default is NOVAS_SUN).
+  enum novas_planet center;          ///< major planet or barycenter at the center of the orbit (default is NOVAS_SUN).
   enum novas_reference_plane plane;  ///< reference plane NOVAS_ECLIPTIC_PLANE (default) or NOVAS_EQUATORIAL_PLANE
   enum novas_equator_type type;      ///< the type of equator in which orientation is referenced (true, mean, or GCRS [default]).
-  double obl;                        ///< [rad] obliquity of orbital reference plane (e.g. 90&deg; - Dec<sub>pole</sub>)
-  double Omega;                      ///< [rad] argument of ascending node of the orbital reference plane (e.g. RA<sub>pole</sub>)
+  double obl;                        ///< [rad] relative obliquity of orbital reference plane (e.g. 90&deg; - Dec<sub>pole</sub>)
+  double Omega;                      ///< [rad] relative argument of ascending node of the orbital reference plane (e.g. RA<sub>pole</sub>)
 } novas_orbital_system;
 
 
@@ -702,8 +703,8 @@ typedef struct {
  * @sa enum NOVAS_ORBITAL_OBJECT
  */
 typedef struct {
-  novas_orbital_system system;      ///< orbital reference system assumed for the paramtetrization
-  double jd_tdb;                    ///< [day] Barycentri Dynamical Time (TDB) based Julian date of parameters.
+  novas_orbital_system system;      ///< orbital reference system assumed for the parametrization
+  double jd_tdb;                    ///< [day] Barycentri Dynamical Time (TDB) based Julian date of the parameters.
   double a;                         ///< [AU] semi-major axis
   double e;                         ///< eccentricity
   double omega;                     ///< [rad] argument of periapsis / perihelion
@@ -714,7 +715,7 @@ typedef struct {
 } novas_orbital_elements;
 
 /**
- * Initializer for novas_orbital_elements for heliocentric orbits
+ * Initializer for novas_orbital_elements for heliocentric orbits using GCRS ecliptic pqrametrization.
  *
  * @author Attila Kovacs
  * @since 1.2