# E.S.O. - VLT project/ESO Archive
# $Id: TcsCatalog.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  27 Jun 96  Created
#

NAME
TcsCatalog - class for accessing TCS catalogs

SYNOPSIS
#include "TcsCatalog.h"

class TcsCatalog : public AstroCatalog {
public:
    TcsCatalog(const CatalogInfoEntry* e);
    virtual ~TcsCatalog();

    static TcsCatalog* open(const char* name);

    int numCols();
    char** colNames();
    const char* colName(int col);
    int colIndex(const char* colName);
    int hasCol(const char* name);
    
    int getObject(const char* id, TcsCatalogObject& obj);	      
    
    int searchClosestStar(const WorldCoords& pos, 
	double mag0, double mag1,		     
	TcsCatalogObject& obj);	     
};

DESCRIPTION
This class is a subclass of AstroCatalog specialized for accessing
GSC, PPM or similar catalogs for use by the TCS (Telescope Control
Software).  A TcsCatalog is like an AstroCatalog, except that it
assumes a catalog has fixed columns, such as those that are found in
the GSC or PPM catalogs.  This class restricts itself to these fixed
columns and ignores the rest.  Each row of a TcsCatalog can be
represented by a TcsCatalogObject. Any missing column values are set
to the appropriate null value (defined in TcsCatalogObject.h).

CATALOG SERVERS
This class uses the same catalog servers as the AstroCatalog class. Please
refer to AstroCatalog for details.

LOCAL CATALOGS
The format of local catalog files and query results that are stored in
files is the same here as in AstroCatalog, except that here the
column names are fixed. In addition, catalogs saved in TCS format
contain additional comments in the header indicating that the catalog
is a TCS catalog and with the meanings of the columns. 

UNITS
Unless otherwise stated, the units for all radius values are in arcmin.
Floating point values for RA and DEC are always in degrees. The
default equinox is J2000.

QUERY PARAMETERS
Parameters for catalog searches are checked to make sure they are
valid and in the correct range. A radius value must be between 0.0 and
300.0 arcmin.  A magnitude may have any value. For ranges, such as min
and max radius and min and max magnitude, the order of the arguments
is not important, since they will be rearranged as needed. If both min
and max values are 0.0, they are ignored for that search. If you
really want to search for objects with "0.0" magnitude, specify a
range with small values that are not zero, for example, min/max mag =
(-0.0001, +0.0001).

PUBLIC METHODS
TcsCatalog(const CatalogInfoEntry* e)
	Constructor - create a TCS catalog class instance.  Note: the
	public interface normally uses TcsCatalog::open().  The
	argument represents the entry in the catalog config file for
	this catalog.

~TcsCatalog()
	Destructor - close catalog and free any resources.

open(const char* name)
	Open the named catalog and return a pointer to a new
	TcsCatalog (or derived class) object created for it or NULL if
	errors occur. If the given name is really the name of a file,
	it is opened as a local catalog and the pointer returned is of
	type TcsLocalCatalog, a subclass of TcsCatalog. If the file
	is not in the correct format, a NULL pointer is returned.

numCols()
	Return the number of columns in the catalog (fixed number).

colNames()
	Return an array of column names (this is always the same for
	TCS catalogs).
 
colName(int col)
	Return the name of the given column (fixed for TCS catalogs).

colIndex(const char* colName)
	Return the column index for the given column name (fixed for
	TCS catalogs).

hasCol(const char* name)
	Return true if the catalog contains the given column (fixed
	for TCS catalogs).

int getObject(const char* id, TcsCatalogObject& obj)
	This method is redefined in this class to get the object given
	by "id" in the catalog and return 0 if all is OK.  Note that
	the interface is changed here to use the TcsCatalogObject to
	hold the result rather than a QueryResult as in the parent
	class version.

	Arguments:

	id,	 	(in ) - object id in catalog.
	obj	      	(out) - object for row, if found.

int searchClosestStar(const WorldCoords& pos, double mag0, double mag1, 
	              TcsCatalogObject& obj)
	This method is redefined in this class to search for the star
	closest to the given position, with the magnitude in the given
	range. Note that the interface is changed here to use the
	TcsCatalogObject to hold the result rather than a QueryResult
	as in the parent class version.

	Arguments:

	pos,	     	(in )  - center position in world coordinates
	mag0,	     	(in )  - min magnitude 
	mag1,	    	(in )  - max magnitude 
	obj		(out)  - object for row, if found

SEE ALSO

AstroCatalog, TcsCatalogObject(3C++), TcsQueryResult(3C++), 
TcsLocalCatalog, tcscat(n)
----------------------------------------------------------------------
