#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(); };
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.
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.
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).
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.
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).
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 is allocated internally for the query results. It is the caller's responsibility to delete the result object when no longer needed.
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.
Please send questions or comments to abrighto@eso.org@eso.org.
Copyright © 1998 ESO - European Southern Observatory