Deepsearch Software Docs: Conceptual Overview

Common Blocks

NOTE!!!: Most of the Deepsearch common blocks are No Longer Necessary! I encourage you NOT to use them unless either you're a paleolithic FORTRAN-style programmer who thinks that global common blocks are a good idea, or unless you're adapting old software and making the conversion is necessary. Otherwise, if you use freadimage2 in place of freadimage, freduceimage2 in place of freduceimage, etc., you don't have to mess with the Deepsearch common blocks at all!

If you don't want to use them, skip down to Data Types below

If you must use them....

Much of the deepsearch software you will use for anything makes implicit reference to a set of common blocks. This is a terrible, horrible concept that should really be replaced by OOP objects or, at the very least, pointers to structures, which is used to sling whole sets of data between various different routines.

The most fundamental of these objects is the "header buffers." If you've set up your IDL properly for the deepsearch software, when you run IDL you have defined a variable ims which is an array of structures. Each structure which is an element of that array has fields that represent various information about an image that, in anybody else's image analysis software, would probably be stored in the FITS header.

You never use element 0 of the ims structure. That is reserved for transformations to and from RA & Dec. (This will only make sense if you already understand some of the deepsearch software, so don't worry about it.) When you read in an image, if you want to do anything with it, you associated an ims buffer with it. For instance, in IDL try:

IDL> readimage,1,im1,'apr198btc3642csg.fts'
IDL> help,/str,ims[1]

(The help,/str is standard IDL to view the contents of a structure.) The structure ims[1] now has information about the image apr198btc3642csg.fts. Sometimes you will hear this be referred to as "image buffer 1", but note that the image data itself is not stored anywhere in ims[1], only header information.

Important Warning !!!!!

The deepsearch IDL software was developed by many who were not "real" programers and the use of our common block related to this BUFFER NUMBER is doubly messy by their hard-coding the temporary buffer numbers in their subroutines at random. Soon some of our codes became incompatible because they happened to use the same buffer number and thus overwriting each other. To remedy this particular problem, two simple routines were created: get_buff.pro & free_buff.pro . Any "utility" subroutine that does use buffer numbers for ims[ ] common block variables on its own way MUST use these two routines to avoid conflicts with all the other programs.

Instead of hard coding temporary buffer numbers like :

; Buffer usage ; 11 -- candidate refsys ; 12 -- chart image ; 13 -- apm proxy refsysbuf = 11 chartbuf = 12 proxybuf = 13 reduceimage,11,pho1,image=candsum.refsys the code must be written this way: buffers = get_buff(3) ;gets three unused buffer numbers refsysbuf = buffers(0) chartbuf = buffers(1) proxybuf = buffers(2) reduceimage,refsysbuf,pho1,image=candsum.refsys And when done with these three buffers, free them before returning to the parent level by : free_buff, buffers ;This marks the buffers as "free to use"

Another structure that you will probably never deal with explicitly, but which you will deal with implicitly, is the trns structure. This is a two-dimensional array of structures designed to store transformation coefficients between images. So, for instance, if you've run the proper routines (which will be documented later), trns[1,2] will hold the coefficients necessary to tranform coordinates on the image loaded into header buffer 1 (ims[1]) to coordinates on the image loaded into header buffer 2 (ims[2]). See the section on translations for information on how you would actually use this.

Data Types

Image Headers

When you read an image with freadimage2, you get back an "ims struct", or an image header. Try:

IDL> r=freadimage2(ims1,im1,'filename') IDL> help,/str,ims1

to see what fields there are in an ims1 struct. See Images and the Database for more information on figuring out what a good filename might be.

Image Data

When you read an image, the image data (variable im1 in the example above) is just a two-dimensional array of floating point numbers.

Photometry Lists

When you reduce an image, e.g. with

IDL> r=freduceimage2(ims1,im1,pho1)

you get back an array of type star_struct. You will also hear this structure referred to as a "pho" array on occasion (short for "photometry list"). Each element of this array represents one object (usually a star or a galaxy) found on the image. Use IDL's help,/str command to get more information about what is in this structure. (At some point in the future I hope to document specific elements of the structure.) Information on each object includes its position, identification, and brightness.