# Modules

A description of low-level execution parts of Munipack for programmers.

## Introduction

Munipack's working core is split on to single exacutables (modules) which can be run independently. Both command-line and graphical interfaces (munipack, xmunipack) just provides user friendly interface and calls the modules. The design naturally separates the GUI and the execution part.

The way is very flexible. It has benefit when another interfaces or usage is required. For example, the routines can be easy used as utilities for (web) servers, Virtual observatory, scripting systems, pipe lines, called from shells, etc.

## Rules

There are a few strictly followed rules for all modules:

- Every module is a single executable.
- Modules interacts ONLY via its standard input, output and error. Just only text messages are mutually exchanged. Ones does not uses command-line parameters or any form of GUI.
- Parameters are passed in the form: PARAMETER = VALUE.
- Character size does matter (use uppercase).
- Parameter values must be in Fortran free format: Numbers are typed as expected (but it is preferred to recognize between integers and floats). Strings are enclosed in apostrophes. Boolean (logical) values has the first character only T or F. Example: FILE = 'file.fits', INIT = T, N = 10, TOL = 1e-3.
- The list (array) of parameters has specified number of items on a single line preceding the first argument. Example:

      NITEMS = 2
      ITEM = 'file1.fits'
      ITEM = 'file2.fits'

- Filenames can be specified as URL. Any file locator known to cFITSIO library may be used (ftp://server.domain/file.fits).
- FITS filename may include HDU specification.
- Unknown parameters are silently ignored.
- Boolean VERBOSE parameter switch on/off a response for user (log).
- Boolean PIPELOG parameter switch on/off a response for a calling routine.
- Control text messages are introduced by the sequence: `=*> *` (where `*` is an arbitrary text).

Modules are stored in LIBEXEC path as defined by Autotools. Current binary distribution defines the path as `/opt/munipack/libexec/munipack`. Note that modules are not available in system-wide binary search path.

## Logging messages

The rules for logging are analogical to standard Unix philosophy:

- Generally, logging is switched-off. It means that just only error messages are printed. No logging messages appears by default.
- Use of VERBOSE parameter produces logging in human-readable (free, no-rules) form.
- Use of PIPELOG parameter produces control text messages in carefully defined machine-readable format (see next section).
- Return codes are printed to standard error output in the form: STOP <code>, the line must contains no other characters. The result code is zero for successful exit.

## Inter-process communication

Calling routines must print some listing in specified format when parameter PIPELOG is used:

- Example: `=AFIT> 2 1 3 4`
- General format: `=[key]> [value]`
- Format can be parsed with the regular expression pattern: `"^=(.*)> (.+)"` (without quotes). Parameters are available via \1 and \2 back-references.

## FITS keywords

There is no general convention for FITS keywords except NAXIS, NAXES, BITPIX and SIMPLE. Unforunatelly, frequently are used different keywords with the same meaning. For example, an exposure time may be stored as EXPTIME or EXPOSURE keywords. Therefore all the modules accepts following parameters to set proper keywords according to a local conventions. See FITS environment variables.

## Astrometry

Astrometry provides astrometry.

Module name: astrometer

Source: `astrometry/astrometry.f95`

Parameters (see astrometry page for description)
Parameter | type | description
--- | --- | ---
PROJECTION | string | type of projection
FITS | string | select a method: ROBUST, SQUARE
AUNITS | string | print residuals in specified units
WCSSAVE | bool | save astrometry to header
VERBOSE | logical | print verbose mesages
PIPELOG | logical | print control mesages
CRPIX | float,float | center of projection on map (rectangular coordinates)
CRVAL | float,float | center of projection on sphere (spherical coordinates), degrees
SCALE | float | scale in pixels per degree
ANGLE | float | rotation about center in degrees
SIG | float | mean uncertainity in position
XSIG | float | probability coefficient
FSIG | float | mean uncertainity in fluxes
INITPAR | bool | init parameters (provided by CRVAL,SCALE and ANGLE)
MATCH | bool | use matching
NMATCH | integer | number of objects used in matching sequence
MAXMATCH | integer | number of objects used for matching
FULLMATCH | integer | ... for matching
COL_RA | integer | column with RA
COL_DEC | integer | column with Dec
COL_PMRA | integer | column with PM in RA
COL_PMDEC | integer | column with PM in Dec
COL_MAG | integer | column with magnitude
CAT | string | FITS table filename used as the reference catalogue for spherical coordinates
REF | string | FITS table filename used as the reference list of spherical coordinates of objects
REL | string | FITS filename used as the reference list of rectangular coordinates of objects
FILE | string | FITS table filename containing list of rectangular coordinates of objects used for astrometry