idlastro / Database Procedures: DBCIRCLE

[Source code]

NAME
DBCIRCLE
PURPOSE
Find sources in a database within specified radius of specified center
EXPLANATION
Database must include items named 'RA' (in hours) and 'DEC' (in degrees)
and must have previously been opened with DBOPEN
CALLING SEQUENCE
list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT, 
                           /GALACTIC, TO_B1950, /TO_J2000, COUNT= ] )   
INPUTS
RA_CEN - Right ascension of the search center in decimal HOURS, scalar
DEC_CEN - Declination of the search center in decimal DEGREES, scalar
        RA_CEN and DEC_CEN should be in the same equinox as the 
        currently opened catalog.
OPTIONAL INPUT
RADIUS - Radius of the search field in arc minutes, scalar.
        DBCIRCLE prompts for RADIUS if not supplied.
SUBLIST - Vector giving entry numbers in currently opened database
        to be searched.  Default is to search all entries
OUTPUTS
LIST - Vector giving entry numbers in the currently opened catalog
       which have positions within the specified search circle
       LIST is set to -1 if no sources fall within the search circle
OPTIONAL OUTPUT
DIS -  The distance in arcminutes of each entry specified by LIST
        to the search center (given by RA_CEN and DEC_CEN)
OPTIONAL KEYWORD INPUT
/GALACTIC - if set, then the first two parameters are interpreted as
          Galactic coordinates in degrees, and is converted internally
          to J2000 celestial to search the database.   
/SILENT - If this keyword is set, then DBCIRCLE will not print the 
        number of entries found at the terminal
/TO_J2000 - If this keyword is set, then the entered coordinates are
        assumed to be in equinox B1950, and will be converted to
        J2000 before searching the database
/TO_B1950 - If this keyword is set, then the entered coordinates are
        assumed to be in equinox J2000, and will be converted to
        B1950 before searching the database
        NOTE: The user must determine on his own whether the database
        is in B1950 or J2000 coordinates.
OPTIONAL KEYWORD OUTPUT
COUNT - - Integer scalar giving the number of valid matches
METHOD
A DBFIND search is first performed on a square area of given radius.
The list is the restricted to a circular area by using GCIRC to 
compute the distance of each object to the field center.
RESTRICTIONS;
The database must have items 'RA' (in hours) and 'DEC' (in degrees).
Alternatively, the database could have items RA_OBJ and DEC_OBJ 
both in degrees)
EXAMPLE
Find all Hipparcos stars within 40' of the nucleus of M33
(at J2000 1h 33m 50.9s 30d 39' 36.7'')
IDL> dbopen,'hipparcos'
IDL> list = dbcircle( ten(1,33,50.9), ten(3,39,36.7), 40)
PROCEDURE CALLS
BPRECESS, DBFIND(), DBEXT, DB_INFO(), GCIRC, GLACTC, JPRECESS
REVISION HISTORY
Written W. Landsman     STX           January 1990
Fixed search when crossing 0h         July 1990
Spiffed up code a bit     October, 1991
Leave DIS vector unchanged if no entries found W. Landsman July 1999
Use maximum declination, rather than declination at field center to
correct RA for latitude effect    W. Landsman   September 1999
Added COUNT, GALACTIC keywords  W. Landsman   December 2008
Fix problem when RA range exceeds 24h  W. Landsman   April 2009
Work as advertised for RA_OBJ field  W. Landsman June 2010
Fix occasional problem when crossing 0h  E. Donoso/W.Landsman Jan 2013
Check if database has been opened W. Landsman Aug 2013
onvert from Galactic
ize of search field in degrees
pdated Sep 1999
orrect for latitude effect
nly need search on Dec?
If minimum RA is less than 0, or maximum RA is greater than 24
then we must break up into two searchs
tem RA_OBJ assumed to be in degrees
Use GCIRC to compute angular distance of each source to the field center
ny entries found?