# $Id: astro_image.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  16 Oct 95  Created
#

NAME
astroImage - C Library for accessing astronomical image servers (obsolete)

SYNOPSIS
#include "astroImage.h"

typedef void* AiHandle;

AiHandle aiOpen(char* name);

void aiClose(AiHandle);

char* aiGetImage(AiHandle handle, double ra, double dec, 
		 double width, double height);

DESCRIPTION
Note: This interface is obsolete. Please use the astroCatalog
interface, which now also supports image servers.

This man page describes a library for accessing astronomical image
servers from C applications in a generic way.

Note: Although the library is implemented in C++, it also defines a C
interface, which is described here.  To use this library from C, an
application must have a C++ main and be linked with the C++
compiler. This is easily done by renaming the C main to c_main and
defining a C++ main that calls it.

The main purpose of this library is to provide generic access to a
variety of astronomical image servers available locally or on the
network.  The interface hides the details of accessing the various
servers.

IMAGE SERVERS
This class communicates with an image server via HTTP requests. The
list of servers and how to access them is kept in a configuration
file, which is also accessed via HTTP. The default config file is:

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

The default can be overridden by defining the environment variable
SKYCAT_CONFIG to another valid HTTP URL.

ERROR HANDLING
Most of the routines described here return non-zero on error and zero
if all is OK (routines that return pointers return a NULL pointer on
error). The text of the error message can be retrieved with the
acGetError() function and an error code is available via the
acGetErrorCode function. The error codes are the same as those in
<errno.h> and have the same meanings (EINVAL means invalid operand -
or parameter, 0 means no code was available). 

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.

C ROUTINES
aiOpen
	Open the named image server and return a handle for it or NULL
	if there were errors. The handle can be used in subsequent
	operations on the image server.
	Arguments:
		name (in) - image server name
	Return value: 
		image server handle for use in future calls

aiClose
	Close the image server connection and free its resources.
	Arguments:
		handle (in) - image server handle
	Return value: 
		None

aiGetImage
        Pass a request to the image server and return the name of a
        FITS file containing the resulting image, or NULL if not
        found. The return filename is the name of a temporary file
        that will be reused on the next call to this routine.
	Arguments:
		handle (in) - image server handle
		ra        (in ) - world coordinates of center point
		dec	  (in ) - in degrees	
		width	  (in ) - width of image in arc-minutes
		image	  (in ) - height of image in arc-minutes
	Return value: 
		pointer to temporary FITS file containing image

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

