To calculate the source position for each event (from the '''Events''' table) in the camera, a tool called `calcsource` was developed.

The toll is called like this
{{{
calcsource YYMMDDNNN
}}}
where '''YYMMDDNNN''' is the identifier of a run created from the night of sun-set '''YYMMDD''' and the run-id '''NNN'''. It is also known as !FileId.

== Getting the source ==

The tool then requests right ascension and declination of the source observed with a given run (Source.*) and the pointing position of the telescope (!RunInfo.*) by the following query:

{{{#!sql
SELECT 
    RunInfo.fRightAscension, 
    RunInfo.fDeclination, 
    Source.fRightAscension, 
    Source.fDeclination, 
    Source.fSourceName
FROM 
    RunInfo
LEFT JOIN 
    Source USING (fSourceKey)
WHERE 
    fNight=20YYMMDD
AND 
    fRunID=NNN
}}}

Here, YYMMDD and NNN are again the parts from the !FileId given as positional option.

The table names `Source` and `RunInfo` can be altered by the options `--table.source` and `--table.runinfo`.

== Getting events ==

Then, a list of all event times together with the corresponding event number is obtained for the given run by
{{{#!sql
SELECT 
    MJD, 
    MilliSec, 
    EvtNumber
FROM 
    Images
WHERE 
    FileId=YYMMDDNNN
}}}

The !FileId comes again from the command line argument. The table name for the '''Images''' table can be altered by `--table.events`.

For source and pointing position, zenith distance and azimuth is calculated using `libnova` and the wrapper `Nova::GetHrzFromEqu`. The result is then rotated into the camera and projected on a plane which gives the x/y coordinates in the camera.

The result is then inserted into a table '''Position''' which name can be altered with `--table.position`. By default, all entries corresponding to the given !FileId are deleted from the table before the new positions are inserted running
{{{#!sql
DELETE FROM Position WHERE FileId=YYMMDDNNN
}}}


== Table Creation ==

It is not very handy if the SQL table has to be created manually beforehand. Therefore, `calcsource` can automatically create the table. To do this, specify `--create`. The query which would be used to create the table can be printed with `--print-create` even when `--create` has not been specified. Tables are created only if the do not yet exist (`CREATE TABLE IF NOT EXISTS`). To ensure recreation of a table, the old table can be dropped with `--drop`. As any insert operation would fail if the required table is dropped and no new one is created, `--drop` always implies `--create`.

The table is created as

{{{#!sql
CREATE TABLE IF NOT EXISTS Position
(
    FileId INT UNSIGNED NOT NULL,
    EvtNumber INT UNSIGNED NOT NULL,
    X FLOAT NOT NULL,
    Y FLOAT NOT NULL,
    PRIMARY KEY (FileId, EvtNumber)
)
DEFAULT CHARSET=latin1 COLLATE=latin1_general_ci
}}}

=== Database Engine ===

The default database engine is to create the table with the default of the database. If a database engine (`ENGINE=`) should be forced for the table the `--engine ENGINE` option can be used. Similarly, the row-format (`ROW_FORMAT=`) can be defined using `--row-format FORMAT`. For example:

{{{
--engine InnoDB --row-format=COMPRESSED
}}}

== Ignore duplicate entries ==

Usually, the `INSERT` query would fail if another row with the same primary key exists already.  This can be avoided adding the `IGNORE` keyword to the `INSERT` query by `--ignore-errors`, which essentially ignores all errors and turns them into warnings which are printed after the query succeeded.

If the `--update` option is given, column are updated with `ON DUPLICATE KEY UPDATE X=VALUES(X), Y=VALUES(Y)`.

== Source position ==

Instead of obtaining the source position automatically, right-ascension and declination can be specified manually with `--ra` and `--dec`.

== Focal Distance ==

For a correct calculation of X and Y, the focal distance has to be known. The default is 4889mm. It can be altered with `--focal-dist`.

== Debugging ==

The `INSERT` query can be skipped with `--insert`. A dry run which guarantees that nothing in the database is altered can be done with `--dry-run` (note that this might produce subsequent errors).

To print out the meta queries (DROP, CREATE, DELETE, SELECT), the option `--print-meta` exists. The longer `INSERT` query can be printed using `--print-insert`.