C-Munipack 1.2 / Application programming interface / API reference

Functions for reading and writing photometry files.

cmpack_phtfile.h

Data structures

CmpackPhtMeasurementMeasurement stored in photometry file.

Type definitions

CmpackPhtFilePhotometry file context.
CmpackPhtApertureAperture definition in photometry file.
CmpackPhtStarStar definition in photometry file.

Functions

cmpack_pht_initCreate new photometry file context.
cmpack_pht_loadLoad a photometry file.
cmpack_pht_saveSave data from memory to a photometry file.
cmpack_pht_copyCopy a file.
cmpack_pht_clearClear all data.
cmpack_pht_testTest if given file seems to be a photometry file.
cmpack_pht_test_bufferTest if the content of the buffer might be a photometry file.
cmpack_pht_get_sizeGet frame size in pixels.
cmpack_pht_get_jdGet julian date of observation.
cmpack_pht_get_exptimeGet exposure duration.
cmpack_pht_get_filterGet optical filter name.
cmpack_pht_get_offsetGet frame size in pixels.
cmpack_pht_pkysSet parameter value in file header (string).
cmpack_pht_pkyiSet parameter value in file header (integer).
cmpack_pht_pkydSet parameter value in file header (double).
cmpack_pht_gkysGet value of parameter in file header (string).
cmpack_pht_gkyiGet value of parameter in file header (integer number).
cmpack_pht_gkydGet value of parameter in file header (real number).
cmpack_pht_gkycGet comment text of parameter in file header.
cmpack_pht_nkeyGet number of parameters in header section.
cmpack_pht_gkynGet the parameter from header section by its index.
cmpack_pht_dkeyDelete parameter from header section.
cmpack_pht_naperGet number of apertures stored in a photometry file.
cmpack_pht_get_apertureGet aperture context by the index.
cmpack_pht_find_apertureGet aperture context by the identifier.
cmpack_pht_add_apertureAdd new aperture to a file.
cmpack_pht_aperture_newCreate a new aperture definition.
cmpack_pht_aperture_get_idGet identifier of an aperture.
cmpack_pht_aperture_set_radiusSet aperture radius.
cmpack_pht_aperture_get_radiusGet radius of an aperture.
cmpack_pht_nstarGet number of stars stored in a photometry file.
cmpack_pht_add_starAdd new star to a file.
cmpack_pht_get_starGet star context by the index.
cmpack_pht_find_starGet star context by its identifier.
cmpack_pht_find_star_by_refidGet star context by its reference identifier.
cmpack_pht_star_newCreate a new star context.
cmpack_pht_star_get_idGet position of a center of a star.
cmpack_pht_star_set_centerSet position of a center of a star.
cmpack_pht_star_get_centerGet position of a center of a star.
cmpack_pht_star_set_refidSet reference id of a star.
cmpack_pht_star_get_refidGet reference id of a star.
cmpack_pht_star_clear_measurementsClear all measurements for specified star.
cmpack_pht_star_set_measurementSet a measurement for specified star and aperture.
cmpack_pht_star_get_measurementSet a measurement for specified star and aperture.

Description

Photometry files contain photometry result for a single CCD frame. The file is valid standalone XML document. This format was introduced in the version 1.2

CmpackPhtFile (data type)

Photometry file context.

Synopsis

typedef struct _CmpackPhtFile CmpackPhtFile

Description

This private structure holds the content of the read-all file.

CmpackPhtAperture (data type)

Aperture definition in photometry file.

Synopsis

typedef struct _CmpackPhtAperture CmpackPhtAperture

Description

This structure is used to access an aperture definitions in photometry files.

CmpackPhtStar (data type)

Star definition in photometry file.

Synopsis

typedef struct _CmpackPhtStar CmpackPhtStar

Description

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

CmpackPhtMeasurement (data structure)

Measurement stored in photometry file.

Synopsis

typedef struct _CmpackPhtMeasurement
{
     int mask,
     int code,
     double magnitude,
     double error
} CmpackPhtMeasurement;

Members

maskBitmask of valid fields (combination of CMPACK_MASK_xxx values).
codeResult of photometry.
magnitudeInstrumental mahnitude.
errorError estimation of instrumental magnitude.

cmpack_pht_init (function)

Create new photometry file context.

Synopsis

CmpackPhtFile * cmpack_pht_init (void)

Return value

pointer to a new instance

cmpack_pht_load (function)

Load a photometry file.

Synopsis

int cmpack_pht_load (CmpackPhtFile ** 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_pht_save (function)

Save data from memory to a photometry file.

Synopsis

int cmpack_pht_save (CmpackPhtFile * file, const char * filename)

Parameters

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

Return value

zero on success, error code on failure

cmpack_pht_copy (function)

Copy a file.

Synopsis

void cmpack_pht_copy (CmpackPhtFile * dstfile, CmpackPhtFile * 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_pht_clear (function)

Clear all data.

Synopsis

void cmpack_pht_clear (CmpackPhtFile * file)

Parameters

file[in] file context

cmpack_pht_test (function)

Test if given file seems to be a photometry file.

Synopsis

int cmpack_pht_test (const char * filename)

Return value

nonzero if the file is a photometry file, zero otherwise

cmpack_pht_test_buffer (function)

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

Synopsis

int cmpack_pht_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 photometry file. This function is used for file format autodetection.

Return value

nonzero if the file is a photometry file, zero otherwise

cmpack_pht_get_size (function)

Get frame size in pixels.

Synopsis

int cmpack_pht_get_size (CmpackPhtFile * 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_pht_get_jd (function)

Get julian date of observation.

Synopsis

double cmpack_pht_get_jd (CmpackPhtFile * fc)

Parameters

fc[in] file context

Return value

Julian date or zero on failure

cmpack_pht_get_exptime (function)

Get exposure duration.

Synopsis

double cmpack_pht_get_exptime (CmpackPhtFile * fc)

Parameters

fc[in] file context

Return value

Exposure duration in seconds or zero on failure

cmpack_pht_get_filter (function)

Get optical filter name.

Synopsis

const char * cmpack_pht_get_filter (CmpackPhtFile * 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_pht_get_offset (function)

Get frame size in pixels.

Synopsis

int cmpack_pht_get_offset (CmpackPhtFile * file, double * offsetx, double * offsety)

Parameters

file[in] file context
offsetx[out] frame offset in x axis in pixels
offsety[out] frame offset in y axis in pixels

Return value

nonzero on success, zero on failure

cmpack_pht_pkys (function)

Set parameter value in file header (string).

Synopsis

void cmpack_pht_pkys (CmpackPhtFile * 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. Otherwise, its content is changed. Keys are case sensitive.

Parameters

file[in] file context
key[in] parameter name
val[in] parameter value
com[in] comment text (can be NULL)

cmpack_pht_pkyi (function)

Set parameter value in file header (integer).

Synopsis

void cmpack_pht_pkyi (CmpackPhtFile * file, const char * key, int val, const char * com)

Description

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

Parameters

file[in] file context
key[in] parameter name
val[in] parameter value
com[in] comment text (can be NULL)

cmpack_pht_pkyd (function)

Set parameter value in file header (double).

Synopsis

void cmpack_pht_pkyd (CmpackPhtFile * 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. Otherwise, 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 text (can be NULL)

cmpack_pht_gkys (function)

Get value of parameter in file header (string).

Synopsis

const char * cmpack_pht_gkys (CmpackPhtFile * 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

parameter value, null terminated string

cmpack_pht_gkyi (function)

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

Synopsis

int cmpack_pht_gkyi (CmpackPhtFile * file, const char * key, int defval)

Description

Keys are case sensitive. If the parameter is not defined, returns the default value.

Parameters

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

Return value

parameter value or default value if it is not defined

cmpack_pht_gkyd (function)

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

Synopsis

double cmpack_pht_gkyd (CmpackPhtFile * file, const char * key, double defval)

Description

Keys are case sensitive. If the parameter is not defined, returns the default value.

Parameters

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

Return value

parameter value or default value if it is not defined

cmpack_pht_gkyc (function)

Get comment text of parameter in file header.

Synopsis

const char * cmpack_pht_gkyc (CmpackPhtFile * 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_pht_nkey (function)

Get number of parameters in header section.

Synopsis

int cmpack_pht_nkey (CmpackPhtFile * file)

Parameters

file[in] file context

Return value

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

cmpack_pht_gkyn (function)

Get the parameter from header section by its index.

Synopsis

int cmpack_pht_gkyn (CmpackPhtFile * 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 internal memory buffers. You must not free or modify it!

Parameters

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

Return value

nonzero on success, zero on failure

cmpack_pht_dkey (function)

Delete parameter from header section.

Synopsis

void cmpack_pht_dkey (CmpackPhtFile * file, const char * key)

Description

Keys are case sensitive.

Parameters

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

cmpack_pht_naper (function)

Get number of apertures stored in a photometry file.

Synopsis

int cmpack_pht_naper (CmpackPhtFile * file)

Parameters

file[in] file context

Return value

number of apertures or negative value on failure

cmpack_pht_get_aperture (function)

Get aperture context by the index.

Synopsis

CmpackPhtAperture * cmpack_pht_get_aperture (CmpackPhtFile * file, int index)

Description

Index of the first aperture is zero. The function increments aperture's reference counter, the caller is responsible to call the cmpack_unref() function when the context is no longer needed.

Parameters

file[in] file context
index[in] aperture index (starting by 0)

Return value

pointer to context or zero on failure.

cmpack_pht_find_aperture (function)

Get aperture context by the identifier.

Synopsis

CmpackPhtAperture * cmpack_pht_find_aperture (CmpackPhtFile * file, int aperid)

Description

The function increments aperture's reference counter, the caller is responsible to call the cmpack_unref() function when the context is no longer needed.

Parameters

file[in] file context
aperid[in] aperture identifider

Return value

aperture index or negative value on failure

cmpack_pht_add_aperture (function)

Add new aperture to a file.

Synopsis

void cmpack_pht_add_aperture (CmpackPhtFile * file, CmpackPhtAperture * aper)

Description

The function steals the aperture's reference, so the caller dont need to decrement the aperture's reference counter.

Parameters

file[in] file context
aper[in] aperture context

cmpack_pht_aperture_new (function)

Create a new aperture definition.

Synopsis

CmpackPhtAperture * cmpack_pht_aperture_new (int id)

Description

The function makes a new aperture definition and returns a new reference to it.

Parameters

id[in] aperture identifider

Return value

pointer to the new reference

cmpack_pht_aperture_get_id (function)

Get identifier of an aperture.

Synopsis

int cmpack_pht_aperture_get_id (CmpackPhtAperture * aper)

Parameters

aper[in] aperture context

Return value

returns aperture id or zero on failure

cmpack_pht_aperture_set_radius (function)

Set aperture radius.

Synopsis

void cmpack_pht_aperture_set_radius (CmpackPhtAperture * aper, double radius)

Parameters

aper[in] aperture context
radius[in] radius in pixels

Return value

zero on success, error code on failure

cmpack_pht_aperture_get_radius (function)

Get radius of an aperture.

Synopsis

double cmpack_pht_aperture_get_radius (CmpackPhtAperture * aper)

Parameters

aper[in] aperture context

Return value

aperture radius in pixels or zero on failure

cmpack_pht_nstar (function)

Get number of stars stored in a photometry file.

Synopsis

int cmpack_pht_nstar (CmpackPhtFile * file)

Parameters

file[in] file context

Return value

zero on success, error code on failure

cmpack_pht_add_star (function)

Add new star to a file.

Synopsis

void cmpack_pht_add_star (CmpackPhtFile * file, CmpackPhtStar * star)

Description

The function steals the reference to the star.

Parameters

file[in] file context
star[in] star context

cmpack_pht_get_star (function)

Get star context by the index.

Synopsis

CmpackPhtStar * cmpack_pht_get_star (CmpackPhtFile * file, int index)

Description

Index of the first star is zero. The function increments star's reference counter, the caller is responsible to call the cmpack_unref() function when the context is no longer needed.

Parameters

file[in] file context
index[in] star index (starting by 0)

Return value

pointer to context or zero on failure.

cmpack_pht_find_star (function)

Get star context by its identifier.

Synopsis

CmpackPhtStar * cmpack_pht_find_star (CmpackPhtFile * file, int starid)

Description

The function increments star's reference counter, the caller is responsible to call the cmpack_unref() function when the context is no longer needed.

Parameters

file[in] file context
starid[in] star identifier

Return value

pointer to context or zero on failure.

cmpack_pht_find_star_by_refid (function)

Get star context by its reference identifier.

Synopsis

CmpackPhtStar * cmpack_pht_find_star_by_refid (CmpackPhtFile * file, int refid)

Description

The function increments star's reference counter, the caller is responsible to call the cmpack_unref() function when the context is no longer needed.

Parameters

file[in] file context
refid[in] reference identifier

Return value

pointer to context or zero on failure.

cmpack_pht_star_new (function)

Create a new star context.

Synopsis

CmpackPhtStar * cmpack_pht_star_new (int id)

Parameters

id[in] star identifier

Return value

Zero on success or error code on failure

cmpack_pht_star_get_id (function)

Get position of a center of a star.

Synopsis

int cmpack_pht_star_get_id (CmpackPhtStar * star)

Parameters

star[in] star context

Return value

Star identifier or negative value on failure

cmpack_pht_star_set_center (function)

Set position of a center of a star.

Synopsis

void cmpack_pht_star_set_center (CmpackPhtStar * star, double x, double y)

Parameters

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

cmpack_pht_star_get_center (function)

Get position of a center of a star.

Synopsis

int cmpack_pht_star_get_center (CmpackPhtStar * star, double * x, double * y)

Parameters

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

Return value

nonzero on success or zero on failure

cmpack_pht_star_set_refid (function)

Set reference id of a star.

Synopsis

void cmpack_pht_star_set_refid (CmpackPhtStar * star, int refid)

Parameters

star[in] star context
refid[in] reference star identifier

cmpack_pht_star_get_refid (function)

Get reference id of a star.

Synopsis

int cmpack_pht_star_get_refid (CmpackPhtStar * star)

Parameters

star[in] star context

Return value

Reference id or negative value on failure

cmpack_pht_star_clear_measurements (function)

Clear all measurements for specified star.

Synopsis

void cmpack_pht_star_clear_measurements (CmpackPhtStar * star)

Parameters

star[in] star context

cmpack_pht_star_set_measurement (function)

Set a measurement for specified star and aperture.

Synopsis

void cmpack_pht_star_set_measurement (CmpackPhtStar * star, int aperture, const CmpackPhtMeasurement * data)

Parameters

star[in] star context
aperture[in] aperture identifier
data[in] measurement data

cmpack_pht_star_get_measurement (function)

Set a measurement for specified star and aperture.

Synopsis

int cmpack_pht_star_get_measurement (CmpackPhtStar * star, int aperture, CmpackPhtMeasurement * data)

Parameters

star[in] star context
aperture[in] aperture identifier
data[out] measurement data

Return value

Zero on success or error code on failure