# E.S.O. - VLT project/ESO Archive
# $Id: AstroCatalog.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  17 Oct 95  Created
#

NAME
AstroCatalog - C++ class for accessing astromical catalogs

SYNOPSIS
#include "AstroCatalog.h"

class AstroCatalog {
...
public:
    AstroCatalog(const CatalogInfoEntry*);

    virtual ~AstroCatalog();

    static AstroCatalog* open(const char* name);

    static int nameToWorldCoords(
	const char* objName, 
	WorldCoords& pos,
	const char* nameServer = "simbad_ns@eso", 
	FILE* feedback = NULL);

    virtual int query(
	const AstroQuery& q, 
	const char* filename, 
	QueryResult& result);

    const char* symbol();
    const char* searchCols();
    const char* sortCols();
    const char* sortOrder();
    const char* showCols();
    const char* copyright();

    int id_col();
    int ra_col();
    int dec_col();
    int x_col();
    int y_col();
    int is_tcs();
    int isWcs();

    double equinox();

    int getPreview(const char* url, char*& content_type);

    CatalogInfoEntry* entry();

    void feedback(FILE* f);

    int status();

    const char* name();
    const char* longName();
    const char* shortName();

    const char* servType();

    virtual int numCols() ;
    virtual char** colNames() ;
    virtual const char* colName(int col);

    virtual int colIndex(const char* colName);

    int hasCol(const char* name);

    int more();

    int getDescription(
	int& numCols,
	char**& colNames);
   
    int getObject(
	const char* id,
	int numCols,
	char** colNames,
	QueryResult& result);
    
    int getArea(
	int numCols,
	char** colNames,
	const WorldCoords& pos0,
	const WorldCoords& pos1,
	double mag0,
	double mag1,
	int maxRows,
	const char* filename,
	int& numFound,
	QueryResult& result);

    int circularSearch(
	int numCols,
	char** colNames,
	const WorldCoords& pos,
	double radius0,
	double radius1,
	double mag0,
	double mag1,
	int maxRows,
	const char* filename,
	int& numFound,
	QueryResult& result);

    int searchClosestStar(
	int numCols,
	char** colNames,
	const WorldCoords& pos,
	double mag0,
	double mag1,
	QueryResult& result);

    int CatalogSearch(
	int numCols,
	char** colNames,
	int numSearchCols,
	char** searchCols,
	char** minVals,
	char** maxVals,
	int maxRows,
	const char* filename,
	int& numFound,
	QueryResult& result);

    static const char* getError();
    static void clearError();
};

DESCRIPTION
This class manages access to astronomical catalogs. The main entry
point is the "open" method, which returns a pointer to an AstroCatalog
object to be used to access the named catalog. This object should be
deleted with "delete" when no longer needed.

CATALOG SERVERS
This class communicates with catalog servers via HTTP requests. The
lists of servers and how to access them are kept in configuration
files, which are accessed via HTTP or read from local files.  The
default catalog config file is a hard coded URL:

    http://archive.eso.org/skycat/skycat2.0.cfg

The default can be overridden by defining the environment variable
CATLIB_CONFIG to another valid HTTP URL. For compatibility with
previous versions, the environment variable SKYCAT_CONFIG may also be
used.

LOCAL CATALOGS
If the catalog name passed to the open method is the name of a file,
it is taken to be a local catalog file in tab table format. This is
the same format used by the Starbase utilities. A local catalog is an
ASCII file containing an optional title and header information
followed by the column headings, a dashed line and the data rows. The
columns are separated by tabs. This is also the format of query
results returned via HTTP from remote catalog servers.

Example:

Table1

# comment line

# The header may contain catalog config information...
symbol: mag circle 15-$mag
search_cols:    mag "Brightest (min)" "Faintest (max)"

id	ra	dec	pos-e	mag
------	--	---	-----	---
A00050	3:19:28	8:26:29	0.2	13.49
A00098	3:19:32	8:34:15	0.4	13.40
A00288	3:19:21	8:31:19	0.2	13.13
A00314	3:19:44	8:30:58	0.2	13.98

The format of a local catalog is the same as the format of the result
of a query to a remote catalog. The header may contain comments (with
'#') and optional configuration information in the same format as the
catalog config files.

The pointer returned from the open method for files is a pointer to a
LocalCatalog object, a subclass of AstroCatalog specialized in dealing
with local catalogs. The interface is the same for remote and local
catalogs, only the implementation is different in some ways (some
virtual methods are redefined in the derived class).

UNITS
Unless otherwise stated, the units for all radius values are in arcmin
for catalogs that support World Coordinates and image pixels for
catalogs that do not. A catalog is considered to support World
Coordinates if the values of ra_col and dec_col in the catalog config
entry are valid (they are 1 and 2 by default). If x_col and y_col were
given, the catalog is considered to be using image pixel coordinates.

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).

FORMAT OF QUERY RESULTS
Catalog query results are returned in a class QueryResult object. This
object is used to access values based on a row and column index or
column name. Overloaded "get" methods allow column values to be
retrieved as int, short, float, double, char, char*, or WorldCoords
(internally, the values are stored as strings).

MEMORY MANAGEMENT
Memory is allocated internally for the query results.  It is the
caller's responsibility to delete the result object when no longer
needed.

PUBLIC METHODS
open(name)
        Open the named catalog and return a pointer an AstroCatalog
	(or LocalCatalog) object allocated for the catalog, or NULL if
	errors occur.

	Arguments:
		name (in) - catalog name or file name for local catalogs
	Return value: 
		pointer to an allocated AstroCatalog or derived object


query(q, filename, result)
	Pass the given query to the catalog server and return the
	number of objects found.

	Arguments:

		q         (in ) - AstroQuery object, describes query.

		filename  (in ) - Optional file name: if not NULL, a copy of
				  the results from the server is written to
				  the given file.

		result    (out) - Set on successful return to contain and 
                   		  manage the query results. 
	Return value: 
		The number of objects found, or -1 if errors occured.

nameToWorldCoords(objName, pos, nameServer, feedback)
	Use a name server catalog (like simbad_ns@eso or ned_ns@eso)
	to get the coordinates from the object name. If feedback is
	not NULL, status info is written to the given open file.

	Arguments:
   		objName    (in ) - name of star or astronomical object
    		pos        (out) - reference to WorldCoords object result
		nameServer (in ) - name server to use to resolve name
		feedback   (in ) - file pointer for user interface feedback
	Return value: 
		If successful, 0, otherwise 1.

getDescription(numCols, colNames)
	Get the number of columns and the column names for the given
	catalog and return 0 if all is OK. The memory for the return
	arrays is managed internally and should not be modified by the
	caller.

	Arguments:
   		numCols  (out) - number of catalog columns
    		colNames (out) - reference to array of column names
	Return value: 
		If successful, 0, otherwise 1.


getObject(id, numCols, colNames, result)	
	Get the values for the specified columns for the object given
	by "id" in the catalog and return 0 if found. The id should be
	a valid object id obtained by a previous catalog query.  If
	colNames is not NULL, it should be an array of column names to
	fetch, otherwise all columns are fetched. The result argument
	is set on return to contain the results of the query.

    	Arguments:
   		id        (in ) - object id

		numCols   (in)  - number of columns (column names)

    		colNames  (in ) - array of column names to read, or 
				  NULL to read all columns.

		result (in/out) - set from query result data
	Return value: 
		Returns 0 if there were no errors, otherwise 1. It is not
		considered an error if no object was found.

getArea(numCols, colNames, pos0, pos1, mag0, mag1, maxRows, filename,
        numfound, results)
	Get the values for all objects in the rectangular region given
	by the two world coordinate points. If mag0 and mag1 are not
	0.0, they are taken to be the minimum and maximum magnitude
	values for the query. If colNames is not NULL, it should be an
	array of column names to fetch, otherwise all
	columns are fetched. The number of object rows returned is
	limited to maxRows (the more() method can be called to see
	if more objects would have been available). 

	On return, numFound is set to the number of objects found and,
	if any were found, result is set to be used for accessing the
	results.

	If filename is not NULL, the results will be copied to the
	given file in the format of a local catalog.

	Arguments:
		numCols   (in)  -  number of columns (column names)

    		colNames  (in ) - array of column names to read, 
				  or NULL to read all

		pos0      (in ) - world coordinates of first point

		pos1	  (in ) - world coordinates of second point

		mag0	  (in ) - min magnitude

		mag1	  (in ) - max magnitude

		maxRows   (in ) - max number of rows to return

		filename  (in ) - if not null, write results to this 
				  file

		numFound  (out) - number of objects found

		result (in/out) - set to contain query result
	Return value: 
		If successful, 0, otherwise 1.

			
circularSearch(numCols, colNames, pos, radius0, radius1, mag0, mag1, 
		maxRows, filename, numFound, result)
	Get the values for all objects in the circle or ring given by
	the world coordinate point and the min and max radius values.
	If mag0 and mag1 are not 0.0, they are taken to be the minimum
	and maximum magnitude values for the query. If colNames is not
	NULL, it should be an array of column names to fetch,
	otherwise all columns are fetched. The number of object rows
	returned is limited to maxRows (the more() method can be
	called to see if more objects would have been available).

	On return, numFound is set to the number of objects found and,
	if any were found, result is set to be used for accessing the
	results.

	If filename is not NULL, the results will be copied to the
	given file in the format of a local catalog.

	Arguments:
		numCols   (in)  -  number of columns (column names)

    		colNames  (in ) - array of column names to read, or
				  NULL to read all

		pos       (in ) - world coordinates of center point

		radius0	  (in ) - min radius from center point

		radius1	  (in ) - max radius from center point

		mag0	  (in ) - min magnitude

		mag1	  (in ) - max magnitude

		maxRows   (in ) - max number of rows to return

		filename  (in ) - if not null, write results to this 
				  file

		numFound  (out) - number of objects found

		result (in/out) - filled with query result
	Return value: 
		If successful, 0, otherwise 1.


searchClosestStar(numCols, colNames, pos, mag0, mag1, result)	
	Get the values for the specified columns for the object in the
	catalog closest to the given position and return 0 if
	found. If colNames is not NULL, it should be an array of
	column names to fetch, otherwise all columns are fetched. If
	mag0 and mag1 are not 0.0, they are taken to be the minimum
	and maximum magnitude values for the query. The result argument
	is set on return to contain the query results.

    	Arguments:
		numCols   (in)  - number of columns (column names)

    		colNames  (in ) - array of column names to read, 
				  or NULL to read all columns.

		pos       (in ) - world coordinates of point

		mag0	  (in ) - min magnitude

		mag1	  (in ) - max magnitude

 		result (in/out) - set to contain the query result
	Return value: 
		Returns 0 if there were no errors, otherwise 1. It is not
		considered an error if no object was found.

CatalogSearch(numCols, colNames, numSearchCols, searchCols, minVals, 
		maxVals, maxRows, filename, numFound, result)	
	Get the values for all objects fulfilling the specified
	criteria.  The criteria are given by the array of column names
	to compare and two arrays of the same size containing min and
	max values, in string format, corresponding to the column
	names. Null strings are ignored, so, for example, if there is
	no min value, only the max value will be used.  If colNames is
	not NULL, it should be an array of column names to fetch,
	otherwise all columns are fetched. The number of object rows
	returned is limited to maxRows (the more() method can be
	called to see if more objects would have been available).  On
	return, numFound is set to the number of objects found and, if
	any were found, "result" is set for accessing the catalog
	values found.  If filename is not NULL, the results will be
	copied to the given file in the format of a local catalog

    	Arguments:
		numCols   (in)  - number of columns (column names)

    		colNames  (in ) - array of column names to read, 
				  or NULL to read all columns.

		numSearchCols (in ) - number of column names to compare 

		searchCols (in ) - array of column names to compare 

    		minVals   (in ) - array of column minimum values

    		maxVals   (in ) - array of column maximum values

		maxRows   (in ) - max number of rows to return

		filename  (in ) - if not null, write results to this 
				  file

		numFound  (out) - set to number of objects found

		result (in/out) - contains query result

	Return value: 
		Returns 0 if there were no errors, otherwise 1.

getError()
	Return the text of the most recent error message reported by
	the catalog classes.

clearError()
	Reset the error message buffer to empty.

numCols()
        Return the number of columns in result lists.

colName(col)
        Return the name of the given column (columns are numbered
        starting with zero).

colNames()
	Return an array of the catalog column names.

colIndex(name)
	Return the catalog column index for the given column name.
    
hasCol(name)
	Return true if the catalog contains the given column.

status()
        Return the status (after constructor) for error checking.
	If no errors occured, a value of 0 is returned.

more()
        Return true if more than "maxRows" rows would have been
        available to the last call to query().

name()
longName()
shortName()
        Return the name (long name) or short name of this catalog.
	These are values defined in the catalog config file.

symbol()
searchCols()
sortCols()
sortOrder()
showCols()
copyright()
id_col()
ra_col()
dec_col()
x_col()
y_col()
is_tcs()
isWcs()
equinox()
	All these methods return the corresponding values from the
	catalog config entry for the current catalog.

getPreview(url, content_type)
	Given a URL pointing to preview data (FITS image or tab table
	data), request the data from the server and return 0 if all is
	OK.  On return, if there were no errors, the "ctype" argument
	is set to the Content-type of the result to indicate the type
	of data. The data is automatically decompressed if needed (if
	the content-type is recognized).  The "tmpfile()" method gives
	the name of the file containing the results on success.

entry()
	Return a pointer to the catalog config entry for the open
	catalog.

feedback(FILE)
	Set the file pointer to use for http feedback during transfers.


SEE ALSO
AstroImage, WorldCoords(3C++)
----------------------------------------------------------------------

