Functions

This section lists the functions defined in the geomajis library.

Template functions

group Template functions

Template functions for memory allocation and FITS file writing.

Functions

template<typename T>
T *alloc_vec(SpiceLong n_x)

Contiguous memory allocation for a 1D array of type T.

Parameters:

n_x – SpiceLong - Number of elements in the array.

Returns:

Pointer to the allocated 1D array.

template<typename T>
T **alloc_arr(SpiceLong n_x, SpiceLong n_y)

Partially contiguous memory allocation for a 2D array of type T.

This function allocates memory contiguously along the first and second dimension, but not for the whole 2D array. Warning; this is not a fully contiguous allocation, and should not be used for arrays destined for FITS output, use alloc_2d_ for that purpose.

Parameters:

  • n_x – SpiceLong - Number of rows.

  • n_y – SpiceLong - Number of columns.

Returns:

Pointer to the allocated 2D array.

template<typename T>
T **alloc_2d_(long ndims, long *vdims)

Contiguous memory allocation for a 2D array of type T.

This function allocates memory contiguously for a 2D array, ensuring that the entire array is stored in a single block of memory. It is suitable for arrays destined for FITS output.

Parameters:

  • ndims – long - Number of dimensions (should be 2).

  • vdims – long* - Array containing the dimensions of the 2D array.

Returns:

Pointer to the allocated 2D array.

template<typename T>
T ***alloc_3d_(long naxis, long *naxes)

Contiguous mem.

allocation for a 3D array of type T.

This function allocates memory contiguously for a 3D array, ensuring that the entire array is stored in a single block of memory. It is suitable for arrays destined for FITS output.

Parameters:

  • naxis – long - Number of dimensions (should be 3).

  • naxes – long* - Array containing the dimensions of the 3D array.

Returns:

Pointer to the allocated 3D array.

template<typename T>
struct ima_grp
#include <libgeomajis.h>

Structure to hold image group information.

This structure holds the dimensions and data for an image group, including the number of axes, their sizes, and a pointer to the data cube.

Template Parameters:

T – Type of the data stored in the image group.

Param naxis:

SpiceLong - Number of axes in the image group.

Param naxes:

SpiceLong* - Array containing the sizes of each axis.

Param szprd:

SpiceLong* - Array containing the product of sizes for each axis

Param dtcub:

T* - Pointer to the data cube of the image group.

I/O functions

group I/O functions

General functions for file handling.

Functions

FILE *fopenw(SpiceChar *path)

Open/write file with additional printout+ eventual error output.

This function opens a file for writing and if the file cannot be opened, it prints an error message and exits the program.

Parameters:

path – SpiceChar* The path to the file to be opened.

Returns:

FILE* Returns a file pointer to the opened file.

FILE *fopenr(char *path)

Open/read file with additional printout+ eventual error output.

Parameters:

path – char* The path to the file to be opened.

Returns:

FILE* Returns a file pointer to the opened file.

void fclsf(FILE *path, SpiceChar *name)

Close file and free memory.

This function closes the file and prints a message indicating that the file has been closed.

Parameters:

  • path – FILE* The file pointer to be closed.

  • name – SpiceChar* The name of the file for printout.

bool ftest(const std::string &file)

Making sure that a file exist.

Parameters:

file – std::string The name of the file to be checked.

Returns:

bool Returns true if the file exists, false otherwise.

void vtest(std::vector<std::string> flst)

Check if multiple files exist.

This function checks if all files in the list exist and prints a message accordingly.

Parameters:

flst – std::vector<std::string> A vector containing the names of the files to be checked.

void rd_reqs_lst(std::string fpath, rqrd_lst *req_lst)

Read a list of flags and keys setting up which input list, and which target list to read, as well as where to find the meta-kernel.

Parameters:

  • fpath – std::string The path to the file containing the required list.

  • req_lst – rqrd_lst* Pointer to a structure that will hold the required lists.

void get_reqs(rqrd_lst *lreqs, std::string cfg_dflt, int argc, char *argv[])

Get the required lists and paths from a configuration file and command line arguments.

This function reads the required lists and paths from a default configuration file and modifies them based on command line arguments if provided.

Parameters:

  • lreqs – rqrd_lst* Pointer to a structure that will hold the required lists.

  • cfg_dflt – std::string The path to the default configuration file.

  • argc – int The number of command line arguments.

  • argv – char** The command line arguments.

void read_input(std::string fname, i_obs *g_obs)

Read input data from a file and populate the observation structure.

This function reads a file containing observation data, parses it, and fills the provided observation structure with the relevant information. It expects a specific format in the input file and will exit if the format is incorrect. The function reads the file line by line, extracting observation names, target names, details, and channel information. It allocates memory for the channels and CUFs and fills in the relevant data.

Parameters:

  • fname – std::string The name of the file to read.

  • g_obs – i_obs* Pointer to an observation structure that will be populated with data.

trgts_list rd_trgtlst(std::string fpath)

Read list of targets and their properties.

Parameters:

fpath – std::string The path to the file containing the list of targets.

Returns:

trgts_list Returns a trgts_list object containing the target specifications.

void get_output_name(std::string path_out, char *name_obs, char *filename, long fnm_len)

Assemble the output name of the observation.

Parameters:

  • path_out – std::string The output path where the observation file will be saved.

  • name_obs – char* Pointer to a character array that will hold the observation name.

  • filename – char* Pointer to a character array that will hold the full filename.

  • fnm_len – long The length of the filename character array.

FITSIO functions

group FITSIO library wrappers

These functions wrap around the FITSIO library to write data sets to disk.

Functions

template<typename T>
void writefits(const char *fname, T *arr0, long bitpix, long tform, long naxis, long *naxes)

Write a FITS file with the given data.

This function creates a FITS file and writes the provided data into it. Any passed-on array should be allocated using alloc_2d_ or alloc_3d_ to ensure proper memory layout for FITS output.

Parameters:

  • fname – const char* - Name of the FITS file to write.

  • arr0 – T* - Pointer to the data array to write.

  • bitpix – long - Bit pixel value for the FITS image.

  • tform – long - Data type for the FITS image.

  • naxis – long - Number of axes in the FITS image.

  • naxes – long* - Array containing the dimensions of the FITS image.

void write_fits_I_II_III(fitsfile *fptr, lst_krnls *lst_k, i_obs *g_obs, time_mpos *tmpos, geninfo *ginfo, trgts_list *l_obj, obj_fov *l_fov)

One way stop to write in the first group of binary tables.

Parameters:

  • fptr – fitsfile* Pointer to the FITS file to write to.

  • lst_k – lst_krnls* Pointer to a structure that holds the list of loaded kernels.

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • ginfo – geninfo* Pointer to a structure that will hold general information about the spacecraft.

  • l_obj – trgts_list* Pointer to a list of target objects.

  • l_fov – obj_fov* Pointer to the field of view structure.

void write_fits_IV(fitsfile *fptr, i_obs *g_obs, trginfo *tinfo, SpiceLong index, SpiceBoolean f_dsk)

Print-out target specific quantities in fits table.

Parameters:

  • fptr – fitsfile* Pointer to the FITS file to write to.

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tinfo – trginfo* Pointer to a structure that holds target information.

  • index – SpiceLong The index of the target in the list.

  • f_dsk – SpiceBoolean Flag indicating if DSK data is available.

void write_fits_V(fitsfile *fptr, infoframe *finfo, SpiceLong *nmax, SpiceLong *sz_cub, SpiceBoolean has_dsk)

Write target specific information frames as FITS image.

Parameters:

  • fptr – fitsfile* Pointer to the FITS file to write to.

  • finfo – infoframe* Pointer to a structure that holds information frames.

  • nmax – SpiceLong* Pointer to a variable that holds the maximum number of elements.

  • sz_cub – SpiceLong* Pointer to a variable that holds the size of the cube.

  • has_dsk – SpiceBoolean Flag indicating if DSK data is available.

Targets information

group Assemble planetary physical informations

Functions to generate, if necessary, a list of objects that will, or might, be observed by MAJIS and their physical properties by querying the SPICE kernel pool.

Functions

void gen_obj_jsys_grab(FILE *fp, SpiceInt nfid, SpiceChar *nfnm, SpiceBoolean f_ring)

Retrieve information about a specific target.

Parameters:

  • fp – FILE* The file pointer to write the target information.

  • nfid – SpiceInt The ID of the target.

  • nfnm – SpiceChar* The name of the target.

  • f_ring – SpiceBoolean Flag indicating if the target is a ring.

void gen_obj_jsys(std::string f_nm)

Generate a list of targets and their properties.

This function generates a list of targets and their properties (Name, NAIF IDs, radii, are they Jupiter rings, etc.). Besides objects from the Jupiter system, it also includes Venus, the Earth and the moon.

Parameters:

f_nm – std::string The name of the file to write the target list.

GEOMAJIS core

group Wrappers around SPICE functions

Functions based on the SPICE library to perform various operations such as converting body names to IDs, converting epochs, getting positions, computing illumination angles, etc.

Functions

SpiceInt alias_bods2c(SpiceChar *nm)

Wrapper around bods2c with a fail check.

Parameters:

nm – SpiceChar* The name of the body to be converted to its NAIF ID.

Returns:

SpiceInt Returns the NAIF ID of the body or an error

void get_time_mpos(SpiceInt *id_spc, i_obs *g_obs, time_mpos *tmpos)

Grab the UTC values from the input list read, and convert them.

This function retrieves the UTC values from the input observation list, converts them to the appropriate format, and stores them in the provided time_mpos structure.

Parameters:

  • id_spc – SpiceInt* Pointer to the NAIF ID of the spacecraft.

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tmpos – time_mpos* Pointer to a structure that will hold the converted time values.

void get_set_pos(i_obs *g_obs, time_mpos *tmpos, geninfo *ginfo)

Get positions, distances and light times for a set of objects: S/C->SSB, S/C->Sun, S/C->Earth, S/C->Jupiter, Sun->Jupiter.

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tmpos – time_mpos* Pointer to a structure that will hold the converted time values.

  • ginfo – geninfo* Pointer to a structure that will hold general information about the spacecraft.

void wrp_occult(i_obs *g_obs, mission *lrefs, time_mpos *tmpos, trgts_list *lobjs, obj_fov *l_fov, trginfo *tinfo)

Find out which object is in front of which other object.

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • lrefs – mission* Pointer to a structure that holds mission references.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • lobjs – trgts_list* Pointer to a list of target objects.

  • l_fov – obj_fov* Pointer to the field of view structure.

  • tinfo – trginfo* Pointer to a structure that holds target information.

void get_azimut(SpiceAngles *ang)

Illumination functions.

Compute the azimuth angle based on phase, incidence, and emergence angles.

Parameters:

ang – SpiceAngles* Pointer to a structure that holds the angles (phase, incidence, emergence).

void get_illum(SpiceVecDbl *p_xyz, SpiceVecDbl *p_obs, SpiceVecDbl *p_sun, SpiceVecDbl radii, SpiceAngles *ang, bool f_dbg)

Compute geometrical angles directly instead of using illum_c, (i.e.

spare CPU cycles and two spkez calls and then some)

Parameters:

  • p_xyz – SpiceVecDbl* Pointer to the position vector of the target.

  • p_obs – SpiceVecDbl* Pointer to the position vector of the observer.

  • p_sun – SpiceVecDbl* Pointer to the position vector of the Sun.

  • radii – SpiceVecDbl The radii of the target body.

  • ang – SpiceAngles* Pointer to a structure that will hold the computed angles (phase, incidence, emergence, azimuth).

  • f_dbg – bool Flag indicating whether to print debug information.

void get_trg_blk(i_obs *g_obs, mission *lrefs, time_mpos *tmpos, trgts_list *lobjs, obj_fov *l_fov, geninfo *ginfo, trginfo *tinfo)

loop over objects in Fov, get state, distance, lt, sub-spc, sub-sol

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • lrefs – mission* Pointer to a structure that holds mission references.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • lobjs – trgts_list* Pointer to a list of target objects.

  • l_fov – obj_fov* Pointer to the field of view structure.

  • ginfo – geninfo* Pointer to a structure that will hold general information about the spacecraft.

  • tinfo – trginfo* Pointer to a structure that holds target information.

void gen_vrt_ray(i_obs *g_obs, imppe *tmpccd)

Generate a set of vertices and rays from given instrument specifications.

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tmpccd – imppe* Pointer to a structure that holds information about the instrument’s CCD.

void get_radec(i_obs *g_obs, time_mpos *tmpos, geninfo *ginfo, imppe *fk_ccd)

Compute RA/DEC pointings for all vertices at all epochs for a given observation.

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • ginfo – geninfo* Pointer to a structure that will hold general information about the spacecraft.

  • fk_ccd – imppe* Pointer to a structure that holds information about the instrument’s CCD.

void trg_in_fov(i_obs *g_obs, mission *lrefs, time_mpos *tmpos, trgts_list *lobjs, obj_fov *l_fov)

Query which objects are in the field of view.

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • lrefs – mission* Pointer to a structure that holds mission references.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • lobjs – trgts_list* Pointer to a list of target objects.

  • l_fov – obj_fov* Pointer to the field of view structure.

void get_rtx(i_obs *g_obs, mission *lrefs, time_mpos *tmpos, trgts_list *lobjs, target_specs *trgbd, trginfo *tinfo, infoframe *finfo, imppe *fkccd)

Perform computations with ellipsoid (and eventually DSK)

Parameters:

  • g_obs – i_obs* Pointer to the observation structure containing the time information.

  • lrefs – mission* Pointer to a structure that holds mission references.

  • tmpos – time_mpos* Pointer to a structure that holds time and position information.

  • lobjs – trgts_list* Pointer to a list of target objects.

  • trgbd – target_specs* Pointer to a structure that holds target specifications.

  • tinfo – trginfo* Pointer to a structure that holds target information.

  • finfo – infoframe* Pointer to a structure that holds information frames.

  • fkccd – imppe* Pointer to a structure that holds information about the instrument’s CCD.