# rust-spice
[![logo image]][repository link]
[![crate badge]][crate link]
[![doc badge]][doc link]
[![license badge]][license link]
[![pre-commit badge]][pre-commit link]
[![coverage doc badge]][coverage doc link]
[![coverage test badge]][coverage test link]
> **WOW! The complete NASA/NAIF Spice toolkit is actually usable on Rust**
---
[Intro](#intro) |
[Requirements](#requirements) |
[Usage](#usage) |
[In action](#in-action) |
[In development](#in-development) |
[Multi-threaded usage](#multi-threaded-usage) |
[Roadmap](#roadmap) |
[Contributors](#contributors) |
[License](#license)
---
## Intro
**SPICE** is *An Observation Geometry System for Space Science Missions*. Visit
their [website][naif link].
## Requirements
1) Install [CSPICE library][cspice install link] for your platform.
2) Set the environment variable `CSPICE_DIR` to your CSPICE installation folder
(where CSPICE subfolders `include` and `lib` are located. You can do that in the
[Cargo configuration][config doc]).
3) In the `cspice/lib` folder you might need for Unix systems to rename the
static library to match standards: `cspice.a` -> `libcspice.a`
See other requirements at [`cspice-sys`][cspice-sys link] library which provides
unsafe bindings to CSPICE.
## Usage
Add the dependency **rust-spice** to your `Cargo.toml`:
```toml
[dependencies]
rust-spice = "*" # replace * by the latest version of the crate
```
[`cspice-sys`][cspice-sys link] library depends on Clang which might not be
available to your system. In this case, you can use the feature `noclang`:
```toml
[dependencies]
rust-spice = {version = "*", default-features = false, features = ["noclang"] }
```
To enable the `lock` feature (see [## Multi-threaded usage](#multi-threaded-usage)).
```toml
[dependencies]
rust-spice = {version = "*", features = ["lock"] }
```
## In action
A nice and idiomatic interface to Spice,
```rust
use spice;
let mut kernel = spice::furnsh("/Users/gregoireh/data/spice-kernels/hera/kernels/mk/hera_study_PO_EMA_2024.tm");
let et = spice::str2et("2027-MAR-23 16:00:00");
let (position, light_time) = spice::spkpos("DIMORPHOS", et, "J2000", "NONE", "SUN");
// position -> 18.62640405424448, 21.054373008357004, -7.136291402940499
// light time -> 0.00009674257074746383
spice::kclear();
```
You can look for some inspirations in the [core tests][core tests link].
This dataset used as an example can be downloaded from
[here](https://s2e2.cosmos.esa.int/bitbucket/projects/SPICE_KERNELS/repos/hera/browse).
## In development
Developing an idiomatic interface for Spice in Rust takes time, and not all
functions are implemented yet. In the [documentation online][doc link], a
complete guide details which functions are available. If yours is not, you can
always use the unsafe API which contains all [cspice functions][cspice api].
For instance, with the unsafe API, the example above would be,
```rust
use spice;
use std::ffi::CString;
unsafe {
let kernel = CString::new("/Users/gregoireh/data/spice-kernels/hera/kernels/mk/hera_study_PO_EMA_2024.tm").unwrap().into_raw();
spice::c::furnsh_c(kernel);
let mut et = 0.0;
let date = CString::new("2027-MAR-23 16:00:00").unwrap().into_raw();
spice::c::str2et_c(date, &mut et);
let target_c = CString::new("DIMORPHOS").unwrap().into_raw();
let frame_c = CString::new("J2000").unwrap().into_raw();
let abcorr_c = CString::new("NONE").unwrap().into_raw();
let observer_c = CString::new("SUN").unwrap().into_raw();
let mut light_time = 0.0;
let mut position = [0.0, 0.0, 0.0];
spice::c::spkpos_c(
target_c,
et,
frame_c,
abcorr_c,
observer_c,
&mut position[0],
&mut light_time,
);
spice::c::kclear_c();
}
```
Much less friendly.. yet it is available. I would love some help in order to
complete the idiomatic development. You can raise an issue or propose a pull
request for the implementation of a specific function.
## Multi-threaded usage
CSPICE itself contains massive amounts of shared mutable state and is thus not thread-safe - concurrent
calls to any SPICE functions will almost always lead to crashes. To prevent this, if you need
to call SPICE functions from multiple threads, this crate provides a thread-safe API with the `lock`
feature. When enabled, the API is exposed in the form of associated functions on a guard singleton
`SpiceLock`, which is `!Sync + Send`. You can then only share this singleton and thus the methods it
provides between threads using a `Mutex`, preventing concurrent API usage.
The lock exposes the [neat][neat link] versions of functions where available, and the [raw][raw link] versions for the rest.
For functions which have neither, you will have to use the unsafe (and unguarded) direct C bindings.
Just make sure you have the lock before calling them.
```rust
# #[cfg(feature = "lock")]
# {
use spice::SpiceLock;
// `try_acquire` will return `Err` if a lock already exists
let sl = SpiceLock::try_acquire().unwrap();
// SPICE functions are now associated functions of the lock with a `&self` arg
let mut kernel = sl.furnsh("/Users/gregoireh/data/spice-kernels/hera/kernels/mk/hera_study_PO_EMA_2024.tm");
let et = sl.str2et("2027-MAR-23 16:00:00");
let (position, light_time) = sl.spkpos("DIMORPHOS", et, "J2000", "NONE", "SUN");
sl.kclear();
# }
```
## Roadmap
+ provide a packaging of the test assets
+ complete most-used API
+ complete whole API
+ refactoring of the procedural macros
+ refactoring of Cell
## Contributors
Hall of fame:
+ [@s-rah][s-rah url]: [#2][PR 2]
+ [@pixldemon][pixldemon url]: [#6][PR 6] [#10][PR 10]
A huge thanks for their contributions!!
## License
Licensed under the [Apache License, Version 2.0][license link].
[repository link]: https://github.com/GregoireHENRY/rust-spice
[logo image]: https://raw.githubusercontent.com/GregoireHENRY/rust-spice/main/rust-spice/rsc/img/logo_bg.png
[crate link]: https://crates.io/crates/rust-spice
[crate badge]: https://img.shields.io/crates/v/rust-spice.svg
[doc link]: https://docs.rs/rust-spice
[doc badge]: https://docs.rs/rust-spice/badge.svg
[license link]: https://raw.githubusercontent.com/GregoireHENRY/rust-spice/main/LICENSE
[license badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg
[pre-commit link]: https://pre-commit.com
[pre-commit badge]: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white
[coverage doc badge]: https://img.shields.io/badge/Documentation-100%25-brightgreen
[coverage doc link]: https://docs.rs/crate/rust-spice
[coverage test badge]: https://img.shields.io/badge/Tests-90%25-green
[coverage test link]: https://docs.rs/crate/rust-spice
[core tests link]: https://github.com/GregoireHENRY/rust-spice/tree/main/rust-spice/tests/core/mod.rs
[naif link]: https://naif.jpl.nasa.gov/naif
[cspice api]: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/index.html
[cspice install link]: https://naif.jpl.nasa.gov/naif/toolkit_C.html
[cspice-sys link]: https://github.com/jacob-pro/cspice-rs/tree/master/cspice-sys
[config doc]: https://doc.rust-lang.org/cargo/reference/config.html
[raw link]: https://docs.rs/rust-spice/latest/spice/core/raw/index.html
[neat link]: https://docs.rs/rust-spice/latest/spice/core/neat/index.html
[s-rah url]: https://github.com/s-rah
[pixldemon url]: https://github.com/pixldemon
[PR 2]: https://github.com/GregoireHENRY/rust-spice/pull/2
[PR 6]: https://github.com/GregoireHENRY/rust-spice/pull/6
[PR 10]: https://github.com/GregoireHENRY/rust-spice/pull/10