API¶

namespace SpiceQL¶

types

Typedefs

typedef std::shared_ptr<Kernel> SharedKernel¶

typedef of std::shared_ptr<Kernel>

This basically allows the Kernel to exist as a reference counted variable. Once all references to the Kernel cease to exist, the kernel is unloaded.

typedef std::unique_ptr<Kernel> StackKernel¶

typedef of std::unique_ptr<Kernel>

This basically allows the Kernel to exist only within the call stack it is used in.

Functions

std::vector<std::vector<double>> concatStates(std::vector<std::vector<double>> statePositions, std::vector<std::vector<double>> stateVelocities)¶

Combine the state positions and velocities into a single vector

Returns: Single vector with {X1, Y1, Z1, dX1, dY1, dZ1, X2, Y2, Z2, dX2, dY2, dZ2, …}

void writeSpk(std::string fileName, std::vector<SpkSegment> segments)¶

Write SPK segments to a file.

Given a vector of SPK segments, write them to the requested SPK file.

Parameters

fileName – file specification to have the SPK segments written to
segments – spkSegments to be written

void writeSpk(std::string fileName, std::vector<std::vector<double>> statePositions, std::vector<double> stateTimes, int bodyCode, int centerOfMotion, std::string referenceFrame, std::string segmentId, int polyDegree, std::optional<std::vector<std::vector<double>>> stateVelocities = std::nullopt, std::optional<std::string> segmentComment = std::nullopt)¶

Write SPK to path.

Parameters

fileName – full path to file to write the segment to
statePositions – Nx3 array of positions in X,Y,Z order
stateTimes – Nx1 array of times
bodyCode – NAIF integer code for the body the states belong to
centerOfMotion – is the NAIF integer code for the center of motion of the object identified by body.
referenceFrame – The NAIF code the states are relative to
segmentId – ID for the segment
polyDegree – degree of the hermite polynomials used for interpolation
stateVelocities – Nx3 array of state velocities in VX, VY, VZ order, optional
segmentComment – Comment associated with the segment, optional

void writeCk(std::string fileName, std::vector<std::vector<double>> quats, std::vector<double> times, int bodyCode, std::string referenceFrame, std::string segmentId, std::string sclk, std::string lsk, std::optional<std::vector<std::vector<double>>> angularVelocity = std::nullopt, std::optional<std::string> comment = std::nullopt)¶

Write CK segments to a file.

Given orientations, angular velocities, times, target and reference frames, write data as a segment in a CK kernel.

Parameters

fileName – path to file to write the segment to
quats – nx4 vector of orientations as quaternions
times – nx1 vector of times matching the number of quats
bodyCode – NAIF body code identifying the orientations belong to
referenceFrame – NAIF string for the reference frame the orientations are in
segmentId – Some ID to give the segment
sclk – path to S clock kernal to convert to and from ephemeris time
lsk – path to leap second kernal
angularVelocity – optional, nx3 array of angular velocities
comment – optional, comment to be associated with the segment

void writeCk(std::string fileName, std::string sclk, std::string lsk, std::vector<CkSegment> segments)¶

Write CK segments to a file.

Given orientations, angular velocities, times, target and reference frames, write data as a segment in a CK kernel.

Parameters

fileName – path to file to write the segment to
sclk – path to SCLK kernel matching the segments’ frame code
lsk – path to LSK kernel
segments – spkSegments to be writte

void writeTextKernel(std::string fileName, std::string type, nlohmann::json &keywords, std::optional<std::string> comment = std::nullopt)¶

Write json key value pairs into a NAIF text kernel.

Parameters

fileName – pull path to the text kernel
type – kernel type string, valid text kernel types: FK, IK, LSK, MK, PCK, SCLK
comment – the comment to add to the top of the kernel
keywords – json object containing key/value pairs to write to the text kernel

std::string getLatestKernel(std::vector<std::string> kernels)¶

get the latest kernel in a list

Returns the kernel with the latest version string (e.g. the highest v??? or similar sub-string in a kernel path name) in the input list and returns it as a path object.

Parameters: kernels – vector of strings, should be a list of kernel paths.
Returns: path object to latest Kernel

nlohmann::json getLatestKernels(nlohmann::json kernels)¶

returns a JSON object of only the latest version of each kernel type

Recursively iterates Kernel groups in the input JSON and gets the kernels with the latest version string (e.g. the highest v??? sub-string in a kernel path name).

New JSON is returned.

Parameters: kernels – A Kernel JSON object
Returns: A new Kernel JSON object with reduced kernel sets

std::vector<std::string> getKernelVectorValue(std::string key)¶

return’s kernel values in the form of a vector

Takes in a kernel key and returns the value associated with that kernel as a vector of string Note: This function is for when the kernel has more than 1 value associated with it, ie: INS-236800_FOV_REF_VECTOR = ( 1.0, 0.0, 0.0 )

Parameters: key – key - Kernel to get values from
Returns: vector of values in the form of a string

std::string getKernelStringValue(std::string key)¶

return’s kernel value from key

Takes in a kernel key and returns the value associated with that kernel as a string Note: this function is for when the kernal has a single value associated with it, ie: INS-236800_FOV_REF_ANGLE = ( 5.27 )

Parameters: key – key - Kernel to get values from
Returns: string of value associated with key

nlohmann::json searchMissionKernels(std::string root, nlohmann::json conf)¶

Returns all kernels available for a mission.

Returns a structured json object containing all available kernels for a specified mission along with their dependencies.

TODO: Add a “See Also” on json format after the format matures a bit more.

Parameters

root – root path to search
conf – json conf file

Returns

list of paths matching ext

nlohmann::json searchMissionKernels(nlohmann::json conf)¶

Returns all kernels available for a mission.

Returns a structured json object containing all available kernels for a specified mission along with their dependencies.

TODO: Add a “See Also” on json format after the format matures a bit more.

Parameters: conf – json conf file
Returns: list of paths matching ext

nlohmann::json searchMissionKernels(nlohmann::json kernels, std::vector<double> times, bool isContiguous = false)¶

Returns all kernels available in the time range.

Returns a structured json object containing all available kernels for a specified time range along with their dependencies.

TODO: Add a “See Also” on json format after the format matures a bit more.

Parameters

kernels – kernels to search
times – vector of times to match
isContiguous – if true, all times need to be in the kernel to match the query, else, any kernel that is in any of the times inputed get returned

Returns

json object with new kernels

nlohmann::json globKernels(std::string root, nlohmann::json conf, std::string kernelType)¶

acquire all kernels of a type according to a configuration JSON object

Given the root directotry with kernels, a JSON configuration object and a kernel type string (e.g. ck, fk, spk), return a JSON object containing kernels. The kernel config’s regular expressions are replaced by a concrete kernel list located in the passed in root.

Parameters

root – Directory with kernels somewhere in the directory or its subdirectories
conf – JSON config file, usually this is a JSON object read from one of the db files that shipped with the library
kernelType – Some CK kernel type, see Kernel::TYPES

std::vector<std::string> getKernelList(nlohmann::json kernels)¶

Get all the kernels in the json as a vector.

Recusively iterates all the kernel keys and flattens them in a vector.

Parameters: kernels – json object with kernel query results
Returns: vector<string> list of kernels

std::set<std::string> getKernelSet(nlohmann::json kernels)¶

Get all the kernels in the json as a set.

Recusively iterates all the kernel keys and flattens them in a vector.

Parameters: kernels – json object with kernel query results
Returns: set<string> set of kernels

double utcToEt(std::string et)¶

convert a UTC string to an ephemeris time

Basically a wrapper around NAIF’s cspice str2et function except it also temporarily loads the required kernels. See Also: https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/str2et_c.html

Parameters: et – UTC string, e.g. “1988 June 13, 12:29:48 TDB”
Returns: double precision ephemeris time

double sclkToEt(std::string mission, std::string sclk)¶

Parameters

mission –
sclk –

Returns

double

std::string toUpper(std::string s)¶

force a string to upper case

Parameters: s – input string
Returns: copy of input string, in upper case

std::string toLower(std::string s)¶

force a string to lower case

Parameters: s – input string
Returns: copy of input string, in lower case

std::string replaceAll(std::string str, const std::string &from, const std::string &to)¶

find and replace one substring with another

Parameters

str – input string to search
from – substring to find
to – substring to replace “from” instances to

Returns

std::string

std::vector<std::string> getPathsFromRegex(std::string root, nlohmann::json r)¶

glob, but with json

Lambda for globbing files from a regular expression stored in json. As they can be a single expression or a list, we need to massage the json a little.

Parameters

root – root path to search
r – json list of regexes

Returns

vector of paths

void mergeConfigs(nlohmann::json &baseConfig, const nlohmann::json &mergingConfig)¶

Merge two json configs.

When arrays are merged, the values from the base config will appear first in the merged config.

Parameters

baseConfig – The config to merge into
mergingConfig – The config to merge into the base config

std::vector<std::string> ls(std::string const &root, bool recursive)¶

ls, like in unix, kinda. Also it’s a function.

Iterates the input path and returning a list of files. Optionally, recursively.

Parameters

root – The root directory to search
recursive – recursively iterates through directories if true

Returns

list of paths

std::vector<std::string> glob(std::string const &root, std::regex const &reg = std::regex(~~".*"~~), bool recursive = false)¶

glob, like python’s glob.glob, except C++

Given a root and a regular expression, give all the files that match.

Parameters

root – The root directory to search
reg – std::regex object to pattern to search, defaults to “.*”, or match averything.
recursive – recursively iterates through directories if true

Returns

list of paths matching regex

std::vector<std::pair<double, double>> getTimeIntervals(std::string kpath)¶

Get start and stop times a kernel.

For each segment in the kernel, get all start and stop times as a vector of double pairs. This gets all start and stop times regardless of the frame associated with it.

Input kernel is assumed to be a binary kernel with time dependant external orientation data.

Parameters: kpath – Path to the kernel
Returns: std::vector of start and stop times

targetState getTargetState(double et, std::string target, std::string observer, std::string frame = ~~"J2000"~~, std::string abcorr = ~~"NONE"~~)¶

Simple struct for holding target states.

Gives the position and velocity for a given frame at some ephemeris time

Mostly a C++ wrap for NAIF’s spkezr_c

Parameters

et – ephemeris time at which you want to optain the target state
target – NAIF ID for the target frame
observer – NAIF ID for the observing frame
frame – The reference frame in which to get the positions in
abcorr – aborration correction flag, default it NONE. This can set to: “NONE” - No correction For the “reception” case, i.e. photons from the target being recieved by the observer at the given time. “LT” - One way light time correction “LT+S” - Correct for one-way light time and stellar aberration correction “CN” - Converging Newtonian light time correction “CN+S” - Converged Newtonian light time correction and stellar aberration correction For the “transmission” case, i.e. photons emitted from the oberver hitting at target at the given time “XLT” - One-way light time correction using a newtonian formulation “XLT+S” - One-way light time and stellar aberration correction using a newtonian formulation “XCN” - converged Newtonian light time correction “XCN+S” - converged Newtonian light time correction and stellar aberration correction.

Returns

A TargetState struct with the light time adjustment and a Nx6 state vector of positions and velocities in x,y,z,vx,vy,vz format.

targetOrientation getTargetOrientation(double et, int toframe, int refframe = 1)¶

simple struct for holding target orientations

Gives quaternion and angular velocity for a given frame at a given ephemeris time

Orientations for an input frame in some reference frame. The orientations returned from this function can be used to transform a position in the source frame to the ref frame.

Parameters

et – ephemeris time at which you want to optain the target pointing
toframe – the source frame’s NAIF code.
refframe – the reference frame’s NAIF code, orientations are relative to this reference frame

Returns

SPICE-style quaternions (w,x,y,z) and optional angular velocity

nlohmann::json findKeywords(std::string keytpl)¶

finds key:values in kernel pool

Given a key template, returns matching key:values from the kernel pool by using gnpool, gcpool, gdpool, and gipool

Parameters: keytpl – input key template to search for
Returns: json list of found key:values

std::vector<nlohmann::json::json_pointer> findKeyInJson(nlohmann::json in, std::string key, bool recursive = true)¶

recursively search keys in json.

Given a root and a regular expression, give all the files that match.

Parameters

in – input json to search
key – key to search for
recursive – recursively iterates through objects if true

Returns

vector of refernces to matching json objects

std::string getKernelType(std::string kernelPath)¶

get the Kernel type (CK, SPK, etc.)

Parameters: kernelPath – path to kernel
Returns: Kernel type as a string

std::string getConfigDirectory()¶

Get the directory pointing to the db files.

Default behavior returns the installed DB files in $CONDA_PREFIX/etc/SpiceQL/db.

If the env var $SSPICE_DEBUG is set, this returns the local source path of _SOURCE_PREFIX/SpiceQL/db/

Returns: std::string directory containing db files

std::vector<std::string> getAvailableConfigFiles()¶

Returns a vector of all the available configs.

Returns the db files in either the installed or debug directory depending on whether or not SSPICE_DEBUG is set.

See: getConfigDirectory

Returns: std::vector<std::string>

std::vector<nlohmann::json> getAvailableConfigs()¶

Get names of available config files as a json vector.

This iterates through all the configs in the db folder either installed or in the debug directory depending on whether or not SSPICE_DEBUG is set. Loads them as vector of json obects and returns the vector.

Returns: std::vector<nlohmann::json>

std::string getMissionConfigFile(std::string mission)¶

Returns the path to the Mission specific Spice config file.

Given a mission, search a prioritized list of directories for the json config file. This function checks in the order:

The local build dir, i.e. $CMAKE_SOURCE_DIR
The install dir, i.e. $CMAKE_PREFIX

Parameters: mission – mission name of the config file
Returns: path object of the condig file

nlohmann::json getMissionConfig(std::string mission)¶

Returns the path to the Mission specific Spice config file.

Given a mission, search a prioritized list of directories for the json config file. This function checks in the order:

The local build dir, i.e. $CMAKE_SOURCE_DIR
The install dir, i.e. $CMAKE_PREFIX

Parameters: mission – mission name of the config file
Returns: path object of the config file

void resolveConfigDependencies(nlohmann::json &config, const nlohmann::json &dependencies)¶

resolve the dependencies in a config in place

Given a config with “deps” keys in it and a second config to extract dependencies from, recursively resolve all of the deps into their actual values. Only allows up to 10 recurssions.

Parameters

config – The config to populate
dependencies – The config to pull dependencies from

Returns

The full instrument config

size_t eraseAtPointer(nlohmann::json &j, nlohmann::json::json_pointer ptr)¶

erase a part of a json object based on a json pointer

Parameters

j – The json object ot erase part of. Modified in place
ptr – The object to erase

Returns

The number of objects removed

std::vector<std::string> jsonArrayToVector(nlohmann::json arr)¶

Returns std::vector<string> interpretation of a json array.

Attempts to convert the json array to a C++ array. Also handles strings in cases where one element arrays are stored as scalars. Throws exception if the json obj is not an array.

Parameters: arr – input json arr
Returns: string vector containing arr data

std::string getDataDirectory()¶

Returns std::vector<string> interpretation of a json array.

Attempts to convert the json array to a C++ array. Also handles strings in cases where one element arrays are stored as scalars. Throws exception if the json obj is not an array.

Parameters: arr – input json arr
Returns: string vector containing arr data

class CkSegment¶

#include <io.h>

C++ object repersenting NAIF spice CK Segment and it’s metadata

CK kernels consist of multiple CK segments. These specifically define a type 3 CK segment which consists of two parallel arrays of ephemeris times and orientations as SPICE quaternions.

See: : https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/q2m_c.html

class Config¶

#include <config.h>

Object for interacting with SpiceQL target configs.

The config class can wrap multiple config files and give an interface for interacting with the configs and obtaining kernel lists.

class Kernel¶

#include <spice_types.h>

Base Kernel class.

This is mostly designed to enable the automatic unloading of kernels. The kernel is furnsh-ed on instantiation and unloaded in the destructor.

class KernelPool¶

#include <spice_types.h>

Singleton class for interacting with the cspice kernel pool.

Contains functions required to load and unload kernels and keep track of furnished kernels.

class KernelSet¶

#include <spice_types.h>

Class for furnishing kernels in bulk.

Given a json object, furnish every kernel under a “kernels” key. The kernels are unloaded as soon as the object goes out of scope.

Generally used on results from a kernel query.

class SpkSegment¶

#include <io.h>

C++ object repersenting NAIF spice SPK Segment and it’s metadata

SPK kernels consist of multiple CK segments. These specifically define a type 13 SPK segment which consists of parallel arrary of ephemeris times in a 6 element state array’s of x, y, z, vx, vy, vz