C-Munipack 1.2 / Application programming interface / API reference

Functions for reading and writing catalogue files.

cmpack_catfile.h

Enumerations

CmpackSelectionTypeSelection types.

Type definitions

CmpackCatFileCatalogue file context.
CmpackCatStarStar definition in catalogue file.
CmpackCatSelectionSelection in catalogue file.

Functions

cmpack_cat_initCreate a new catalogue file context.
cmpack_cat_loadLoad catalogue file from file.
cmpack_cat_saveSave changed, close file and free allocated memory.
cmpack_cat_clearClear all data.
cmpack_cat_copyMake a copy of a catalogue file.
cmpack_cat_makeMake catalogue file from a photometry file.
cmpack_cat_testTest if given file seems to be a catalogue file.
cmpack_cat_test_bufferTest if the content of the buffer might be a catalogue file.
cmpack_cat_get_sizeGet frame size in pixels.
cmpack_cat_get_jdGet julian date of observation.
cmpack_cat_get_exptimeGet exposure duration.
cmpack_cat_get_filterGet optical filter name.
cmpack_cat_get_objectGet object's designation.
cmpack_cat_get_objraGet object's right ascension (R.A.
cmpack_cat_get_objdecGet object's declination (Dec.
cmpack_cat_pkysSet parameter value in file header (string).
cmpack_cat_pkyiSet parameter value in file header (integer).
cmpack_cat_pkydSet parameter value in file header (double).
cmpack_cat_gkysGet value of parameter in file header (string).
cmpack_cat_gkyiGet value of parameter in file header (integer number).
cmpack_cat_gkydGet value of parameter in file header (real number).
cmpack_cat_gkycGet comment text of parameter in file header.
cmpack_cat_nkeyGet number of parameters in file header.
cmpack_cat_gkynGet the parameter from file header by its index.
cmpack_cat_dkeyDelete parameter from file header.
cmpack_cat_nstarGets number of stars defined in the file.
cmpack_cat_add_starAdd a star to a catalogue file.
cmpack_cat_get_starGet star by its index.
cmpack_cat_find_starFind star by identifier.
cmpack_cat_star_get_idGet star indentifier.
cmpack_cat_star_set_centerSet position of a star.
cmpack_cat_star_get_centerGet position of a star.
cmpack_cat_star_set_magnitudeSet magnitude of a star.
cmpack_cat_star_get_magnitudeGet magnitude of a star.
cmpack_cat_clear_selectionSet selection type of all stars to CMPACK_SELECT_NONE.
cmpack_cat_set_star_typeSet selection type of a single star.
cmpack_cat_get_star_typeGet selection type of a single star.
cmpack_cat_get_selectionGet selection context from a catalogue file.
cmpack_cat_selection_clearClear the selection context.
cmpack_cat_selection_appendAppend a list of stars.
cmpack_cat_selection_setSet selection.
cmpack_cat_selection_nitemsGet number of stars in a selection.
cmpack_cat_selection_getGet list of stars.
cmpack_cat_selection_itemGet a star by index.

Description

Catalogue files contain information relative position of stars and position of variable, comparison and check stars. It is designed to simplify the final phase of the reduction process. The application loads the selection from a catalogue file and user only checks and confirms it.

The catalogue file is a XML document, see the Reference manual for its document type definition.

CmpackCatFile (data type)

Catalogue file context.

Synopsis

typedef struct _CmpackCatFile CmpackCatFile

Description

This private structure holds the content of the catalogue file.

CmpackCatStar (data type)

Star definition in catalogue file.

Synopsis

typedef struct _CmpackCatStar CmpackCatStar

Description

This structure is used to access a star definitions in a catalogue files.

CmpackCatSelection (data type)

Selection in catalogue file.

Synopsis

typedef struct _CmpackCatSelection CmpackCatSelection

Description

This structure is used to access a selection of stars in a catalogue files.

CmpackSelectionType (enumeration)

Selection types.

Synopsis

enum CmpackSelectionType
{
     CMPACK_SELECT_NONE,
     CMPACK_SELECT_VAR,
     CMPACK_SELECT_COMP,
     CMPACK_SELECT_CHECK
};

Enumerators

CMPACK_SELECT_NONEOrdinary star.
CMPACK_SELECT_VARVariable star.
CMPACK_SELECT_COMPComparison star.
CMPACK_SELECT_CHECKCheck star.

cmpack_cat_init (function)

Create a new catalogue file context.

Synopsis

CmpackCatFile * cmpack_cat_init (void)

Return value

pointer to a new instance

cmpack_cat_load (function)

Load catalogue file from file.

Synopsis

int cmpack_cat_load (CmpackCatFile ** file, const char * filename, CmpackLoadMode flags)

Parameters

file[out] new file context
filename[in] path + file name
flags[in] flags (see CMPACK_LOAD_xxx constants)

Return value

zero on success, error code on failure

cmpack_cat_save (function)

Save changed, close file and free allocated memory.

Synopsis

int cmpack_cat_save (CmpackCatFile * file, const char * filename)

Description

If the file was created by means of cmpack_cat_init() function, no changes are saved.

Parameters

file[in] file context
filename[in] path + file name

Return value

zero on success, error code on failure

cmpack_cat_clear (function)

Clear all data.

Synopsis

void cmpack_cat_clear (CmpackCatFile * file)

Parameters

file[in] file context

cmpack_cat_copy (function)

Make a copy of a catalogue file.

Synopsis

void cmpack_cat_copy (CmpackCatFile * dstfile, CmpackCatFile * srcfile)

Description

Makes a copy of source file to the destination file. All content of the destination file will be deleted.

Parameters

dstfile[in] destination file context
srcfile[in] source file context

cmpack_cat_make (function)

Make catalogue file from a photometry file.

Synopsis

int cmpack_cat_make (CmpackCatFile * dstfile, CmpackPhtFile * srcfile, int aperture)

Description

Converts a photometry file to a catalogue file. All content of the destination file will be deleted.

Parameters

dstfile[in] destination file context
srcfile[in] source file context
aperture[in] aperture id

cmpack_cat_test (function)

Test if given file seems to be a catalogue file.

Synopsis

int cmpack_cat_test (const char * filename)

Return value

nonzero if the file is a photometry file, zero otherwise

cmpack_cat_test_buffer (function)

Test if the content of the buffer might be a catalogue file.

Synopsis

int cmpack_cat_test_buffer (const char * buffer, int buflen, int filesize)

Description

The function checks the data in the buffer and returns nonzero, when the buffer contain first 'buflen' bytes from a catalogue file. This function is used for file format autodetection.

Return value

nonzero if the file is a photometry file, zero otherwise

cmpack_cat_get_size (function)

Get frame size in pixels.

Synopsis

int cmpack_cat_get_size (CmpackCatFile * file, int * width, int * height)

Parameters

file[in] file context
width[out] frame width in pixels (0 = not available)
height[out] frame height in pixels (0 = not available)

Return value

nonzero on success, zero on failure

cmpack_cat_get_jd (function)

Get julian date of observation.

Synopsis

double cmpack_cat_get_jd (CmpackCatFile * fc)

Parameters

fc[in] file context

Return value

Julian date or zero on failure

cmpack_cat_get_exptime (function)

Get exposure duration.

Synopsis

double cmpack_cat_get_exptime (CmpackCatFile * fc)

Parameters

fc[in] file context

Return value

Exposure duration in seconds or zero on failure

cmpack_cat_get_filter (function)

Get optical filter name.

Synopsis

const char * cmpack_cat_get_filter (CmpackCatFile * fc)

Description

The function returns pointer to the internal buffer. You must not free or modify it.

Parameters

fc[in] file context

Return value

Filter name, null terminated string

cmpack_cat_get_object (function)

Get object's designation.

Synopsis

const char * cmpack_cat_get_object (CmpackCatFile * fc)

Description

The function returns pointer to the internal buffer. You must not free or modify it.

Parameters

fc[in] file context

Return value

Object's designation, null terminated string

cmpack_cat_get_objra (function)

Get object's right ascension (R.A.

Synopsis

const char * cmpack_cat_get_objra (CmpackCatFile * fc)

Description

)

The function returns pointer to the internal buffer. You must not free or modify it.

Parameters

fc[in] file context

Return value

Object's R.A., null terminated string

cmpack_cat_get_objdec (function)

Get object's declination (Dec.

Synopsis

const char * cmpack_cat_get_objdec (CmpackCatFile * fc)

Description

)

The function returns pointer to the internal buffer. You must not free or modify it.

Parameters

fc[in] file context

Return value

Object's Dec., null terminated string

cmpack_cat_pkys (function)

Set parameter value in file header (string).

Synopsis

void cmpack_cat_pkys (CmpackCatFile * file, const char * key, const char * val, const char * com)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name
val[in] parameter value
com[in] comment (parameter description)

cmpack_cat_pkyi (function)

Set parameter value in file header (integer).

Synopsis

void cmpack_cat_pkyi (CmpackCatFile * file, const char * key, int val, const char * com)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name
val[in] parameter value
com[in] comment (parameter description)

Return value

zero on success, error code on failure

cmpack_cat_pkyd (function)

Set parameter value in file header (double).

Synopsis

void cmpack_cat_pkyd (CmpackCatFile * file, const char * key, double val, int prec, const char * com)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name
val[in] parameter value
prec[in] number of decimal places
com[in] comment (parameter description)

Return value

zero on success, error code on failure

cmpack_cat_gkys (function)

Get value of parameter in file header (string).

Synopsis

const char * cmpack_cat_gkys (CmpackCatFile * file, const char * key)

Parameters

file[in] file context
key[in] parameter name

Return value

pointer to internal buffer or NULL

cmpack_cat_gkyi (function)

Get value of parameter in file header (integer number).

Synopsis

int cmpack_cat_gkyi (CmpackCatFile * file, const char * key, int defval)

Description

Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name
defval[in] default value

Return value

parameter value or default value

cmpack_cat_gkyd (function)

Get value of parameter in file header (real number).

Synopsis

double cmpack_cat_gkyd (CmpackCatFile * file, const char * key, double defval)

Description

Keys are case sensitive. You can set the output parameter to NULL if you want to test the value only.

Parameters

file[in] file context
key[in] parameter name
defval[in] default value

Return value

parameter value or default value

cmpack_cat_gkyc (function)

Get comment text of parameter in file header.

Synopsis

const char * cmpack_cat_gkyc (CmpackCatFile * file, const char * key)

Description

Keys are case sensitive. The function returns pointer to the internal buffer. You must not free or modify it.

Parameters

file[in] file context
key[in] parameter name

Return value

comment text, null terminated string

cmpack_cat_nkey (function)

Get number of parameters in file header.

Synopsis

int cmpack_cat_nkey (CmpackCatFile * file)

Parameters

file[in] file context

Return value

number of parameter or zero if the file is not valid context or if the header is empty.

cmpack_cat_gkyn (function)

Get the parameter from file header by its index.

Synopsis

int cmpack_cat_gkyn (CmpackCatFile * file, int index, const char ** key, const char ** val, const char ** com)

Description

Index of the first parameter is zero. The output parameters receive the pointers to newly allocated memory buffers. The caller is responsible to free it by calling of cmpack_free() function. You can set the value of output parameter to NULL if you do not need to read it.

Parameters

file[in] file context
index[in] parameter index (starting by zero)
key[out] parameter name (can be NULL)
val[out] parameter value (can be NULL)
com[out] comment (can be NULL)

Return value

zero on success, error code on failure

cmpack_cat_dkey (function)

Delete parameter from file header.

Synopsis

void cmpack_cat_dkey (CmpackCatFile * file, const char * key)

Description

Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name

cmpack_cat_nstar (function)

Gets number of stars defined in the file.

Synopsis

int cmpack_cat_nstar (CmpackCatFile * file)

Parameters

file[in] file context

Return value

number of selected stars or zero on failure

cmpack_cat_add_star (function)

Add a star to a catalogue file.

Synopsis

CmpackCatStar * cmpack_cat_add_star (CmpackCatFile * file, int star_id)

Parameters

file[in] file context
star_id[in] star identifier

Return value

new reference to a star

cmpack_cat_get_star (function)

Get star by its index.

Synopsis

CmpackCatStar * cmpack_cat_get_star (CmpackCatFile * file, int index)

Parameters

file[in] file context
index[in] index

cmpack_cat_find_star (function)

Find star by identifier.

Synopsis

CmpackCatStar * cmpack_cat_find_star (CmpackCatFile * file, int star_id)

Parameters

file[in] file context
star_id[in] star identifier

cmpack_cat_star_get_id (function)

Get star indentifier.

Synopsis

int cmpack_cat_star_get_id (CmpackCatStar * star)

Parameters

star[in] star context

Return value

identifier of a star or negative value on failure

cmpack_cat_star_set_center (function)

Set position of a star.

Synopsis

void cmpack_cat_star_set_center (CmpackCatStar * star, double x, double y)

Parameters

star[in] star context
x[in] position in x axis in pixels
y[in] position in y axis in pixels

cmpack_cat_star_get_center (function)

Get position of a star.

Synopsis

int cmpack_cat_star_get_center (CmpackCatStar * star, double * x, double * y)

Parameters

star[in] star context
x[out] position in x axis in pixels
y[out] position in y axis in pixels

Return value

zero on success or error code on failure

cmpack_cat_star_set_magnitude (function)

Set magnitude of a star.

Synopsis

void cmpack_cat_star_set_magnitude (CmpackCatStar * star, double mag)

Parameters

star[in] star context
mag[in] magnitude

cmpack_cat_star_get_magnitude (function)

Get magnitude of a star.

Synopsis

int cmpack_cat_star_get_magnitude (CmpackCatStar * star, double * mag)

Parameters

star[in] star context
mag[out] magnitude

Return value

nonzero on success or zero on failure

cmpack_cat_clear_selection (function)

Set selection type of all stars to CMPACK_SELECT_NONE.

Synopsis

void cmpack_cat_clear_selection (CmpackCatFile * file)

Parameters

file[in] file context

cmpack_cat_set_star_type (function)

Set selection type of a single star.

Synopsis

void cmpack_cat_set_star_type (CmpackCatFile * file, int star_id, CmpackSelectionType type)

Parameters

file[in] file context
star_id[in] star identifier
type[in] selection type

cmpack_cat_get_star_type (function)

Get selection type of a single star.

Synopsis

CmpackSelectionType cmpack_cat_get_star_type (CmpackCatFile * file, int star_id)

Parameters

file[in] file context
star_id[in] star identifier

Return value

selection type or CMPACK_SELECT_NONE if the star does not exist.

cmpack_cat_get_selection (function)

Get selection context from a catalogue file.

Synopsis

CmpackCatSelection * cmpack_cat_get_selection (CmpackCatFile * file, CmpackSelectionType type)

Parameters

file[in] file context
type[in] selection type

Return value

new reference to the selection context

cmpack_cat_selection_clear (function)

Clear the selection context.

Synopsis

void cmpack_cat_selection_clear (CmpackCatSelection * sel)

Parameters

sel[in] selection context

cmpack_cat_selection_append (function)

Append a list of stars.

Synopsis

void cmpack_cat_selection_append (CmpackCatSelection * sel, const int * list, int count)

Parameters

sel[in] selection context
list[in] star identifiers
count[in] number of stars

cmpack_cat_selection_set (function)

Set selection.

Synopsis

void cmpack_cat_selection_set (CmpackCatSelection * sel, const int * list, int count)

Parameters

sel[in] selection context
list[in] star identifiers
count[in] number of stars

cmpack_cat_selection_nitems (function)

Get number of stars in a selection.

Synopsis

int cmpack_cat_selection_nitems (CmpackCatSelection * sel)

Parameters

sel[in] selection context

Return value

number of items or zero on failure

cmpack_cat_selection_get (function)

Get list of stars.

Synopsis

int cmpack_cat_selection_get (CmpackCatSelection * sel, int * list, int count)

Parameters

sel[in] selection context
list[in] buffer which receives star identifiers
count[in] buffer size

Return value

number of items stored to buffer or negative value on failure

cmpack_cat_selection_item (function)

Get a star by index.

Synopsis

int cmpack_cat_selection_item (CmpackCatSelection * sel, int index)

Parameters

sel[in] selection context
index[in] zero base index

Return value

star identifier or negative value on failure