js-spice
js-spice
is a Node.js module that provides a JavaScript interface to NASA/JPL/NAIF's CSPICE toolkit, a collection of functions widely used in the planetary science community for spaceflight geometry calculations. Designed primarily for astrophysicists and developers in the field of space exploration, this module enables the integration of CSPICE's robust space mission analysis capabilities into JavaScript applications.
For an example of js-spice
usage, refer to our web server project that utilizes the module: Earth-Moon-Sun Simulation. This project illustrates how js-spice can be used for space-related calculations and simulations in a JavaScript environment.
Installation Guide
To install js-spice to your node.js project:
npm install @gamergenic/js-spice
Tests
js-spice
can be tested to verify the build's integrity by navigating to the project's directory and executing npm test
.
Keep in mind that some tests require SPICE kernel data files, which are automatically downloaded to the test/data directory upon the first test run.
Usage
const {spice} = require('@gamergenic/js-spice');
...for just the spice wrapper.
const { spice, cacheGenericKernel, getKernels, getGeophysicalConstants, et_now } = require('@gamergenic/js-spice');
...to include functions for downloading and caching kernel files, etc.
Example
An example of using SPICE from JavaScript:
async function example(){
const { spice, getKernels } = require('@gamergenic/js-spice');
const kernelsToLoad = [
'lsk/a_old_versions/naif0009.tls',
'pck/a_old_versions/pck00008.tpc',
'spk/planets/a_old_versions/de421.bsp',
'spk/satellites/a_old_versions/sat288.bsp',
'spk/stations/a_old_versions/earthstns_itrf93_050714.bsp',
'fk/stations/a_old_versions/earth_topo_050714.tf',
'pck/a_old_versions/earth_070425_370426_predict.bpc',
];
await getKernels(kernelsToLoad);
try{
/*
We'll consider Saturn to be visible from DSS-14 when
Saturn has elevation above 6 degrees in the DSS-14
topocentric reference frame DSS-14_TOPO.
Create a confinement window for the view period
search. This window contains the start and stop times
of the search interval.
*/
const et0 = et_now();
const et1 = et_now() + spice.spd() * 5;
const cnfine = [[et0, et1]];
/*
Set the observer, target and reference frame.
*/
const obsrvr = "DSS-14";
const target = "SATURN";
const frame = "DSS-14_TOPO";
/*
The coordinate system is latitudinal; in this system,
in the DSS-14_TOPO frame, the coordinate "latitude"
is equivalent to elevation.
*/
const crdsys = "LATITUDINAL";
const coord = "LATITUDE";
/*
The relational operator for this search is "greater
than" and the reference value is 6 degrees (converted
to radians).
*/
const relate = ">";
const refval = 6.0 * spice.rpd();
/*
We're looking for the apparent position of Saturn,
so apply corrections for light time and stellar
aberration.
*/
const abcorr = "LT+S";
/*
Set the step size for this search. The step must
be shorter than the shortest interval over which
the elevation is increasing or decreasing.
We pick a conservative value: 6 hours. Units
expected by SPICE are TDB seconds.
*/
const step = spice.spd() / 4;
/*
The adjustment value isn't used for this search;
set it to 0.
*/
const adjust = 0.0;
/*
The number of intervals will be left as default
and the argument omitted.
Execute the search.
*/
console.log("\n\nStarting elevation search.\n");
const result = spice.gfposc(
target, frame, abcorr, obsrvr,
crdsys, coord, relate, refval,
adjust, step, cnfine);
console.log("Done.\n");
/*
Display the times of rise and set.
*/
console.log( "\nTimes of Saturn rise/set as seen from DSS-14:\n\n" );
const timeformat = "YYYY MON DD HR:MN:SC.###### TDB::RND::TDB";
if(Array.isArray(result)){
result.forEach((window)=>{
et0str = spice.timout(window[0], timeformat);
et1str = spice.timout(window[1], timeformat);
console.log(`${et0str} ${et1str}`);
});
}
}
catch(error){
console.error(error);
}
}
// run the asynchronous example.
// the example will download and cache kernel files, then use 'gfposc' to determine
// Saturn's rise/set time as seen from DSS-14.
example();
Features
js-spice
is a partial wrapping of the NASA NAIF SPICE toolkit, with additional types that can be used for convenience. The wrapped functions preserve the documented parameters and usage documented in the official SPICE documentation such that it can be used as a reference source.
API Reference
Functions
Wrapped function list:
axisar
azlrec
b1900
b1950
bodvrd
clight
conics
convrt
cylrec
deltet
dpr
erract
errdev
errprt
et2utc
etcal
eul2m
evsgp4
failed
furnsh
georec
getelm
gfposc
gfsep
halfpi
ident
invert
j1900
j1950
j2000
j2100
jyear
kclear
latrec
m2eul
m2q
mtxm
mtxv
mxm
mxmt
mxv
nvc2pl
nvp2pl
oscelt
pckfrm
pgrrec
pi
pl2nvc
pl2nvp
pl2psv
prop2b
psv2pl
pxform
pxfrm2
q2m
qxq
radrec
raxisa
recazl
reccyl
recgeo
reclat
recpgr
recrad
recsph
reset
rotate
rpd
sigerr
spd
sphrec
spkcls
spkcpo
spkcpt
spkcvo
spkcvt
spkezr
spkgeo
spkgps
spkobj
spkopn
spkpos
spkw05
str2et
sxform
timout
twopi
unload
vadd
vcrss
vdist
vdot
vequ
vhat
vlcom
vlcom3
vminus
vnorm
vpack
vperp
vprjp
vprjpi
vproj
vrel
vrotv
vscl
vsep
vsub
vtmv
vupack
vzero
xpose
Types
None. Native JavaScript types are used.
Vectors
[x,y,z]
, where x, y, and z are double-precision numerics.
Quaternions
{"w":x, "x":x, "y":y, "z":z}
Ephemeris Time
et
, where et is a double-precision number.
State
{"r": [x,y,z], "v": [dx,dy,dz]}
, where x, y, z and dx, dy, dz are double-precision numbers.
AZL
{"range": range, "az":az, "el":el};
, where range, az, and el are double-precision numbers.
CYL
{"r": r, "clon":clon, "z":z}
, where r, clon, and z are double-precision numbers.
GEO
{"lon": lon, "lat": lat, "alt": alt}
, where lon, lat, and alt are double-precision numbers.
LAT
{"radius": radius, "lon": lon, "lat": lat}
, where radius, lon, and lat are double-precision numbers.
PGR
{"lon", "lat", "alt"}
, where lon, lat, and alt are double-precision numbers.
RAD
{"range", "ra", "dec"}
, where range, ra, and dec are double-precision numbers.
SPH
{"r", "colat", "slon"}
, where r, colat, and slon are double-precision numbers.
Osculating elements
{"rp": rp, "ecc": ecc, "inc":inc, "lnode":lnode, "argp":argp, "m0":m0, "t0":t0, "mu":mu}
, where all values are double-precision numerics.
rp Perifocal distance.
ecc Eccentricity.
inc Inclination.
lnode Longitude of the ascending node.
argp Argument of periapse.
m0 Mean anomaly at epoch.
t0 Epoch.
mu Gravitational parameter.
Two-line elements
{"ndt20":ndt20, "ndd60":ndd60, "bstar":bstar, "incl":incl, "node0":node0, "ecc":ecc, "omega":omega, "m0":m0, "n0":n0, "epoch":epoch}
, where all values are double-precision numerics
Confinement windows
[[start1, end1], [start2, end2], ...]
, where start1, end1, ... are double precision et's.
Matrices (3D Rotation)
[[m00, m01, m02],
[m10, m11, m12],
[m20, m21, m22]]
Where m00...m22 are double-precision numeric values.
Planes
{"normal": [x, y, z], "constant": c}
Euler Angles
{
"angle3": angle3,
"angle2": angle2,
"angle1": angle1,
"axis3": axis3,
"axis2": axis2,
"axis1": axis1
}
Functions will throw an error when they are unable to decipher input. The error thrown will explain the expected type for the first incorrect argument detected.
In some places inputs can be provided in multiple formats but outputs formats for a given type are intended to remain consistent. For example spice.recazl
will accept ([x,y,z])
, ("x":x, "y":y, "z":z)
, or (x, y, z)
while spice.azlrec
will only output [x,y,z]
.
Functions
axisar
Function Documentation
Functionality
The axisar
function constructs a rotation matrix for rotating vectors by a specified angle about a specified axis.
Usage Examples
Array Axis:
let axis = [0, 0, 1];
let angle = 3.1415926536; // Angle in radians
let rotationMatrix = spice.axisar(axis, angle);
Object Axis:
axis = {x: 0, y: 0, z: 1};
rotationMatrix = spice.axisar(axis, angle);
Separate Axis Arguments:
rotationMatrix = spice.axisar(0, 0, 1, angle);
Parameters
-
axis
: The axis of rotation. Can be provided as an array[x, y, z]
, an object{x:, y:, z:}
, or as separatex, y, z
arguments. -
angle
: The rotation angle in radians.
Return Value
Returns a 3x3 rotation matrix (2D array) representing the rotation.
Error Handling
- Throws an error if encountered.
Notes
- This function wraps the NAIF SPICE
axisar_c
function. - Be aware of the precision limits due to floating-point arithmetic.
azlrec
Function Documentation
Functionality
The azlrec
function converts from the range, azimuth, and elevation of a point to rectangular coordinates.
Usage Examples
Standard Coordinates:
const pi = 3.1415926536;
const rpd = pi / 180;
const azl = {"range": 1.732, "az": 315 * rpd, "el": -35.264 * rpd};
const rec = spice.azlrec(azl, false, false);
const x = rec[0];
const y = rec[1];
const z = rec[2];
Azimuth Counter-Clockwise, Elevation Positive-Z:
const rec = spice.azlrec(azl, true, true);
Parameters
-
azl
: An object containingrange
,az
(azimuth), andel
(elevation) properties. -
azccw
: A boolean flag indicating if azimuth is counter-clockwise (true) or clockwise (false). -
elplsz
: A boolean flag indicating if elevation is positive towards +Z (true) or towards -Z (false).
Return Value
Returns an array of rectangular coordinates corresponding to the input azimuthal coordinates.
Error Handling
- Throws an error if incorrect arguments are provided.
b1900
Function Documentation
Functionality
The b1900
function returns the Julian Date corresponding to Besselian Date 1900.0.
Usage Example
const b1900 = spice.b1900();
Return Value
Returns the Julian Date corresponding to Besselian Date 1900.0 as a double.
Notes
- This function wraps the NAIF SPICE
b1900_c
function. - No input parameters are required.
- Does not throw an error.
b1950
Function Documentation
Functionality
The b1950
function returns the Julian Date corresponding to Besselian Date 1950.0.
Usage Example
const b1950 = spice.b1950();
Return Value
Returns the Julian Date corresponding to Besselian Date 1950.0 as a double.
Notes
- This function wraps the NAIF SPICE
b1950_c
function. - No input parameters are required.
- Does not throw an error.
bodvrd
Function Documentation
Functionality
The bodvrd
function fetches from the kernel pool the double precision values of an item associated with a body, such as radii or axis lengths.
Usage Examples
Fetching Earth Radii:
const earth_radii = spice.bodvrd("EARTH", "RADII");
// earth_radii is a 3D numeric array.
Fetching Radii with Body ID:
const earth_radii = spice.bodvrd("399", "RADII");
// earth_radii is a 3D numeric array.
Fetching 1-Dimensional Value:
const earth_long_axis = spice.bodvrd("EARTH", "LONG_AXIS");
// earth_long_axis is a double-precision number.
Parameters
-
bodynm
: Name of the celestial body (e.g., "EARTH") or body ID (e.g., "399"). -
item
: The item for which values are requested (e.g., "RADII", "LONG_AXIS"). -
maxn
(optional): Maximum number of values expected.
Return Value
Returns an array of double precision values if the result is multi-dimensional, or a single numeric value if the result is 1-dimensional.
Error Handling
- Throws an error if incorrect arguments are provided or if the kernel variable is not found.
clight
Function Documentation
Functionality
The clight
function returns the speed of light in a vacuum, expressed in kilometers per second.
Usage Example
const c = spice.clight();
Return Value
Returns the speed of light in vacuum (km/sec) as a double.
Notes
- This function wraps the NAIF SPICE
clight_c
function. - No input parameters are required.
- Does not throw an error.
conics
Function Documentation
Functionality
The conics
function determines the state (position and velocity) of an orbiting body from a set of orbital elements (elliptic, hyperbolic, or parabolic).
Usage Example
const oscelts = {
"rp": 1e8,
"ecc": 0,
"inc": 1.5707963267948966,
"lnode": 1.5707963267948966,
"argp": 0,
"m0": 0.7853981633974484,
"t0": 0,
"mu": 398600.435436096
};
const et = 0;
let state_at_et = spice.conics(oscelts, et);
// position as an [x, y, z] array
let r = state_at_et.r;
// velocity as a [dx, dy, dz] array
let v = state_at_et.v;
Parameters
-
oscelts
: An object containing orbital elements (rp, ecc, inc, lnode, argp, m0, t0, mu). -
et
: The ephemeris time at which the state of the body is to be computed.
Return Value
Returns an object containing the state (position 'r' and velocity 'v') of the body.
Error Handling
- Throws an error if incorrect arguments are provided.
convrt
Function Documentation
Functionality
The convrt
function converts a numerical value from one unit to another (e.g., miles to kilometers, parsecs to lightyears).
Usage Examples
Miles to Kilometers:
const statute_miles = 300.0;
const km = spice.convrt(distsm, "statute_miles", "km");
Parsecs to Lightyears:
const parsecs = 1.0;
const lightyears = spice.convrt(onpars, "PARSECS", "LIGHTYEARS");
Parameters
-
x
: The numeric value to be converted. -
in
: The unit of the input value (e.g., "statute_miles", "PARSECS"). -
out
: The unit for the output value (e.g., "km", "LIGHTYEARS").
From NAIF SPICE Documentation, the following are recognized units:
-
Angles:
- "RADIANS"
- "DEGREES"
- "ARCMINUTES"
- "ARCSECONDS"
- "HOURANGLE"
- "MINUTEANGLE"
- "SECONDANGLE"
-
Metric Distances:
- "METERS"
- "M"
- "KILOMETERS"
- "KM"
- "CENTIMETERS"
- "CM"
- "MILLIMETERS"
- "MM"
-
English Distances:
- "FEET"
- "INCHES"
- "YARDS"
- "STATUTE_MILES"
- "NAUTICAL_MILES"
-
Astrometric Distances:
- "AU"
- "PARSECS"
- "LIGHTSECS"
- "LIGHTYEARS" julian lightyears
-
Time:
- "SECONDS"
- "MINUTES"
- "HOURS"
- "DAYS"
- "JULIAN_YEARS"
- "TROPICAL_YEARS"
- "YEARS" (same as julian years)
Return Value
Returns the converted value as a double.
Error Handling
- Throws an error if conversion between the specified units is not possible or if units are unrecognized.
cylrec
Function Documentation
Functionality
The cylrec
function converts coordinates from cylindrical to rectangular representation.
Usage Example
const pi = 3.1415926536;
const rpd = pi / 180;
const cyl = {"r": 1.4142, "clon": 45.0 * rpd, "z": 1.0};
// get rectangular coordinates as [x, y, z] array
const rec = spice.cylrec(cyl);
Parameters
-
cyl
: An object representing cylindrical coordinates with propertiesr
(radius),clon
(longitude in radians), andz
(height).
Return Value
Returns an array representing the rectangular coordinates corresponding to the input cylindrical coordinates.
Error Handling
- Throws an error if incorrect arguments are provided.
deltet
Function Documentation
Functionality
The deltet
function computes the value of Delta ET (ET - UTC) for a given epoch. This function is typically used to convert between Ephemeris Time (ET) and Coordinated Universal Time (UTC).
Usage Example
const epoch = 0;
const eptype = 'UTC';
const delta = spice.deltet(epoch, eptype);
Parameters
-
epoch
: The epoch at which Delta ET is to be computed. -
eptype
: The type of the input epoch, typically 'UTC'.
Return Value
Returns the value of Delta ET (ET - UTC) as a double.
Error Handling
- Throws an error if incorrect arguments are provided.
dpr
Function Documentation
Functionality
The dpr
function returns the number of degrees per radian, useful for converting angles from radians to degrees.
Usage Example
const degreesPerRadian = spice.dpr();
Return Value
Returns the number of degrees per radian as a double.
Notes
- This function wraps the NAIF SPICE
dpr_c
function. - No input parameters are required.
- Does not throw an error.
erract
Function Documentation
Functionality
The erract
function retrieves or sets the default error action for handling CSPICE errors.
Usage Example
const initialValue = spice.erract('GET');
spice.erract('SET', "IGNORE");
Parameters
- First argument (string): Specifies the action to be performed ('GET' or 'SET').
- Second argument (string, optional): Specifies the error action to set ('ABORT', 'IGNORE', 'REPORT', 'RETURN', 'DEFAULT'). Only required when the first argument is 'SET'.
Return Value
When used with 'GET', returns the current error action. When used with 'SET', returns the new error action.
Error Handling
- Throws an error if incorrect arguments are provided.
errdev
Function Documentation
Functionality
The errdev
function retrieves or sets the name of the current output device for CSPICE error messages.
Usage Example
const initialValue = spice.errdev('GET');
spice.errdev('SET', "./test/temp/tempfile");
Parameters
- First argument (string): Specifies the action to be performed ('GET' or 'SET').
- Second argument (string, optional): The name of the error output device. Only required when the first argument is 'SET'. Valid values are "SCREEN", "NULL", or a file path.
Return Value
When used with 'GET', returns the name of the current error output device. When used with 'SET', returns the new error output device name.
Error Handling
- Throws an error if incorrect arguments are provided.
errprt
Function Documentation
Functionality
The errprt
function retrieves or sets the list of error message items to be output when a CSPICE error is detected.
Usage Example
const initialValue = spice.errprt('GET');
spice.errprt('SET', "SHORT, LONG");
Parameters
- First argument (string): Specifies the action to be performed ('GET' or 'SET').
- Second argument (string, optional): The list of error message items to output. Only required when the first argument is 'SET'. For information on valid values consult the NAIF documentation for errprt_c.
Return Value
When used with 'GET', returns the current list of error message items. When used with 'SET', returns the new list.
Error Handling
- Throws an error if incorrect arguments are provided.
et2utc
Function Documentation
Functionality
The et2utc
function converts an input time from ephemeris seconds past J2000 to Calendar, Day-of-Year, or Julian Date format, UTC.
Usage Example
const et = -527644192.5403653;
const calendarFormatted = spice.et2utc(et, "C", 3);
Parameters
-
et
: The ephemeris time in seconds past J2000 to be converted. -
format
: The format of the output time string ("C" for Calendar, "D" for Day-of-Year, "J" for Julian Date). -
prec
: The precision of fractional seconds in the output time string.
Return Value
Returns the converted time as a string in the specified format.
Error Handling
- Throws an error if incorrect arguments are provided.
etcal
Function Documentation
Functionality
The etcal
function converts an ephemeris epoch, measured in seconds past the epoch of J2000, to a calendar string.
Usage Example
const et = 0;
const calendarString = spice.etcal(et);
Parameters
-
et
: The ephemeris time in seconds past J2000 to be converted.
Return Value
Returns a calendar string corresponding to the input ephemeris time.
Error Handling
- Throws an error if incorrect arguments are provided.
eul2m
Function Documentation
Functionality
The eul2m
function constructs a rotation matrix from a set of Euler angles.
Usage Example
let pi = spice.pi();
const angle3 = 0;
const angle2 = 0;
const angle1 = pi / 2;
const axis3 = 1;
const axis2 = 2;
const axis1 = 3;
const eulers = {
angle3, angle2, angle1,
axis3, axis2, axis1
};
const rotationMatrix = spice.eul2m(eulers);
Parameters
- An object with the following required key/value pairs:
-
angle3
,angle2
,angle1
: The three Euler angles (in radians). -
axis3
,axis2
,axis1
: The axes of the rotations (1-3)
Return Value
Returns a 3x3 rotation matrix constructed from the specified Euler angles.
Error Handling
- Throws an error if incorrect arguments are provided.
evsgp4
Function Documentation
Functionality
The evsgp4
function evaluates NORAD two-line element data for Earth-orbiting spacecraft, computing position and velocity of the spacecraft at a specified ephemeris time.
Usage Example
const { spice, getGeophysicalConstants } = require('@gamergenic/js-spice');
const geophs = await getGeophysicalConstants(true, 'pck/geophysical.ker', 'kennel_cache/naif/generic_kernels');
const et = spice.str2et('2020-05-26 02:25:00');
const tle = [
'1 43908U 18111AJ 20146.60805006 .00000806 00000-0 34965-4 0 9999',
'2 43908 97.2676 47.2136 0020001 220.6050 139.3698 15.24999521 78544'
];
const { elems } = spice.getelm(1957, tle);
const state = spice.evsgp4(et, geophs, elems);
// where is it a day later?
// r = [x, y, z] array
// v = [dx, dy, dz] array
const {r, v} = spice.evsgp4(et + spice.spd(), geophs, elems);
Parameters
-
et
: The ephemeris time at which the state is to be computed. -
geophs
: An array of geophysical constants. see -
elems
: An array of elements from the NORAD two-line elements.
Return Value
Returns an object containing the state (position 'r' and velocity 'v') of the spacecraft.
Error Handling
- Throws an error if incorrect arguments are provided.
failed
Function Documentation
Functionality
The failed
function checks if an error is currently signaled in the CSPICE system. Note that js-spice wrapped functions, reset the error status before throwing an exception.
Usage Examples
Check for No Error:
spice.reset();
const failed = spice.failed();
// failed will be false
Check for Signaled Error:
spice.sigerr('Houston, we have a problem.');
const failed = spice.failed();
// failed will be true
spice.reset(/*Failure is not an option*/);
Return Value
Returns a boolean value: true
if an error is currently signaled, false
otherwise.
Notes
- This function wraps the NAIF SPICE
failed_c
function. - No input parameters are required.
- Does not throw an error.
furnsh
Function Documentation
Functionality
The furnsh
function furnishes a program with SPICE kernels. It is used to load one or more SPICE kernel files into a program.
Usage Examples
Load a Single Kernel File:
const singleFilePathStr = './test/data/naif/generic_kernels/pck00009.tpc';
spice.furnsh(singleFilePathStr);
Load Multiple Kernel Files:
const pathsArray = ['./path/to/kernel1', './path/to/kernel2'];
spice.furnsh(pathsArray);
Error Handling Example:
spice.furnsh("badpath");
// the next line will never execute (unless you have a kernel named 'badpath', but you don't.)
Parameters
- Can be a single string specifying the path to a kernel file, or an array of strings specifying multiple paths.
Return Value
Does not return a value. Kernels are loaded into the program's internal data space.
Error Handling
- Throws an error if a kernel file cannot be found or if the input is not a string or an array of strings.
georec
Function Documentation
Functionality
The georec
function converts geodetic coordinates (longitude, latitude, altitude) to rectangular coordinates.
Usage Example
const radius = 6378.2064;
const f = 1. / 294.9787;
const pi = 3.1415926536;
const rpd = pi / 180;
const geo = {"lon": 90.0 * rpd, "lat": 0, "alt": 0};
// get rectancular coordinates as [x, y, z] array
const rec = spice.georec(geo, radius, f);
Parameters
-
lon
,lat
,alt
: Longitude, latitude, and altitude in the geodetic coordinate system. -
re
: The equatorial radius of the reference spheroid in kilometers. -
f
: The flattening coefficient of the reference spheroid.
Return Value
Returns an array representing the rectangular coordinates corresponding to the input geodetic coordinates.
Error Handling
- Throws an error if incorrect arguments are provided.
getelm
Function Documentation
Functionality
The getelm
function evaluates NORAD two-line element data for Earth-orbiting spacecraft, extracting orbital elements from the two-line element set.
Usage Example
const tle = [
'1 43908U 18111AJ 20146.60805006 .00000806 00000-0 34965-4 0 9999',
'2 43908 97.2676 47.2136 0020001 220.6050 139.3698 15.24999521 78544'
];
const {elems} = spice.getelm(1957, tle);
Parameters
-
frstyr
: The first two digits of the year corresponding to the earliest representable two-line elements. -
tle
: An array containing the two lines of NORAD two-line element data as strings.
Return Value
Returns an object containing 'elems', the extracted orbital elements and the epoch of the elements and 'epoch'. This is of the form:
{
elems:
{
"ndt20": 2.4422489185892878e-11,
"ndd60": 0,
"bstar": 0.000034965,
"incl": 1.6976398755128366,
"node0": 0.8240327717195948,
"ecc": 0.0020001,
"omega": 3.8502835963620905,
"m0": 2.432461887845993,
"n0": 0.06654065683196603,
"epoch": 643689404.7102276
},
epoch: 643689404.7102276
}
Error Handling
- Throws an error if incorrect arguments are provided.
gfposc
Function Documentation
Functionality
The gfposc
function determines time intervals for which a coordinate of an observer-target position vector satisfies a numerical constraint, typically used for visibility or occultation events.
Usage Example
const et0 = spice.str2et("2009 JAN 1");
const et1 = spice.str2et("2009 JAN 5");
const cnfine = [[et0, et1]];
const obsrvr = "DSS-14";
const target = "SATURN";
const frame = "DSS-14_TOPO";
const crdsys = "LATITUDINAL";
const coord = "LATITUDE";
const relate = ">";
const refval = 6.0 * spice.rpd();
const abcorr = "LT+S";
const step = spice.spd() / 4;
const adjust = 0.0;
// Get the intervals as an array of et pairs [[start1, end1], [start2, end2], ...]
const timeWindows = spice.gfposc(target, frame, abcorr, obsrvr, crdsys, coord, relate, refval, adjust, step, cnfine);
Parameters
-
target
,frame
,abcorr
,obsrvr
: Target, frame, aberration correction, and observer names. -
crdsys
,coord
: Coordinate system and coordinate name. -
relate
: Relational operator ('<', '>', '=', '>=', '<=', '!='). -
refval
: Reference value for the constraint. -
adjust
: Adjustment value for absolute extremal searches. -
step
: Step size in seconds for the search. -
cnfine
: Confinement window for the search.
Return Value
Returns an array of time windows (et [start, end] arrays) when the specified constraint is satisfied.
Error Handling
- Throws an error if incorrect arguments are provided.
example
const kernelsToLoad = [
'lsk/a_old_versions/naif0009.tls',
'pck/a_old_versions/pck00008.tpc',
'spk/planets/a_old_versions/de421.bsp',
'spk/satellites/a_old_versions/sat288.bsp',
'spk/stations/a_old_versions/earthstns_itrf93_050714.bsp',
'fk/stations/a_old_versions/earth_topo_050714.tf',
'pck/a_old_versions/earth_070425_370426_predict.bpc',
];
await getKernels(kernelsToLoad);
try{
/*
We'll consider Saturn to be visible from DSS-14 when
Saturn has elevation above 6 degrees in the DSS-14
topocentric reference frame DSS-14_TOPO.
Create a confinement window for the view period
search. This window contains the start and stop times
of the search interval.
*/
const et0 = et_now();
const et1 = et_now() + spice.spd() * 5;
const cnfine = [[et0, et1]];
/*
Set the observer, target and reference frame.
*/
const obsrvr = "DSS-14";
const target = "SATURN";
const frame = "DSS-14_TOPO";
/*
The coordinate system is latitudinal; in this system,
in the DSS-14_TOPO frame, the coordinate "latitude"
is equivalent to elevation.
*/
const crdsys = "LATITUDINAL";
const coord = "LATITUDE";
/*
The relational operator for this search is "greater
than" and the reference value is 6 degrees (converted
to radians).
*/
const relate = ">";
const refval = 6.0 * spice.rpd();
/*
We're looking for the apparent position of Saturn,
so apply corrections for light time and stellar
aberration.
*/
const abcorr = "LT+S";
/*
Set the step size for this search. The step must
be shorter than the shortest interval over which
the elevation is increasing or decreasing.
We pick a conservative value: 6 hours. Units
expected by SPICE are TDB seconds.
*/
const step = spice.spd() / 4;
/*
The adjustment value isn't used for this search;
set it to 0.
*/
const adjust = 0.0;
/*
The number of intervals will be left as default
and the argument omitted.
Execute the search.
*/
console.log("\n\nStarting elevation search.\n");
const result = spice.gfposc(
target, frame, abcorr, obsrvr,
crdsys, coord, relate, refval,
adjust, step, cnfine);
console.log("Done.\n");
/*
Display the times of rise and set.
*/
console.log( "\nTimes of Saturn rise/set as seen from DSS-14:\n\n" );
const timeformat = "YYYY MON DD HR:MN:SC.###### TDB::RND::TDB";
if(Array.isArray(result)){
result.forEach((window)=>{
et0str = spice.timout(window[0], timeformat);
et1str = spice.timout(window[1], timeformat);
console.log(`${et0str} ${et1str}`);
});
}
}
catch(error){
console.error(error);
}
gfsep
Function Documentation
Functionality
The gfsep
function determines time intervals when the angular separation between the position vectors of two target bodies relative to an observer satisfies a numerical relationship. It is commonly used to find events like conjunctions and oppositions.
Usage Example
const targ1 = "MOON";
const shape1 = "SPHERE";
const frame1 = "NULL";
const targ2 = "EARTH";
const shape2 = "SPHERE";
const frame2 = "NULL";
const abcorr = "NONE";
const obsrvr = "SUN";
const relate = "LOCMAX";
const step = 6. * spice.spd();
const adjust = 0;
const refval = 0;
const et1 = spice.str2et("2007 JAN 01");
const et2 = spice.str2et("2007 JUL 01");
const cnfine = [[et1, et2]];
// Get the intervals as an array of et pairs [[start1, end1], [start2, end2], ...]
const timeWindows = spice.gfsep(
targ1, shape1, frame1, targ2, shape2, frame2, abcorr, obsrvr, relate, refval, adjust, step, cnfine);
Parameters
-
targ1
,shape1
,frame1
: The first target, its shape, and frame. -
targ2
,shape2
,frame2
: The second target, its shape, and frame. -
abcorr
,obsrvr
: Aberration correction and the observer's name. -
relate
: The relational condition for the search ('=', '!=', '<', '>', '<=', '>=', 'LOCMAX', 'LOCMIN', 'ABSMAX', 'ABSMIN'). -
refval
,adjust
,step
: Reference value, adjustment value for absolute extremal searches, and the search step size. -
cnfine
: The confinement window for the search.
Return Value
Returns an array of time windows when the specified condition is satisfied.
Error Handling
- Throws an error if incorrect arguments are provided.
halfpi
Function Documentation
Functionality
The halfpi
function returns half the value of π (pi). This function is useful in calculations involving radians and degrees, especially in trigonometric functions.
Usage Example
const halfpi = spice.halfpi();
Return Value
Returns half the value of π as a double.
Notes
- This function wraps the NAIF SPICE
halfpi_c
function. - No input parameters are required.
- Does not throw an error.
ident
Function Documentation
Functionality
The ident
function returns the 3x3 identity matrix. This matrix is often used in linear algebra and transformations involving coordinates and rotations.
Usage Example
// load the identy matrix as [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
const m_identity = spice.ident();
Return Value
Returns the 3x3 identity matrix.
Notes
- This function wraps the NAIF SPICE
ident_c
function. - No input parameters are required.
- Does not throw an error.
invert
Function Documentation
Functionality
The invert
function generates the inverse of a 3x3 matrix. This function is commonly used in linear algebra, especially in transformations and rotations.
Usage Example
const m = [[0, -1, 0], [0.5, 0, 0], [0, 0, 1]];
const inverse = spice.invert(m);
Parameters
-
m
: The 3x3 matrix to be inverted.
Return Value
Returns the inverse of the given 3x3 matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
j1900
Function Documentation
Functionality
The j1900
function returns the Julian Date corresponding to the date 1899 DEC 31 12:00:00 (1900 JAN 0.5). This is often used as a standard reference date in astronomical calculations.
Usage Example
const j1900 = spice.j1900();
Return Value
Returns the Julian Date of 1899 DEC 31 12:00:00 as a double.
Notes
- This function wraps the NAIF SPICE
j1900_c
function. - No input parameters are required.
- Does not throw an error.
j1950
Function Documentation
Functionality
The j1950
function returns the Julian Date corresponding to the date 1950 JAN 01 00:00:00 (1950 JAN 1.0). This date is often used as a standard epoch in astronomical calculations.
Usage Example
const actual = spice.j1950();
Return Value
Returns the Julian Date of 1950 JAN 01 00:00:00 as a double.
Notes
- This function wraps the NAIF SPICE
j1950_c
function. - No input parameters are required.
- Does not throw an error.
j2000
Function Documentation
Functionality
The j2000
function returns the Julian Date corresponding to the date 2000 JAN 01 12:00:00 (2000 JAN 1.5). This is a key reference date in astronomical and space mission calculations.
Usage Example
const j2000 = spice.j2000();
Return Value
Returns the Julian Date of 2000 JAN 01 12:00:00 as a double.
Notes
- This function wraps the NAIF SPICE
j2000_c
function. - No input parameters are required.
- Does not throw an error.
j2100
Function Documentation
Functionality
The j2100
function returns the Julian Date corresponding to the date 2100 JAN 01 12:00:00 (2100 JAN 1.5). This date is often used in long-term astronomical and space mission calculations.
Usage Example
const j2100 = spice.j2100();
Return Value
Returns the Julian Date of 2100 JAN 01 12:00:00 as a double.
Notes
- This function wraps the NAIF SPICE
j2100_c
function. - No input parameters are required.
- Does not throw an error.
jyear
Function Documentation
Functionality
The jyear
function returns the number of seconds in a Julian year. This is a key constant in time system conversions and astronomical calculations.
Usage Example
const jyear = spice.jyear();
Return Value
Returns the number of seconds in a Julian year as a double.
Notes
- This function wraps the NAIF SPICE
jyear_c
function. - No input parameters are required.
- Does not throw an error.
kclear
Function Documentation
Functionality
The kclear
function clears all loaded SPICE kernels from the program's internal data space. It is often used in unit testing and when resetting the kernel pool is necessary.
Usage Example
spice.kclear();
Notes
- This function wraps the NAIF SPICE
kclear_c
function. - No input parameters are required.
- Does not throw an error.
latrec
Function Documentation
Functionality
The latrec
function converts from latitudinal coordinates (radius, longitude, latitude) to rectangular coordinates.
Usage Example
const lat = {"radius": 403626.33912495, "lon": -98.34959789 * spice.rpd(), "lat": -18.26566077 * spice.rpd()};
const rec = spice.latrec(lat);
const x = rec[0];
const y = rec[1];
const z = rec[2];
Parameters
-
radius
: The distance of the point from the origin. -
lon
: The longitude of the point in radians. -
lat
: The latitude of the point in radians.
Return Value
Returns an array representing the rectangular coordinates corresponding to the input latitudinal coordinates.
Error Handling
- Throws an error if incorrect arguments are provided.
m2eul
Function Documentation
Functionality
The m2eul
function factors a rotation matrix as a product of three rotations about specified coordinate axes.
Usage Example
const r = [[0, 1, 0], [-1, 0, 0], [0, 0, 1]];
const axis3 = 1;
const axis2 = 2;
const axis1 = 3;
const eulers = spice.m2eul(r, axis3, axis2, axis1);
Parameters
-
r
: The rotation matrix to be factored. -
axis3
,axis2
,axis1
: The axes of the rotations.
Return Value
Returns an object containing the Euler angles and axes associated with the factored rotation.
- An object with the following key/value pairs:
-
angle3
,angle2
,angle1
: The three Euler angles (in radians). -
axis3
,axis2
,axis1
: The axes of the rotations (1-3)
Error Handling
- Throws an error if incorrect arguments are provided.
m2q
Function Documentation
Functionality
The m2q
function finds a unit quaternion corresponding to a specified rotation matrix. Quaternions are used in rotations and orientation calculations in three-dimensional space.
Usage Example
let pi = 3.1415926536;
const r = spice.rotate(pi/2, 3);
const quat = spice.m2q(r);
const qx = quat.x;
const qy = quat.y;
const qz = quat.z;
const qw = quat.w;
Parameters
-
r
: The rotation matrix to be converted into a quaternion.
Return Value
Returns a unit quaternion corresponding to the given rotation matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
mtxm
Function Documentation
Functionality
The mtxm
function multiplies the transpose of the first input matrix with the second input matrix. This operation is commonly used in linear algebra, particularly in transformations and rotations.
Usage Example
let m1 = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; // This matrix will be transposed
let m2 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; // This matrix remains as is
let m1t_x_m2 = spice.mtxm(m1, m2); // Multiplication after transposing m1
Parameters
-
m1
: The first 3x3 matrix to be transposed and then multiplied. -
m2
: The second 3x3 matrix.
Return Value
Returns the product of the transposed first matrix and the second matrix as a 3x3 matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
mtxv
Function Documentation
Functionality
The mtxv
function multiplies the transpose of a 3x3 matrix with a 3-dimensional vector. This operation is commonly used in coordinate transformations and vector rotations.
Usage Example
let m = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; // The matrix to be transposed
let v = [1, 0, 0]; // The vector
let mt_x_v = spice.mtxv(m, v); // Multiplication after transposing m
const x = mt_x_v[0];
const y = mt_x_v[1];
const z = mt_x_v[2];
Parameters
-
m
: The 3x3 matrix to be transposed. -
v
: The 3-dimensional vector.
Return Value
Returns the product of the transposed matrix and the vector as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
mxm
Function Documentation
Functionality
The mxm
function multiplies two 3x3 matrices. This operation is widely used in linear algebra, particularly in transformations and rotations.
Usage Example
let m1 = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
let m2 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
// the result will be in the same form as m1, m2 above
let m_x_m = spice.mxm(m1, m2);
Parameters
-
m1
,m2
: The two 3x3 matrices to be multiplied.
Return Value
Returns the product of the two matrices as a 3x3 matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
mxmt
Function Documentation
Functionality
The mxmt
function multiplies the first 3x3 matrix with the transpose of the second 3x3 matrix. This operation is used in linear algebra, particularly in coordinate transformations and rotations.
Usage Example
let m1 = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; // First matrix
let m2 = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; // Second matrix, to be transposed
let m_x_mt = spice.mxmt(m1, m2); // Multiplication with transpose of m2
Parameters
-
m1
: The first 3x3 matrix. -
m2
: The second 3x3 matrix, which will be transposed.
Return Value
Returns the product of the first matrix and the transpose of the second matrix as a 3x3 matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
mxv
Function Documentation
Functionality
The mxv
function multiplies a 3x3 matrix with a 3-dimensional vector. This operation is commonly used in coordinate transformations and vector rotations.
Usage Example
let m = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; // The matrix
let v = [1, 0, 0]; // The vector
let m_x_v = spice.mxv(m, v); // Multiplication of matrix and vector
// result was [x, y, z] array
const x = m_x_v[0];
const y = m_x_v[1];
const z = m_x_v[2];
Parameters
-
m
: The 3x3 matrix. -
v
: The 3-dimensional vector.
Return Value
Returns the product of the matrix and the vector as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
nvc2pl
Function Documentation
Functionality
The nvc2pl
function creates a SPICE plane from a specified normal vector and a constant. This is often used in geometric computations involving planes.
Usage Example
const normal = [1, 2, 3];
const constant = 4;
// plane will be of the form { "normal": [1, 2, 3], "constant": 4}
// and ready to be passed into functions such as vprjp.
const plane = spice.nvc2pl(normal, constant);
Parameters
-
normal
: A 3-dimensional normal vector. -
konst
: A scalar constant.
Return Value
Returns a SPICE plane defined by the normal vector and the constant.
Error Handling
- Throws an error if incorrect arguments are provided.
nvp2pl
Function Documentation
Functionality
The nvp2pl
function creates a SPICE plane from a specified normal vector and a point. This function is useful in geometric computations involving planes.
Usage Example
const normal = [1, 2, 3];
const point = [1, 2, 3];
// plane will be of the form { "normal": [1, 2, 3], "constant": 4}
// and ready to be passed into functions such as vprjp.
const plane = spice.nvp2pl(normal, point);
Parameters
-
normal
: A 3-dimensional normal vector. -
point
: A 3-dimensional point vector.
Return Value
Returns a SPICE plane defined by the normal vector and the point.
Error Handling
- Throws an error if incorrect arguments are provided.
oscelt
Function Documentation
Functionality
The oscelt
function computes the set of osculating conic orbital elements corresponding to the state (position and velocity) of a body. This is essential in celestial mechanics and orbital calculations.
Usage Example
const mu = 3.9860043543609598e5;
const r = 1e8;
const speed = Math.sqrt(mu/r);
const pvinit = {
"r": [0, r/Math.sqrt(2), r/Math.sqrt(2)],
"v": [0, -speed/Math.sqrt(2), speed/Math.sqrt(2)]
};
const et = 0;
const elts = spice.oscelt(pvinit, et, mu);
Parameters
-
state
: The state vector (position and velocity) of the body. -
et
: The ephemeris time. -
mu
: The gravitational parameter (GM) of the primary body.
Return Value
Returns the set of osculating conic orbital elements as an object of the form:
{
"rp": 1e8,
"ecc": 0,
"inc": 1.5707963267948966,
"lnode": 1.5707963267948966,
"argp": 0,
"m0": 0.7853981633974484,
"t0": 0,
"mu": 398600.435436096
};
Error Handling
- Throws an error if incorrect arguments are provided.
pckfrm
Function Documentation
Functionality
The pckfrm
function retrieves the set of reference frame class ID codes from all frames in a specified binary PCK (Planetary Constants Kernel) file. This is useful in planetary science and navigation.
Usage Example
const singleFilePathStr = 'path/to/pck/file.bpc';
const idCodeArray = spice.pckfrm(singleFilePathStr);
Parameters
-
pckfnm
: File path to the binary PCK file.
Return Value
Returns an array of reference frame class ID codes found in the specified PCK file.
Error Handling
- Throws an error if incorrect arguments are provided or if the file cannot be accessed.
pgrrec
Function Documentation
Functionality
The pgrrec
function converts planetographic coordinates to rectangular coordinates. It's essential for working with planetary data in different coordinate systems.
Usage Example
const { spice, getKernels } = require('@gamergenic/js-spice');
await getKernels('pck/a_old_versions/pck00008.tpc', 'kernel_cache/data/naif/generic_kernels');
const re = 3396.190;
const rp = 3376.200;
const f = (re - rp) / re;
const pgr = {"lon": 270.000 * spice.rpd(), "lat": 0, "alt": 0};
const rec = spice.pgrrec('mars', pgr, re, f);
// rec will be an array of the form [x, y, z]
Parameters
-
body
: Name of the body. -
lon
,lat
,alt
: Longitude, latitude, and altitude. -
re
: Equatorial radius of the reference spheroid in kilometers. -
f
: Flattening coefficient.
Return Value
Returns rectangular coordinates based on the given planetographic coordinates.
Error Handling
- Throws an error if incorrect arguments are provided or if the specified body is not recognized.
pi
Function Documentation
Functionality
The pi
function returns the mathematical constant π (pi), the ratio of a circle's circumference to its diameter.
Usage Example
const actual = spice.pi(); // Returns the value of pi
Parameters
This function does not require any parameters.
Return Value
Returns the (delicious) value of π (pi).
[editor's note: please remove 'delicious', astrophysics has no space for humor.]
[author's note: No problem, I'll take care of it tomorrow.]
Error Handling
- Throws an error if any arguments are provided.
pl2nvc
Function Documentation
Functionality
The pl2nvc
function computes a unit normal vector and constant that define a specified plane. This is particularly useful in computational geometry involving planes.
Usage Example
const plane = { normal: [1, 2, 3], constant: 4 };
const {normal, constant} = spice.pl2nvc(plane);
Parameters
-
plane
: The plane object defined by its normal vector and a constant representing a SPICE plane.
Return Value
Returns an object with the normalized vector and adjusted constant of the plane.
Error Handling
- Throws an error if incorrect arguments are provided.
pl2nvp
Function Documentation
Functionality
The pl2nvp
function computes a unit normal vector and a point that define a specified plane. This is valuable in spatial geometry and computational mathematics.
Usage Example
const plane = { normal: [1, 2, 3], constant: 4 };
const {normal, point} = spice.pl2nvp(plane);
Parameters
-
plane
: A plane object defined by a normal vector and a constant of a SPICE plane.
Return Value
Returns an object with a normalized vector and a point that represent the plane.
Error Handling
- Throws an error if incorrect arguments are provided or if the plane cannot be properly defined.
pl2psv
Function Documentation
Functionality
The pl2psv
function computes a point and two orthogonal spanning vectors that generate a specified plane. This function is essential in computational geometry to represent planes in three-dimensional space.
Usage Example
const plane = { normal: [1, 2, 3], constant: 4 };
const {point, span1, span2} = spice.pl2psv(plane);
Parameters
-
plane
: A plane object defined by a normal vector and a constant.
Return Value
Returns an object with a point and two spanning vectors representing the plane ('point', 'span1', and 'span2' key/value pairs).
Error Handling
- Throws an error if incorrect arguments are provided or if the plane cannot be properly represented.
prop2b
Function Documentation
Functionality
The prop2b
function computes the state (position and velocity) of a massless body at a specified time, using a two-body force model. This is useful for calculating orbits around a central mass.
Usage Examples
const gm = 398600.435436096;
const state = {"r": [7000, 0, 0], "v": [0, 7.546049108166282, 0]};
const dt = 3600;
let {r, v} = spice.prop2b(gm, state, dt);
Parameters
-
gm
: Gravitational constant times the mass of the central body. -
state
: Initial state of the body, containingr
(position vector) andv
(velocity vector). -
dt
: Time increment at which the new state is computed.
Return Value
Returns the new state of the body after time dt
, containing r
(position) and v
(velocity) vectors.
Error Handling
- Throws an error for degenerate orbits or incorrect dimensions/types of input vectors.
psv2pl
Function Documentation
Functionality
The psv2pl
function creates a SPICE plane from a point and two spanning vectors.
Usage Example
const point = [1, 2, 3];
const span1 = [1, 1, 0];
const span2 = [0, 1, 1];
const plane = spice.psv2pl(point, span1, span2);
// 'plane' will be an object of the form {"normal":[x, y, z], "constant":c}, which is
// the form expected by other js-spice functions.
Parameters
-
point
: A three-element array representing a point on the plane. -
span1
: A three-element array representing the first spanning vector. -
span2
: A three-element array representing the second spanning vector.
Return Value
Returns an object representing the plane, with properties for the normalized normal vector and the plane constant.
Error Handling
- Throws an error if incorrect arguments are provided.
pxform
Function Documentation
Functionality
The pxform
function calculates the transformation matrix that converts position vectors from one specified reference frame to another at a given epoch.
Usage Example
const et = 0; // Epoch in ephemeris seconds past J2000
const r = spice.pxform('IAU_EARTH', 'J2000', et);
// r is now a rotation matrix of the form [[a,b,c],[d,e,f],[g,h,i]]
Parameters
-
from
: The name of the frame to transform from. -
to
: The name of the frame to transform to. -
et
: The epoch of the transformation in ephemeris seconds past J2000.
Return Value
Returns a 3x3 transformation matrix.
Error Handling
- Throws an error if the specified frames are not recognized or the transformation cannot be computed.
pxfrm2
Function Documentation
Functionality
The pxfrm2
function returns the matrix that transforms position vectors from one specified frame to another at different epochs. This is particularly useful when dealing with frames that are moving with respect to each other.
Usage Example
await getKernels('pck/a_old_versions/pck00009.tpc', 'kernel_cache/data/naif/generic_kernels');
let r = spice.pxfrm2('IAU_EARTH', 'J2000', etfrom, etto);
Parameters
-
from
: The name of the frame to transform from. -
to
: The name of the frame to transform to. -
etfrom
: Epoch in ephemeris seconds past J2000 to evaluate thefrom
frame. -
etto
: Epoch in ephemeris seconds past J2000 to evaluate theto
frame.
Return Value
Returns a 3x3 matrix representing the rotation from the from
frame to the to
frame.
Error Handling
- Throws an error if incorrect or invalid frame names are provided, or if the epochs are invalid.
q2m
Function Documentation
Functionality
The q2m
function calculates the rotation matrix corresponding to a specified unit quaternion. It is typically used to convert quaternion representations of rotations into matrix form, which is more suitable for certain types of calculations.
Usage Example
const s = Math.sqrt(2) / 2;
const q = {"x": 0, "y": 0, "z": -s, "w": s};
const m = spice.q2m(q);
// m now contains a 3x3 array of matrix values.
Parameters
-
q
: The input quaternion represented as an object withx
,y
,z
, andw
components.
Return Value
Returns a 3x3 rotation matrix corresponding to the given quaternion.
Error Handling
- Throws an error if the input is not a unit quaternion.
- Handles cases where input quaternion components are not in the expected format.
Note
This function is essential for converting quaternion representations, commonly used in spacecraft attitude control and 3D graphics, into rotation matrices that can be easily used for further geometric transformations.
qxq
Function Documentation
Functionality
The qxq
function multiplies two quaternions, q1
and q2
. This operation is essential in computational geometry, particularly in spacecraft attitude and orientation calculations.
Usage Example
const q1 = {"x":1, "y":0, "z":0, "w":0};
const q2 = {"x":0, "y":1, "z":0, "w":0};
const q_x_q = spice.qxq(q1, q2);
Parameters
-
q1
: The first quaternion. -
q2
: The second quaternion.
Return Value
Returns the product of the two quaternions as a new quaternion.
Error Handling
- Throws an error if incorrect arguments are provided.
`recrad`` Function Documentation
Functionality
recrad
converts rectangular coordinates to range, right ascension, and declination.
Usage Example
const rec = [0,0.7071067811847432,0.7071067811883519];
const rad = spice.recrad(rec);
// rad is of the form: {"range": 1, "ra":1.5708, "dec":0.785398}
Parameters
-
rec
: An array representing rectangular coordinates.
Return Value
Returns an object containing the range, right ascension, and declination derived from the input rectangular coordinates.
Error Handling
This function throws a TypeError if incorrect arguments are provided. It does not throw any SPICE errors.
raxisa
Function Documentation
Functionality
The raxisa
function computes the axis of the rotation given by an input matrix and the angle of rotation. It is useful for understanding and manipulating rotational transformations.
Usage Example
const m = [[0, 1, 0], [-1, 0, 0], [0, 0, 1]];
const { axis, angle } = spice.raxisa(m);
Parameters
-
matrix
: A 3x3 rotation matrix.
Return Value
An object containing:
-
axis
: The rotation axis as a 3-element array. -
angle
: The rotation angle in radians.
Error Handling
This function validates input types and values, and throws a TypeError
in case of invalid inputs. It throws a generic error when the input is not a rotation matrix.
recazl
Functionality
The recazl
function converts rectangular coordinates of a point to range, azimuth, and elevation.
Usage
const rec = [1, 1, 1];
const actual = spice.recazl(rec, false, false);
Parameters
-
rectan
: An array of rectangular coordinates of the point. -
azccw
: A boolean flag indicating if the azimuth increases in the clockwise direction. -
elplsz
: A boolean flag indicating if the elevation increases towards the +Z axis.
Return
Returns an object containing the range, azimuth, and elevation.
Error Handling
This function throws errors if invalid argument types are provided.
reccyl
Function Documentation
Functionality
The reccyl
function converts rectangular coordinates to cylindrical coordinates.
Usage Example
const rec = [1, 1, 1];
const cyl = spice.reccyl(rec);
// expected = {"r": 1.4142, "clon":45.0*rpd, "z":1.0};
Parameters
-
rec
: The rectangular coordinates of the point.
Return Value
Returns an object containing the cylindrical coordinates r
(radius), clon
(cylindrical longitude), and z
(height).
Error Handling
This function throws a TypeError
if incorrect arguments are provided. It does not throw a SPICE error.
recgeo
Function Documentation
Functionality
The recgeo
function converts rectangular coordinates to geodetic coordinates, defined by the equatorial radius and flattening coefficient of a reference spheroid.
Usage Example
const radius = 6378.2064;
const f = 1./294.9787;
const rec = [0.000, 6378.206, 0.000];
const geo = spice.recgeo(rec, radius, f);
// Expected { "lon": 90.0 * rpd, "lat":0, "alt":0 }
Parameters
-
rectan
: Array of rectangular coordinates [X, Y, Z]. -
re
: Equatorial radius of the reference spheroid (in kilometers). -
f
: Flattening coefficient.
Return Value
Returns an object containing longitude (lon
), latitude (lat
), and altitude (alt
).
Error Handling
This function throws an error if incorrect argument types are provided.
reclat
Function Documentation
Functionality
The reclat
function converts rectangular coordinates to latitudinal coordinates.
Usage Example
const rec = [-55658.44323296, -379226.32931475, -126505.93063865];
const lat = spice.reclat(rec);
// expected = {"radius": 403626.33912495, "lon":-98.34959789*rpd, "lat":-18.26566077*rpd};
Parameters
-
rec
: Array of three elements representing the rectangular coordinates (X, Y, Z).
Return Value
Returns an object with latitudinal coordinates:
-
radius
: The distance of the point from the origin. -
lon
: Longitude of the point in radians. -
lat
: Latitude of the point in radians.
Error Handling
This function throws a TypeError
if the input arguments are not as expected.
recpgr
Function Documentation
Functionality
The recpgr
function converts rectangular coordinates to planetographic coordinates.
Usage Example
await getKernels('pck/a_old_versions/pck00008.tpc');
const re = 3396.190;
const rp = 3376.200;
const f = (re-rp)/re;
const rec = [0.000, 3396.190, 0.000];
const actual = spice.recpgr('mars', rec, re, f);
// expected = {"lon": 270.000 * rpd, "lat":0, "alt":0};
Parameters
-
body_str
: Name of the central body. -
rectan
: Rectangular coordinates of a point. -
re
: Equatorial radius of the reference spheroid in km. -
f
: Flattening coefficient.
Return Value
Returns planetographic coordinates (longitude, latitude, altitude) of the input point.
Error Handling
This function throws an error if invalid arguments are provided.
recrad
Function Documentation
Functionality
The recrad
function converts rectangular coordinates to spherical coordinates (range, right ascension, and declination).
Usage Example
const rec = [0, 0.7071067811847432, 0.7071067811883519];
const rad = spice.recrad(rec);
// expected = {"range": 1, "ra": 90.0 * rpd, "dec": 45.0 * rpd};
Parameters
-
rectan
: Array of rectangular coordinates. -
range
: Distance of the point from the origin. -
ra
: Right ascension of the point. -
dec
: Declination of the point.
Return Value
Returns an object containing the spherical coordinates (range, right ascension, and declination).
Error Handling
This function throws an error if invalid arguments are provided.
recsph
Function Documentation
Functionality
The recsph
function converts rectangular coordinates to spherical coordinates.
Usage Example
const rec = [0, 0.7071067811847432, 0.7071067811883519];
const sph = spice.recsph(rec);
// expected = {"r": 1, "colat": 45.0 * rpd, "slon": 90.0 * rpd};
Parameters
-
rectan
: Rectangular coordinates of a point.
Return Value
Returns spherical coordinates (radius, colatitude, and slon) of the input point.
Error Handling
This function does not throw a SPICE error.
reset
Function Documentation
Functionality
The reset
function is used primarily for unit testing. It clears any SPICE error.
Usage Example
// Signal an error
spice.sigerr('houston, we have a problem.');
// Failure is not an option
spice.reset();
Error Handling
This function does not throw an error.
rotate
Function Documentation
Functionality
The rotate
function calculates the 3x3 rotation matrix generated by a rotation of a specified angle about a specified axis.
Usage Example
const r = spice.rotate(3.14159265358979/2, 3);
// expect r = [[0, 1, 0], [-1, 0, 0], [0, 0, 1]];
Parameters
-
angle
: The rotation angle in radians. -
iaxis
: The axis index about which the rotation is to be performed (1, 2, or 3).
Return Value
Returns the resulting 3x3 rotation matrix.
Error Handling
This function throws an error if invalid arguments are provided.
rpd
Function Documentation
Functionality
The rpd
function returns the number of radians per degree.
Usage Example
const degrees_per_radian = spice.rpd();
Parameters
This function does not require any parameters.
Return Value
Returns the number of radians per degree.
Error Handling
This function throws an error if any argument is provided.
sigerr
Function Documentation
Functionality
The sigerr
function is part of a node-gyp implementation that wraps the NASA/NAIF CSPICE Library. It is used to signal an error in the CSPICE system.
Usage Example
// Signal a SPICE error with a custom message
spice.sigerr('houston, we have a problem.');
// Check if an error has been signaled
const failed = spice.failed();
// we should expect 'failed' to be true now.
spice.reset();
Parameters
-
err
: A string message that describes the error. This message is passed to the CSPICE system.
Error Handling
- The function will signal an error to the CSPICE system using the provided message.
- No return value is expected as the primary purpose is to signal the error state.
Source and Test Files
- The implementation of
sigerr
can be found insigerr.cpp
, which is part of the node-gyp implementation. - Unit tests are provided in
Sigerr.js
, demonstrating the usage and expected behavior of the function.
External Reference
- For more information on the underlying CSPICE function
sigerr_c
, refer to NASA/NAIF Toolkit Documentation.
spd
Function Documentation
Functionality
The spd
function is a part of the node-gyp implementation that interfaces with the NASA/NAIF CSPICE Library. This function returns the number of seconds in a day, a fundamental constant in time-related computations in astrophysics and space science.
Usage Example
// Call spd to get the number of seconds in a day
const secondsInADay = spice.spd();
Parameters
- The function expects no arguments.
Return Value
- Returns the number of seconds in a day, as a numeric value.
Error Handling
- Throws an error if any arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spd_c
, refer to NASA/NAIF Toolkit Documentation.
sphrec
Function Documentation
Functionality
The sphrec
function converts spherical coordinates (radius, colatitude, and longitude) to rectangular (Cartesian) coordinates.
Usage Example
// Define spherical coordinates
const sph = {"r": 1, "colat": 45.0 * (Math.PI / 180), "slon": 90.0 * (Math.PI / 180)};
// Convert to rectangular coordinates
const rec = spice.sphrec(sph);
// Expect rec = [0, 0.7071, 0.7071]
Parameters
- An object
sph
containing the following key/value pairs:-
r
: Radius - distance from the origin. -
colat
: Colatitude - angle measured from the positive Z-axis. -
slon
: Longitude - angle measured from the positive X-axis in the XY-plane.
-
Return Value
- Returns an array of rectangular coordinates
[x, y, z]
corresponding to the input spherical coordinates.
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
sphrec_c
, refer to NASA/NAIF Toolkit Documentation.
spkcls
Function Documentation
Functionality
The spkcls
function closes an open SPK (Spacecraft and Planet Kernel) file identified by its handle.
Usage Example
const handle = spice.spkopenw('new_spk_file.bsp');
spice.spkcls(handle);
// Further write attempts here would fail, as the spk file was closed.
Parameters
-
handle
: An integer representing the handle of the SPK file to be closed.
Error Handling
- Throws an error if an incorrect or invalid handle is provided.
External Reference
- For more information on the underlying CSPICE function
spkcls_c
, refer to NASA/NAIF Toolkit Documentation.
spkcpo
Function Documentation
Functionality
The spkcpo
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the state (position and velocity) of a target body relative to an observer, where the observer's position is specified in a fixed reference frame.
Usage Example
// Define parameters for the SPK "computation of position only" function
const params = {
target: 'Mars',
et: 123456789.0,
outref: 'J2000',
refloc: 'OBSERVER',
abcorr: 'NONE',
obspos: [0.0, 0.0, 0.0],
obsctr: 'Earth',
obsref: 'J2000'
};
// Compute the state of the target
const {state, lt} = spice.spkcpo(params);
// state is returned as { "r": r, "v": v}
Parameters
-
params
: An object containing the following key/value pairs:-
target
: The target body. -
et
: The ephemeris time at which the state is to be computed. -
outref
: The reference frame in which to express the observer's state. -
refloc
: The location to use for the reference point. -
abcorr
: The aberration correction flag. -
obspos
: The position of the observer in the specified reference frame. -
obsctr
: The center of motion of the observer. -
obsref
: The reference frame of the observer's state.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkcpo_c
, refer to NASA/NAIF Toolkit Documentation.
spkcpt
Function Documentation
Functionality
The spkcpt
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the state (position and velocity) of a target with constant position in a specified reference frame relative to an observer.
Usage Example
// Define parameters for the SPK "computation of position and time" function
const params = {
trgpos: [1.0, 2.0, 3.0],
trgctr: 'Earth',
trgref: 'J2000',
et: 123456789.0,
outref: 'J2000',
refloc: 'OBSERVER',
abcorr: 'NONE',
obsrvr: 'Mars'
};
// Compute the state of the target
const {state, lt} = spice.spkcpt(params);
Parameters
-
params
: An object containing the following key/value pairs:-
trgpos
: Target position. -
trgctr
: Target center. -
trgref
: Target reference frame. -
et
: The ephemeris time at which the state is to be computed. -
outref
: The reference frame in which to express the observer's state. -
refloc
: The location to use for the reference point. -
abcorr
: The aberration correction flag. -
obsrvr
: The observer.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkcpt_c
, refer to NASA/NAIF Toolkit Documentation.
spkcvo
Function Documentation
Functionality
The spkcvo
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the state (position and velocity) of a target body relative to an observer. The observer has a constant velocity in a specified reference frame.
Usage Example
// Define parameters for the SPK "computation of velocity only" function
const params = {
target: 'Mars',
et: 123456789.0,
outref: 'J2000',
refloc: 'OBSERVER',
abcorr: 'NONE',
obssta: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
obsepc: 123456789.0,
obsctr: 'Earth',
obsref: 'J2000'
};
// Compute the state of the target
const {state, lt} = spice.spkcvo(params);
Parameters
-
params
: An object containing the following key/value pairs:-
target
: The target body. -
et
: The ephemeris time at which the state is to be computed. -
outref
: The reference frame in which to express the observer's state. -
refloc
: The location to use for the reference point. -
abcorr
: The aberration correction flag. -
obssta
: The state of the observer in the specified reference frame. -
obsepc
: The ephemeris time associated withobssta
. -
obsctr
: The center of motion of the observer. -
obsref
: The reference frame of the observer's state.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkcvo_c
, refer to NASA/NAIF Toolkit Documentation.
spkcvt
Function Documentation
Functionality
The spkcvt
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the state (position and velocity) of a target body having constant velocity in a specified reference frame relative to an observer.
Usage Example
// Define parameters for the SPK "computation of velocity and time" function
const params = {
trgsta: [1.0, 2.0, 3.0, 0.1, 0.2, 0.3],
trgepc: 123456789.0,
trgctr: 'Earth',
trgref: 'J2000',
et: 123456789.0,
outref: 'J2000',
refloc: 'OBSERVER',
abcorr: 'NONE',
obsrvr: 'Mars'
};
// Compute the state of the target
const {state, lt} = spice.spkcvt(params);
Parameters
-
params
: An object containing the following key/value pairs:-
trgsta
: The state of the target. -
trgepc
: The ephemeris time associated withtrgsta
. -
trgctr
: The center of motion of the target. -
trgref
: The reference frame of the target's state. -
et
: The ephemeris time at which the state is to be computed. -
outref
: The reference frame in which to express the observer's state. -
refloc
: The location to use for the reference point. -
abcorr
: The aberration correction flag. -
obsrvr
: The observer.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkcvt_c
, refer to NASA/NAIF Toolkit Documentation.
spkezr
Function Documentation
Functionality
The spkezr
function is a part of the node-gyp implementation wrapping the NASA/NAIF CSPICE Library. It computes the state (position and velocity) of a target body relative to an observing body, corrected for light time and stellar aberration if necessary.
Usage Example
// Define parameters for the SPK "state from ephemeris and observer" function
const params = {
targ: 'Mars',
et: 123456789.0,
ref: 'J2000',
abcorr: 'NONE',
obs: 'Earth'
};
// Compute the state of the target
const {state, lt} = spice.spkezr(params);
Parameters
-
params
: An object containing the following key/value pairs:-
targ
: The target body. -
et
: The ephemeris time at which the state is to be computed. -
ref
: The reference frame in which to express the state. -
abcorr
: The aberration correction flag. -
obs
: The observing body.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkezr_c
, refer to NASA/NAIF Toolkit Documentation.
spkgeo
Function Documentation
Functionality
The spkgeo
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the geometric state (position and velocity) of a target body relative to an observing body in a specified reference frame.
Usage Example
// Define parameters for the SPK "geometric state" function
const params = {
targ: 499, // Mars
et: 123456789.0,
ref: 'J2000',
obs: 399 // Earth
};
// Compute the geometric state of the target
const {state, lt} = spice.spkgeo(params);
Parameters
-
params
: An object containing the following key/value pairs:-
targ
: The NAIF ID of the target body. -
et
: The ephemeris time at which the state is to be computed. -
ref
: The reference frame in which to express the state. -
obs
: The NAIF ID of the observing body.
-
Return Value
- Returns an object containing the target's state and light time (
lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkgeo_c
, refer to NASA/NAIF Toolkit Documentation.
spkgps
Function Documentation
Functionality
The spkgps
function is part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library. It computes the geometric position of a target body relative to an observing body in a specified reference frame, corrected for light time if necessary.
Usage Example
// Define parameters for the SPK "geometric position" function
const params = {
targ: 499, // Mars
et: 123456789.0,
ref: 'J2000',
obs: 399 // Earth
};
// Compute the geometric position of the target
const {pos, lt} = spice.spkgps(params);
// Example assertion to check the correctness
expect(pos).to.be.an('array').with.lengthOf(3);
expectAlmostEqual(lt, 12345.678, 1e-3);
Parameters
-
params
: An object containing the following key/value pairs:-
targ
: The NAIF ID of the target body. -
et
: The ephemeris time at which the position is to be computed. -
ref
: The reference frame in which to express the position. -
obs
: The NAIF ID of the observing body.
-
Return Value
- Returns an object containing the target's position (
pos
) and light time (lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkgps_c
, refer to NASA/NAIF Toolkit Documentation.
spkobj
Function Documentation
Functionality
The spkobj
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, finds the set of ID codes of all objects in a specified SPK (Spacecraft and Planet Kernel) file.
Usage Example
// Define the SPK file name
const spkFileName = 'example.spk';
// Find the set of ID codes in the SPK file
const objectIds = spice.spkobj(spkFileName);
// An array of ID codes should be returned. e.g, [1, 2, 3, 4, ...]
Parameters
-
spkFileName
: A string representing the name of the SPK file.
Return Value
- Returns an array of ID codes for all objects found in the specified SPK file.
Error Handling
- Throws an error if incorrect arguments are provided or if the SPK file cannot be accessed.
External Reference
- For more information on the underlying CSPICE function
spkobj_c
, refer to NASA/NAIF Toolkit Documentation.
spkopn
Function Documentation
Functionality
The spkopn
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, opens a new SPK (Spacecraft and Planet Kernel) file for writing.
Usage Example
// Define parameters to create a new SPK file
const fileName = 'new_spk_file.bsp';
const internalFileName = 'Internal Name';
const numberOfCommentCharacters = 1024;
// Create the new SPK file
const handle = spice.spkopn(fileName, internalFileName, numberOfCommentCharacters);
// if no exception was thrown, handle will return as a 32-bit integer;
Parameters
-
fileName
: The name of the new SPK file. -
internalFileName
: The internal file name for the SPK file. -
numberOfCommentCharacters
: The number of comment characters to allocate.
Return Value
- Returns a handle to the newly created SPK file.
Error Handling
- Throws an error if incorrect arguments are provided or if the file cannot be opened.
External Reference
- For more information on the underlying CSPICE function
spkopn_c
, refer to NASA/NAIF Toolkit Documentation.
spkpos
Function Documentation
Functionality
The spkpos
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the position of a target body relative to an observing body, corrected for light time and stellar aberration if necessary.
Usage Example
// Define parameters for the SPK "position" function
const params = {
targ: 'Mars',
et: 123456789.0,
ref: 'J2000',
abcorr: 'NONE',
obs: 'Earth'
};
// Compute the position of the target
const {pos, lt} = spice.spkpos(params);
Parameters
-
params
: An object containing the following key/value pairs:-
targ
: The target body. -
et
: The ephemeris time at which the position is to be computed. -
ref
: The reference frame in which to express the position. -
abcorr
: The aberration correction flag. -
obs
: The observing body.
-
Return Value
- Returns an object containing the target's position (
pos
) and light time (lt
).
Error Handling
- Throws an error if incorrect or insufficient arguments are provided.
External Reference
- For more information on the underlying CSPICE function
spkpos_c
, refer to NASA/NAIF Toolkit Documentation.
spkw05
Function Documentation
Functionality
The spkw05
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, writes an SPK (Spacecraft and Planet Kernel) segment of type 5, which contains ephemeris data for a specified body.
Usage Example
// Define parameters to write an SPK segment of type 5
const handle = spice.spkopn('new_spk_file.bsp', 'Internal Name', 1024);
const body = 399; // Earth
const center = 10; // Sun
const frame = 'J2000';
const first = 0.0; // Start time
const last = 86400.0; // End time
const segid = 'Segment ID';
const gm = 398600.435436; // GM for Earth
const data = [{state: {r: [x, y, z], v: [dx, dy, dz]}, et: et}, ...]; // Ephemeris data
// Write the segment
spice.spkw05(handle, body, center, frame, first, last, segid, gm, data);
Parameters
-
handle
: The handle of the SPK file to which the segment is to be written. -
body
: The NAIF ID of the body. -
center
: The NAIF ID of the center body. -
frame
: The reference frame. -
first
,last
: The start and end times of the segment. -
segid
: The segment identifier. -
gm
: The gravitational parameter. -
data
: An array of state and epoch pairs.
Return Value
- The function does not return a value but writes the segment to the SPK file.
Error Handling
- Throws an error if incorrect arguments are provided or if there is an issue with writing to the file.
External Reference
- For more information on the underlying CSPICE function
spkw05_c
, refer to NASA/NAIF Toolkit Documentation.
str2et
Function Documentation
Functionality
The str2et
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, converts a time string to ephemeris time (ET), which is the number of seconds past the J2000 epoch.
Usage Example
// Define a time string
const timeString = 'Jan 1, 2023 12:00:00 TDB';
// Convert the time string to ephemeris time
const et = spice.str2et(timeString);
Parameters
-
timeString
: A string representing a time in any format recognized by SPICE.
Return Value
- Returns the ephemeris time (ET) as a numeric value, corresponding to the input time string.
Error Handling
- Throws an error if the time string is not in a recognizable format or if other issues occur during conversion.
External Reference
- For more information on the underlying CSPICE function
str2et_c
, refer to NASA/NAIF Toolkit Documentation.
sxform
Function Documentation
Functionality
The sxform
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the state transformation matrix from one reference frame to another at a specified epoch.
Usage Example
// Define parameters for the state transformation matrix computation
const fromFrame = 'IAU_EARTH';
const toFrame = 'J2000';
const ephemerisTime = 123456789.0; // Example ephemeris time
// Compute the state transformation matrix
const stateTransformMatrix = spice.sxform(fromFrame, toFrame, ephemerisTime);
// stateTransformMatrix will be a 6 x 6 array.
Parameters
-
fromFrame
: The name of the reference frame to transform from. -
toFrame
: The name of the reference frame to transform to. -
ephemerisTime
: The ephemeris time at which the transformation is computed.
Return Value
- Returns a 6x6 state transformation matrix.
Error Handling
- Throws an error if incorrect arguments are provided or if the transformation cannot be computed.
External Reference
- For more information on the underlying CSPICE function
sxform_c
, refer to NASA/NAIF Toolkit Documentation.
timout
Function Documentation
Functionality
The timout
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, converts an input epoch represented in TDB seconds past the TDB epoch of J2000 to a character string formatted according to a user's format picture.
Usage Example
// Define an ephemeris time and a format picture
const et = 757234367.172871; // Example ephemeris time
const formatPicture = 'MON DD,YYYY HR:MN:SC.#### (TDB) ::TDB';
// Convert the ephemeris time to a formatted string
const formattedTime = spice.timout(et, formatPicture);
// formattedTime is now 'DEC 30,2023 18:52:47.1728 (TDB)'
Parameters
-
et
: The ephemeris time in TDB seconds past the J2000 epoch. -
formatPicture
: A string specifying the format for the output string.
Return Value
- Returns a formatted time string according to the specified format.
Error Handling
- Throws an error if incorrect arguments are provided or if the formatting fails.
External Reference
- For more information on the underlying CSPICE function
timout_c
, refer to NASA/NAIF Toolkit Documentation.
twopi
Function Documentation
Functionality
The twopi
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, returns the value of (2\pi) (twice the value of pi).
Usage Example
// Call twopi to get the value of 2*pi
const twoPiValue = spice.twopi();
Parameters
- The function expects no arguments.
Return Value
- Returns the numeric value of (2\pi).
Error Handling
- Throws an error if any arguments are provided.
External Reference
- For more information on the underlying CSPICE function
twopi_c
, refer to NASA/NAIF Toolkit Documentation.
unload
Function Documentation
Functionality
The unload
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, unloads a SPICE kernel from the kernel pool.
Usage Example
// Define the path of the SPICE kernel to unload
const kernelPath = 'path/to/spice_kernel.bsp';
// Unload the specified kernel
spice.unload(kernelPath);
Parameters
-
kernelPath
: A string representing the path to the kernel file to be unloaded.
Return Value
- The function does not return a value but unloads the specified kernel from the pool.
Error Handling
- Throws an error if incorrect arguments are provided or if the kernel cannot be unloaded.
External Reference
- For more information on the underlying CSPICE function
unload_c
, refer to NASA/NAIF Toolkit Documentation.
vadd
Function Documentation
Functionality
The vadd
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, adds two double precision 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const vector1 = [1, 2, 3];
const vector2 = [1, 1, 1];
// Perform vector addition
const resultVector = spice.vadd(vector1, vector2);
// expefcted result: [2, 3, 4];
Parameters
-
vector1
: The first 3-dimensional vector. -
vector2
: The second 3-dimensional vector.
Return Value
- Returns the result of vector addition as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vadd_c
, refer to NASA/NAIF Toolkit Documentation.
vcrss
Function Documentation
Functionality
The vcrss
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the cross product of two 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const vector1 = [0, 1, 0];
const vector2 = [1, 0, 0];
// Compute the cross product
const crossProduct = spice.vcrss(vector1, vector2);
// Expect [0, 0, -1];
Parameters
-
vector1
: The first 3-dimensional vector. -
vector2
: The second 3-dimensional vector.
Return Value
- Returns the cross product of the two vectors as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vcrss_c
, refer to NASA/NAIF Toolkit Documentation.
vdist
Function Documentation
Functionality
The vdist
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, calculates the distance between two 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const vector1 = [1.0, 0.0, 0.0];
const vector2 = [0.0, 1.0, 0.0];
// Calculate the distance between the vectors
const distance = spice.vdist(vector1, vector2);
// expect 1.414214 sqrt(2)
Parameters
-
vector1
: The first 3-dimensional vector. -
vector2
: The second 3-dimensional vector.
Return Value
- Returns the distance between the two vectors as a numeric value.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vdist_c
, refer to NASA/NAIF Toolkit Documentation.
vdot
Function Documentation
Functionality
The vdot
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the dot product of two double precision, 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const vector1 = [1, 2, 3];
const vector2 = [4, 5, 6];
// Compute the dot product
const dotProduct = spice.vdot(vector1, vector2);
// Exptected result is 1*4 + 2*5 + 3*6 = 32
Parameters
-
vector1
: The first 3-dimensional vector. -
vector2
: The second 3-dimensional vector.
Return Value
- Returns the dot product of the two vectors as a numeric value.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vdot_c
, refer to NASA/NAIF Toolkit Documentation.
vequ
Function Documentation
Functionality
The vequ
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, makes one double precision 3-dimensional vector equal to another.
Usage Example
// Define a 3-dimensional vector
const vin = [1, 2, 3];
// Make a new vector equal to the original
const resultVector = spice.vequ(vin);
// expected resultVector = [1, 2, 3];
Parameters
-
vin
: The original 3-dimensional vector.
Return Value
- Returns a new 3-dimensional vector that is equal to the original vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vequ_c
, refer to NASA/NAIF Toolkit Documentation.
vhat
Function Documentation
Functionality
The vhat
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, finds the unit vector along a double precision 3-dimensional vector.
Usage Example
// Define a 3-dimensional vector
const vector = [5.0, 12.0, 0.0];
// Compute the unit vector
const unitVector = spice.vhat(vector);
// expected UnitVector = [0.38461538, 0.92307692, 0.00000000];
Parameters
-
vector
: The original 3-dimensional vector.
Return Value
- Returns the unit vector along the direction of the original vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vhat_c
, refer to NASA/NAIF Toolkit Documentation.
vlcom
Function Documentation
Functionality
The vlcom
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes a vector linear combination of two double precision, 3-dimensional vectors.
Usage Example
// Define scalar coefficients and 3-dimensional vectors
const a = 1;
const v1 = [1, 2, 3];
const b = 2;
const v2 = [4, 5, 6];
// Compute the vector linear combination
const linearCombination = spice.vlcom(a, v1, b, v2);
// expected linearCombination = [1*1 + 2*4, 1*2 + 2*5, 1*3 + 2*6] - [9, 12, 15]
Parameters
-
a
: The scalar coefficient for the first vector. -
v1
: The first 3-dimensional vector. -
b
: The scalar coefficient for the second vector. -
v2
: The second 3-dimensional vector.
Return Value
- Returns the vector linear combination as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vlcom_c
, refer to NASA/NAIF Toolkit Documentation.
vlcom3
Function Documentation
Functionality
The vlcom3
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the vector linear combination of three double precision, 3-dimensional vectors.
Usage Example
// Define scalar coefficients and 3-dimensional vectors
const a = 1;
const v1 = [1, 2, 3];
const b = 2;
const v2 = [4, 5, 6];
const c = 3;
const v3 = [7, 8, 9];
// Compute the vector linear combination
const linearCombination = spice.vlcom3(a, v1, b, v2, c, v3);
// expected linearCombination = [1*1 + 2*4 + 3*7, 1*2 + 2*5 + 3*8, 1*3 + 2*6 + 3*9] - [34, 40, 46]
Parameters
-
a
,b
,c
: The scalar coefficients for the vectors. -
v1
,v2
,v3
: The 3-dimensional vectors.
Return Value
- Returns the vector linear combination as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vlcom3_c
, refer to NASA/NAIF Toolkit Documentation.
vminus
Function Documentation
Functionality
The vminus
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, negates a double precision 3-dimensional vector.
Usage Example
// Define a 3-dimensional vector
const vector = [1, 2, 3];
// Negate the vector
const negatedVector = spice.vminus(vector);
// expect NegatedVector = [-1, -2, -3];
Parameters
-
vector
: The original 3-dimensional vector.
Return Value
- Returns the negated vector as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vminus_c
, refer to NASA/NAIF Toolkit Documentation.
vnorm
Function Documentation
Functionality
The vnorm
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the magnitude of a double precision 3-dimensional vector.
Usage Example
// Define a 3-dimensional vector
const vector = [1, 2, 2];
// Compute the magnitude of the vector
const magnitude = spice.vnorm(vector);
// expect magnitude = sqrt(1^2 + 2^2 + 2^2)
Parameters
-
vector
: The 3-dimensional vector.
Return Value
- Returns the magnitude of the vector as a numeric value.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vnorm_c
, refer to NASA/NAIF Toolkit Documentation.
vpack
Function Documentation
Functionality
The vpack
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, packs three scalar components into a 3-dimensional vector.
Usage Example
// Define three scalar components
const x = -1;
const y = -2;
const z = -3;
// Pack them into a vector
const vector = spice.vpack(x, y, z);
// expect vector = [-1, -2, -3];
Parameters
-
x
: The x-component of the vector. -
y
: The y-component of the vector. -
z
: The z-component of the vector.
Return Value
- Returns a 3-dimensional vector array
[x, y, z]
.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vpack_c
, refer to NASA/NAIF Toolkit Documentation.
vpack
Function Documentation
Functionality
The vpack
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, packs three scalar components into a 3-dimensional vector.
Usage Example
// Define three scalar components
const x = -1;
const y = -2;
const z = -3;
// Pack them into a vector
const vector = spice.vpack(x, y, z);
// expected vector = [-1, -2, -3];
Parameters
-
x
: The x-component of the vector. -
y
: The y-component of the vector. -
z
: The z-component of the vector.
Return Value
- Returns a 3-dimensional vector array
[x, y, z]
.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vpack_c
, refer to NASA/NAIF Toolkit Documentation.
vprjp
Function Documentation
Functionality
The vprjp
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, projects a vector onto a specified plane orthogonally.
Usage Example
// Define the normal and origin of a plane
const norm = [0, 0, 1];
const orig = [0, 0, 0];
// Create the plane
const plane = spice.nvp2pl(norm, orig);
// Define a vector
const vector = [-29703.16955, 879765.72163, -12345.6789];
// Project the vector onto the plane
const projectedVector = spice.vprjp(vector, plane);
// expected projectedVector = [-29703.16955, 879765.72163, 0];
Parameters
-
vin
: The 3-dimensional vector to be projected. -
plane
: The plane onto which the vector is projected, defined by its normal and origin.
Return Value
- Returns the orthogonal projection of the vector onto the specified plane.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vprjp_c
, refer to NASA/NAIF Toolkit Documentation.
vprjpi
Function Documentation
Functionality
The vprjpi
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, finds the vector in a specified plane that maps to a specified vector in another plane under orthogonal projection.
Usage Example
// Define a vector and two planes
const vin = [0, 1, 0];
const projpl = spice.nvc2pl([0,0,1], 0); // Plane perpendicular to Z-axis
const invpl = spice.nvc2pl([0,1,0], 0); // Plane perpendicular to Y-axis
// Find the vector in the invpl plane that maps to vin in the projpl plane
const {vout, found} = spice.vprjpi(vin, projpl, invpl);
// expected Vout = [1, 0, 0], found = true
Parameters
-
vin
: The 3-dimensional vector. -
projpl
: The plane in whichvin
is considered. -
invpl
: The plane in which the output vector is to be found.
Return Value
- Returns an object containing the resulting vector and a boolean indicating if the vector was found.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vprjpi_c
, refer to NASA/NAIF Toolkit Documentation.
vproj
Function Documentation
Functionality
The vproj
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the projection of one 3-dimensional vector onto another 3-dimensional vector.
Usage Example
// Define two 3-dimensional vectors
const a = [6, 6, 6];
const b = [2, 0, 0];
// Compute the projection of vector 'a' onto vector 'b'
const projectedVector = spice.vproj(a, b);
// expected projectedVector = [6, 0, 0]; // Projection of 'a' onto 'b'
Parameters
-
a
: The first 3-dimensional vector. -
b
: The second 3-dimensional vector, onto whicha
is projected.
Return Value
- Returns the projection of
a
ontob
as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vproj_c
, refer to NASA/NAIF Toolkit Documentation.
vrel
Function Documentation
Functionality
The vrel
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the relative difference between two double precision, 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const v1 = [1, 2, 3];
const v2 = [4, 5, 6];
// Compute the relative difference between the vectors
const relativeDifference = spice.vrel(v1, v2);
// expected relativeDifference = 0.592156525463792
Parameters
-
v1
: The first 3-dimensional vector. -
v2
: The second 3-dimensional vector.
Return Value
- Returns the relative difference between
v1
andv2
as a numeric value.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vrel_c
, refer to NASA/NAIF Toolkit Documentation.
vrotv
Function Documentation
Functionality
The vrotv
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, rotates a vector about a specified axis vector by a specified angle.
Usage Example
// Define a vector, axis of rotation, and rotation angle
const v = [1, 2, 3];
const axis = [0, 0, 1]; // Z-axis
const theta = spice.halfpi(); // 90 degrees
// Rotate the vector about the axis by the angle
const rotatedVector = spice.vrotv(v, axis, theta);
// expected rotatedVector = [-2, 1, 3];
Parameters
-
v
: The 3-dimensional vector to be rotated. -
axis
: The 3-dimensional axis vector about which the rotation is performed. -
theta
: The rotation angle in radians.
Return Value
- Returns the rotated vector as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vrotv_c
, refer to NASA/NAIF Toolkit Documentation.
vscl
Function Documentation
Functionality
The vscl
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, multiplies a scalar value with a double precision 3-dimensional vector.
Usage Example
// Define a scalar and a 3-dimensional vector
const s = 2;
const v1 = [1, 2, 3];
// Perform scalar multiplication
const scaledVector = spice.vscl(s, v1);
// expected scaledVector = [2, 4, 6]
Parameters
-
s
: The scalar value. -
v1
: The original 3-dimensional vector.
Return Value
- Returns the scaled vector as a 3-dimensional array.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vscl_c
, refer to NASA/NAIF Toolkit Documentation.
vsep
Function Documentation
Functionality
The vsep
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the separation angle in radians between two double precision, 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const v1 = [1, 0, 0];
const v2 = [0, 1, 0];
// Compute the separation angle between the vectors
const separationAngle = spice.vsep(v1, v2);
// expected separationAngle = Math.PI / 2 - 90 degrees (in radians)
Parameters
-
v1
: The first 3-dimensional vector. -
v2
: The second 3-dimensional vector.
Return Value
- Returns the separation angle in radians between the two vectors.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vsep_c
, refer to NASA/NAIF Toolkit Documentation.
vsub
Function Documentation
Functionality
The vsub
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, computes the difference between two double precision, 3-dimensional vectors.
Usage Example
// Define two 3-dimensional vectors
const v1 = [1, 2, 3];
const v2 = [1, 1, 1];
// Compute the difference between the vectors
const differenceVector = spice.vsub(v1, v2);
// expected differenceVector = [0, 1, 2]
Parameters
-
v1
: The first 3-dimensional vector. -
v2
: The second 3-dimensional vector.
Return Value
- Returns the difference between
v1
andv2
as a 3-dimensional vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vsub_c
, refer to NASA/NAIF Toolkit Documentation.
vtmv
Function Documentation
Functionality
The vtmv
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, multiplies the transpose of a 3-dimensional column vector, a 3x3 matrix, and a 3-dimensional column vector, in that order.
Usage Example
// Define a 3-dimensional vector, a 3x3 matrix, and another 3-dimensional vector
const v1 = [2, 4, 6];
const matrix = [[0, 1, 0], [-1, 0, 0], [0, 0, 1]];
const v2 = [1, 1, 1];
// Perform the matrix multiplication
const result = spice.vtmv(v1, matrix, v2);
// expected result = 4
Parameters
-
v1
: The first 3-dimensional column vector. -
matrix
: The 3x3 matrix. -
v2
: The second 3-dimensional column vector.
Return Value
- Returns the result of the matrix multiplication as a numeric value.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vtmv_c
, refer to NASA/NAIF Toolkit Documentation.
vupack
Function Documentation
Functionality
The vupack
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, unpacks three scalar components from a double precision, 3-dimensional vector.
Usage Example
// Define a 3-dimensional vector
const v = [1, 2, 3];
// Unpack the scalar components from the vector
const { x, y, z } = spice.vupack(v);
// expected Components = "x":1, "y":2, "z":3
Parameters
-
v
: The 3-dimensional vector to unpack.
Return Value
- Returns an object with the scalar components
x
,y
, andz
of the vector.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vupack_c
, refer to NASA/NAIF Toolkit Documentation.
vzero
Function Documentation
Functionality
The vzero
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, checks if a double precision, 3-dimensional vector is the zero vector.
Usage Example
// Define a 3-dimensional vector
const vector = [0, 0, 0];
// Check if the vector is the zero vector
const isZero = spice.vzero(vector);
// expect isZero === true
Parameters
-
vector
: The 3-dimensional vector to check.
Return Value
- Returns a boolean value
true
if the vector is the zero vector, otherwisefalse
.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
vzero_c
, refer to NASA/NAIF Toolkit Documentation.
xpose
Function Documentation
Functionality
The xpose
function, part of a node-gyp implementation wrapping the NASA/NAIF CSPICE Library, transposes a 3x3 double precision matrix.
Usage Example
// Define a 3x3 matrix
const matrix = [[0, -1, 0], [0.5, 0, 0], [0, 0, 1]];
// Transpose the matrix
const transposedMatrix = spice.xpose(matrix);
// expected transposedMatrix = [[0, 0.5, 0], [-1, 0, 0], [0, 0, 1]];
Parameters
-
matrix
: The 3x3 matrix to be transposed.
Return Value
- Returns the transposed 3x3 matrix.
Error Handling
- Throws an error if incorrect arguments are provided.
External Reference
- For more information on the underlying CSPICE function
xpose_c
, refer to NASA/NAIF Toolkit Documentation.
Utility functions
js-spice
includes a few utility function that are useful when working with the module and for downloading kernel files.
cacheGenericKernel
Function Documentation
Functionality
The cacheGenericKernel
function asynchronously downloads a file from a specified URL and saves it to a given directory. This function operates asynchronously and returns a Promise. It should be used with 'await' in an async function context, or with .then()
/.catch()
to properly handle the asynchronous operation. The function skips the download if the file already exists. If 'dirRelative' is not provided, the file is saved using 'urlRelative' as a relative path. Upon successful download, or if the file already exists, it returns the absolute path of the file on the local file system.
Usage Example
const { downloadKernel } = require('@gamergenic/js-spice');
// Async function to download and cache a kernel
async function downloadKernel() {
const urlRelative = 'path/to/kernel';
const dirRelative = 'directory/to/save';
try {
const filePath = await cacheGenericKernel(urlRelative, dirRelative);
console.log(`Kernel saved at: ${filePath}`);
} catch (error) {
console.error(`Error downloading kernel: ${error.message}`);
}
// now you can use the kernel file (supply it to furnsh, etc)
// ...
}
// Call the async function
downloadKernel();
Parameters
-
urlRelative
: The relative URL path from the base URL. -
dirRelative
: (Optional) The relative directory path from the base directory.
Return Value
- Returns a Promise that resolves to the absolute path of the file on the local file system.
Error Handling
- Logs and throws an error if there are issues during the download process.
Reminder
- Remember that this is an asynchronous function. Use
await
within an async function, or.then()
/.catch()
for handling the Promise.
External Reference
- Utilizes Axios for HTTP requests and Node.js File System (fs) module for handling files.
et_now
Function Documentation
Functionality
The et_now
function retrieves the current time in Ephemeris Time (ET) format using the SPICE toolkit. Ephemeris Time is a time scale commonly used in planetary science, especially for solar system dynamics.
Usage Example
const {et_now} = require('@gamergenic/js-spice');
// Retrieve the current time in Ephemeris Time (ET) format
const currentET = et_now();
Parameters
- The function expects no arguments.
Return Value
- Returns the current time in Ephemeris Time (ET) format as a numeric value.
Error Handling
- The function relies on SPICE's
str2et
for time conversion, which may throw an error for invalid time formats or other internal issues.
External Reference
- This function utilizes the
str2et
function from the SPICE toolkit for the time conversion. More information on thestr2et
function can be found in the SPICE toolkit documentation.
getGeophysicalConstants
Function Documentation
Functionality
The getGeophysicalConstants
function asynchronously retrieves geophysical constants for Earth using the SPICE toolkit. The function operates asynchronously and returns a Promise. It should be used with 'await' in an async function context or with .then()
/.catch()
to handle the asynchronous operation properly. If getCachedKernel
is true, the function ensures the specified kernel file is downloaded and available before fetching constants.
Usage Example
const { getGeophysicalConstants } = require('@gamergenic/js-spice');
// Async function to retrieve geophysical constants
async function retrieveConstants() {
try {
const constants = await getGeophysicalConstants(true);
console.log(`Geophysical Constants: `, constants);
} catch (error) {
console.error(`Error retrieving constants: ${error.message}`);
}
// geophysical constants should now be downloaded, cached locally, and supplied to furnsh
}
// Call the async function
retrieveConstants();
Parameters
-
getCachedKernel
: Flag to determine whether to download and cache the kernel file. -
kernelToUse
: (Optional) The kernel file to use. Defaults to 'pck/geophysical.ker'. -
kernelCacheLocation
: (Optional) Location to cache the kernel file. Defaults to 'data/naif/generic_kernels/${file}'.
Return Value
- Returns a Promise that resolves to an object containing key geophysical constants such as j2, j3, j4, ke, qo, so, er, ae.
Error Handling
- Logs and throws an error if there are issues during the process.
Reminder
- Remember that this is an asynchronous function. Use
await
within an async function, or.then()
/.catch()
for handling the Promise.
External Reference
- Utilizes SPICE toolkit functions for fetching geophysical constants.
getKernels
Function Documentation
Functionality
The getKernels
function asynchronously loads and processes SPICE kernel files, returning a Promise. It should be used with 'await' or .then()
to properly handle the asynchronous operation. The function checks if the provided kernelsToLoad
is a string or an array, and then proceeds to load and process each kernel file. If kernelCacheLocation
is not provided, it defaults to 'data/naif/generic_kernels'.
Usage Example
const { getKernels } = require('@gamergenic/js-spice');
// Async function to load kernel files
async function loadKernels() {
const kernels = ['spk/planets.bsp', 'lsk/naif0012.tls'];
try {
await getKernels(kernels);
console.log('Kernels loaded successfully.');
} catch (error) {
console.error(`Error loading kernels: ${error.message}`);
}
// the kernels should now be downloaded, locally cached, and furnsh'ed.
// ...
}
// Call the async function
loadKernels();
Parameters
-
kernelsToLoad
: The kernel file(s) to load. Can be a string or an array of strings. -
kernelCacheLocation
: (Optional) The location where the kernel cache is stored. Defaults to 'data/naif/generic_kernels' if not specified.
Return Value
- Returns a Promise that resolves when the kernel files are loaded and processed.
Error Handling
- Logs and throws an error if there are issues during the process.
Reminder
- Remember that this is an asynchronous function. Use
await
within an async function, or.then()
for handling the Promise.
External Reference
- Utilizes the
cacheGenericKernel
function to cache andspice.furnsh
to process the kernel files.
js-spice
to wrap additional SPICE functions
Extending Additional SPICE functions can be be wrapped for JavaScript use if you add a C++ implementation. To add a new function, copy the implementation of an existing function. It should be (mostly) apparent how to modify the code to wrap the new function.
Example implementation:
#include "wrapped/spkgeo.h"
#include "utility/err.h"
extern "C" {
#include <SpiceUsr.h>
}
#include "utility/pack.h"
#include "utility/unpack.h"
Napi::Value spkgeo(const Napi::CallbackInfo& info) {
Napi::Env env = info.Env();
Napi::HandleScope scope(env);
// Parameters that will be passed into SPICE
SpiceInt targ, obs;
std::string ref;
SpiceDouble et;
if(
// Unpack js parameters into Spice-worthy representations
Unpack("spkgeo", info)
.i(targ, "targ") // "i" = unpack the next param as an integer
.et(et) // "et" = unpack next param as an ephemeris time
.str(ref, "ref") // "str" = unpack next param as a string
.i(obs, "obs") // "i" = unpack next param as integer
.check( [=](const std::string& error) {
// lambda handler for missing/extra args, incorrect types, etc.
Napi::TypeError::New(env, error).ThrowAsJavaScriptException();
})){
return env.Null();
}
SpiceDouble state[6];
SpiceDouble lt;
// https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/C/cspice/spkgeo_c.html
spkgeo_c(targ, et, ref.c_str(), obs, state, <);
// Pack return values as an object containing "state" and "lt" children
// where state is a type state ({r: [x, y, z], v: [dx, dy, dz]})
// and lt is a double precision numeric.
// ...with an error check for SPICE errors
return Pack(info).state(state).as("state").with(lt, "lt").check();
}
The next, after authoring your .h and .cpp wrapper, the .cpp will need added to binding.gyp
.
An include statement for the header will need added to js-spice.cpp
and a line added to export the newly defined function in the bottom half of the file. An optional unit test can be added to the /test subdirectory. The module can then be rebuilt. If you've installed node-gyp globally you can rebuild via node-gyp clean configure build
from the js-spice
directory. If it's not installed, find the binary node-gyp in the node_modules directory under js-spice
and invoke it via its full path.
License
MIT License.