;+ ; NAME: ; oc_getstar_ucac2 ; ; PURPOSE: (one line) ; Returns UCAC2 star structures given their ID's. ; ; DESCRIPTION: ; Returns a fully-populated UCAC2 star structure for each ID supplied. ; The ID's must be in the UCAC2 format. The star structure is returned in ; the standard format, and includes the raw UCAC2 data as well as ; standard-format RA, DEC, magnitudes, etc. ; ; CATEGORY: ; Star catalogs ; ; CALLING SEQUENCE: ; oc_getstar_ucac2, ids [, NSTARS=nstars] [, /VERBOSE] ; ; INPUTS: ; ids -- UCAC2 id's in string format. Can be either scalar or vector. ; Either SCAT-format ('221.00434') or standard UCAC2 ; format ('00534450'), but all ids must be in the same format. ; ; OPTIONAL INPUT PARAMETERS: ; None ; ; KEYWORD INPUT PARAMETERS: ; VERBOSE -- Print messages about incorrect/missing ID's to screen if set. ; ; KEYWORD OUTPUT PARAMETERS: ; NSTARS -- Returns the number of successfully-retrieved stars ; ; OUTPUTS: ; Structures of type 'star' with fields filled in. ; Returns either a vector or a scalar depending on input value 'ids'. ; Length of returned value is the same as that of input 'ids.' ; The field star.ucac2.record is the UCAC2 raw binary catalog entry. ; The fileds in star.ucac2.* are exactly as described in the ; UCAC2 CD-ROM 'readme.txt' file. ; If a star is not found, that entry is blank. ; ; COMMON BLOCKS: ; None ; ; SIDE EFFECTS: ; None ; ; RESTRICTIONS: ; UCAC2 catalog must be available on local filesystem, ; in files $UCAC2_PATH/u2/{z001 .. z288} ; ; EXAMPLE: ; star = oc_getstar_ucac2(['35213093','35396495']) ; ; MODIFICATION HISTORY: ; Written 10-Jan-2006 by Henry Throop, SwRI ; Modified 23-Feb-2006 by HBT. Improved documentation and formatting. ; Modified 26-Feb-2006 by LAY. Allow scalar id. ; Fix bug in star.et (convert EpRAm and EpDEm to ; double before averaging to avoid INT warparound) ; Fixed comment above star.decer ; Fixed conversion and cos dec factors in ; star.radot, decdot, radoterr, and decdoterr. ; Modified 24-Mar-2006 by HBT. Added handling of proper motion with ; ETPM, ra_etpm, etc. ; Modified 14-Apr-2006 by Leslie Young. Made loop index long. ;- ; ** Description of UCAC2 format ** ; Num Bytes Fmt Unit Label Explanation ; ----------------------------------------------------------------------------- ; 1 1- 4 I*4 mas RA Right Ascension at epoch J2000.0 (ICRS) (2) ; 2 5- 8 I*4 mas DE Declination at epoch J2000.0 (ICRS) (2) ; 3 9-10 I*2 0.01 mag U2Rmag Internal UCAC magnitude (red bandpass) (3) ; 4 11 I*1 mas e_RAm s.e. at central epoch in RA (*cos DEm)(1,4) ; 5 12 I*1 mas e_DEm s.e. at central epoch in Dec (1,4) ; 6 13 I*1 nobs Number of UCAC observations of this star(5) ; 7 14 I*1 e_pos Error of original UCAC observ. (mas) (1,6) ; 8 15 I*1 ncat # of catalog positions used for pmRA, pmDC ; 9 16 I*1 cflg ID of major catalogs used in pmRA, pmDE (7) ; 10 17-18 I*2 0.001 yr EpRAm Central epoch for mean RA, minus 1975 (8) ; 11 19-20 I*2 0.001 yr EpDEm Central epoch for mean DE, minus 1975 (8) ; 12 21-24 I*4 0.1 mas/yr pmRA Proper motion in RA (no cos DE) (9) ; 13 25-28 I*4 0.1 mas/yr pmDE Proper motion in DE (9) ; 14 29 I*1 0.1 mas/yr e_pmRA s.e. of pmRA (*cos DEm) (1) ; 15 30 I*1 0.1 mas/yr e_pmDE s.e. of pmDE (1) ; 16 31 I*1 0.05 q_pmRA Goodness of fit for pmRA (1,11) ; 17 32 I*1 0.05 q_pmDE Goodness of fit for pmDE (1,11) ; 18 33-36 I*4 2m_id 2MASS pts_key star identifier (12) ** The 2m_* fields must be renamed in IDL ** ; 19 37-38 I*2 0.001 mag 2m_J 2MASS J magnitude (13) ; 20 39-40 I*2 0.001 mag 2m_H 2MASS H magnitude (13) ; 21 41-42 I*2 0.001 mag 2m_Ks 2MASS K_s magnitude (13) ; 22 43 I*1 2m_ph 2MASS modified ph_qual flag (1,14) ; 23 44 I*1 2m_cc 2MASS modified cc_flg (1,15) ; ----------------------------------------------------------------------------- function oc_getstar_ucac2, ids_in, NSTARS=nstars, VERBOSE=verbose if is_scalar(ids_in) then ids = [ids_in] else ids = ids_in path_catalog = getenv('UCAC2_PATH') + '/u2/' d2r = 2*!dpi / 360d ; Degrees -> radians r2d = 1/d2r as2d = 1/(60d * 60d) ; Arcsec -> degrees mas2d = as2d / 1000d ; mArsec -> degrees mas2r = mas2d * d2r ; mArsec -> radians yr2sec = 31557600d ; Year -> seconds. ; 31557600. from cspice_jyear. ; Initialize all of the proper *STAR* variables idcat = ['', ''] id = ['', ''] poscat = '' et = 0d ; Epoch after PM application ra = 0d dec = 0d raerr = 0d decerr = 0d radot = 0d decdot = 0d radoterr = 0d decdoterr = 0d etpm = [0d, 0d] ; ET at which PM=0. ra_etpm = 0d ; RA at PM=0 dec_etpm = 0d ; DEC at PM=0 raerr_etpm = 0d ; RA err at PM=0 decerr_etpm = 0d ; Dec err at PM=0 magcat = ['', '', '', ''] magname = ['', '', '', ''] mag = [0d, 0d, 0d, 0d] magerr = [0d, 0d, 0d, 0d] SpTcat = '' SpT = '' notecat = [''] note = [''] ; Initialize all of the proper *UCAC2* variables. ; All values are kept as their original format, even if this is a little ; unusual (e.g., 0.001 yrs since 1975, etc.) RA = 0L ; RA, J2000, in mas ; ** Careful here: conflicts with Star.ra DE = 0L ; Dec, J2000, in mas U2Rmag = 0 ; Internal UCAC red magnitude e_RAm = 0B ; Error of RA * cos Dec, in mas e_DEm = 0B ; Error of Dec, in mas nobs = 0B ; Number of UCAC2 obs of this star e_pos = 0B ; Error of original UCAC obs, in mas ncat = 0B ; Number of catalog positions used for pm cflg = 0B ; ID of catalogs usd for pm (decoded where?) EpRAm = 0 ; Epoch of RA, minus 1975. In 0.001 yrs. EpDEm = 0 ; Epoch of DE, minus 1975. In 0.001 yrs. pmRA = 0L ; Proper motion in RA (no cos DE applied), ; 0.1 mas/yr. pmDE = 0L ; Proper motion in Dec, 0.1 mas/yr e_pmRA = 0B ; Error of pmRA (*cos Dec), 0.1 mas/yr e_pmDE = 0B ; Error of pmDE, 0.1 mas/yr q_pmRA = 0B ; Quality of PM q_pmDE = 0B ; Quality of PM m2_id = 0L ; 2MASS pts_key ID. Was 2m_id, ; but invalid IDL variable m2_J = 0 ; 2MASS J magnitude. Was 2m_J -> m2_J, etc. m2_H = 0 ; 2MASS H magnitude m2_Ks = 0 ; 2MASS k_s magnitude m2_ph = 0B ; 2MASS ph_qual flag m2_cc = 0B ; 2MASS cc_flg ; 'Record' is not a UCAC2 field. It stores the entire UCAC2 catalog line ; entry, as stored on disk, and before any conversion to integers, floats, ; etc. record = bytarr(44) ucac2 = {RA:RA, DE:DE, U2Rmag:U2Rmag, e_RAm:e_RAm, e_DEm:e_DEm, $ nobs:nobs, e_pos:e_pos, ncat:ncat, cflg:cflg, $ EpRAm:EpRAm, EpDEm:EpDEm, pmRA:pmRA, pmDE:pmDE, $ e_pmRA:e_pmRA, e_pmDE:e_pmDE, q_pmRA:q_pmRA, $ q_pmDE:q_pmDE, m2_id:m2_id, m2_J:m2_J, m2_H:m2_H, $ m2_Ks:m2_Ks, m2_ph:m2_ph, m2_cc:m2_cc, record:record} star = {idcat:idcat, id:id, poscat:poscat, et:et, $ ra:0d, dec:0d,$ raerr:raerr, decerr:decerr, radot:radot, decdot:decdot, $ radoterr:decdot, decdoterr:decdoterr, $ etpm:etpm, ra_etpm:ra_etpm, dec_etpm:dec_etpm, $ raerr_etpm:raerr_etpm, decerr_etpm:decerr_etpm, $ magcat:magcat, magname:magname, mag:mag, magerr:magerr, $ sptcat:sptcat, spt:spt, notecat:notecat, note:note, $ ucac2:ucac2} ucac2_init = ucac2 star_init = star num_ids = sizex(ids) stars = make_array(num_ids, value=star) ; Convert the id formats. We need *both* scat-formatted and ; ucac2-formatted ID's here. if grep (ids[0], '\.') then begin ids_scat = ids ids_ucac2 = oc_convertid_ucac2(SCAT=ids) end $ else begin ids_ucac2 = string(ids) ids_scat = oc_convertid_ucac2(UCAC2=ids) end ; Get the catalog entry line for each star lines = oc_getline_ucac2(ids_scat, nstars=nstars, verbose=verbose) ; Loop over every star and fill in the fields for i = 0L, num_ids-1 do begin id = ids_ucac2[i] line = lines[i,*] ; Parse the raw catalog line into a bunch of variables if (total(abs(line)) eq 0) then begin star = oc_star_set_empty(star_init) goto, parse_end end ; Clear the star structure, then stick each variable into its proper ; *UCAC2* structure location The byte numbers and their offsets (-127) are ; described in UCAC2's readme.txt file. We apply these offsets, so that ; the numbers we return here match those from UCAC2's u2dumpz.f program. ucac2 = ucac2_init star = star_init ucac2.record = line ucac2.ra = bytes2long(line[0:3]) ucac2.de = bytes2long(line[4:7]) ucac2.U2Rmag = bytes2int (line[8:9]) ucac2.e_RAm = bytes2byte(line[10]) + byte(127) ucac2.e_DEm = bytes2byte(line[11]) + byte(127) ucac2.nobs = bytes2byte(line[12]) ucac2.e_pos = bytes2byte(line[13]) + byte(127) ucac2.ncat = bytes2byte(line[14]) ucac2.cflg = bytes2byte(line[15]) ucac2.EpRAm = bytes2int (line[16:17]) ucac2.EpDEm = bytes2int (line[18:19]) ucac2.pmRA = bytes2long(line[20:23]) ucac2.pmDE = bytes2long(line[24:27]) ucac2.e_pmRA = bytes2byte(line[28]) + byte(127) ucac2.e_pmDE = bytes2byte(line[29]) + byte(127) ucac2.q_pmRA = bytes2byte(line[30]) + byte(127) ucac2.q_pmDE = bytes2byte(line[31]) + byte(127) ucac2.m2_id = bytes2long(line[32:35]) ucac2.m2_j = bytes2int (line[36:37]) ucac2.m2_h = bytes2int (line[38:39]) ucac2.m2_ks = bytes2int (line[40:41]) ucac2.m2_ph = bytes2byte(line[42]) + byte(127) ucac2.m2_cc = bytes2byte(line[43]) + byte(127) ; Process the variables and stick them all into the proper ; *STAR* structure location. ; No precession is necessary, since UCAC2 is already in J2000. star.idcat = ['ucac2', '2mass'] star.id = [ids_ucac2[i], string(ucac2.m2_id)] star.poscat = 'ucac2' ; We default ET to 2000. This is the RA/DEC which UCAC2 catalog is ; supplied with. ; Epoch of original obs, for proper motions. ; NB: We must divide before adding in order to avoid integer wraparaound star.et = 0d ; Convert RA to radians. Epoch = 2000, equinox = J2000. star.ra = ucac2.ra * mas2r star.dec = ucac2.de * mas2r ; Error of RA * cos(Dec). See readme.txt. Radians. ; Catalog error is at ETPM, *not* epoch 2000, even though ; catalog position is at epoch 2000. star.raerr_etpm = ucac2.e_RAm * mas2r ; Error of Dec. See readme.txt. Radians. star.decerr_etpm = ucac2.e_DEm * mas2r ; Proper motion, 0.1mas/yr -> radians/sec. star.radot = ucac2.pmRA * cos(star.dec) * 0.1d*mas2r/yr2sec ; Proper motion, 0.1mas/yr -> radians/sec. star.decdot = ucac2.pmDE * 0.1d*mas2r/yr2sec ; Error of pm, 0.1mas/yr -> radians/sec star.radoterr = ucac2.e_pmRA * 0.1d*mas2r/yr2sec ; Error of pm, 0.1mas/yr -> radians/sec star.decdoterr = ucac2.e_pmDE * 0.1d*mas2r/yr2sec ; ETPM -- default RA, Dec at which PM to apply is zero ; (ie, time at which obs was taken) ; For UCAC2, EpRAm, EpDEm are thousandths of a year since 1975 ; We convert this into seconds since 2000. ; For UCAC2, most of these years are in the 1990 range. ; star.et: Set to 2000 ; star.etpm: It is ~1990 in catalog ; EpRAm -- mean epoch. star.etpm = [(ucac2.EpRAm/1000d)+1975d - 2000d, $ (ucac2.EpDEm/1000d)+1975d - 2000d] * $ yr2sec ; RA_ETPM -- RA at ETPM (ie, ~time at obs was taken). ; We subtract out the PM, since catalog is *not* supplied ; with the actual RA at ETPM. star.ra_etpm = star.ra + star.radot/cos(star.dec) * $ (star.etpm[0]-star.et) star.dec_etpm = star.dec + star.decdot * $ (star.etpm[1]-star.et) ; RAERR -- error in position at epoch ET. ; This is usually going to be *larger* than the error star.raerr, ; since the latter is taken at ETPM where (by definition -- Note (8)) ; the positional error is the smallest. ; Since cos(dec) applies to all three factors here, it divides out. star.raerr = sqrt((star.raerr_etpm)^2 + $ ((star.etpm[0]-star.et)*star.radoterr)^2 ) star.decerr = sqrt( (star.decerr_etpm)^2 + $ ((star.etpm[1]-star.et)*star.decdoterr)^2 ) star.mag = [ucac2.u2Rmag/100d, ucac2.m2_j/1000d, $ ucac2.m2_h/1000d, ucac2.m2_ks/1000d] star.magcat = ['ucac2', '2MASS', $ '2MASS', '2MASS'] star.magname = ['U2R', 'J', $ 'H', 'K_s'] star.magerr = [-999d, -999d, $ -999d, -999d] star.SpTcat = ['none'] star.SpT = [''] star.notecat = 'ucac2' star.note = '' star.ucac2 = ucac2 parse_end: ; Store the structure in an array stars[i] = star end ; Based on whether a scalar or an array was passed in, return the same. ; (In reality, it appears to always return a one-element array of ; structures, but this makes no difference to the user.) if is_scalar(ids) then return, stars[0] if is_array(ids) then return, stars return, stars end ;;;;;;;;;; pro other ;;;;;;;;;; ; ** Code below is for testing purposes and not for user use *** a=oc_getstar_ucac2(['01.00', '01.01', '01.02', '01.03', '201.075154', '201.075154', '201.075156', '201.075189']) id=oc_convertid_ucac2(scat=['1.0', '1.1', '1.2', '2.0', '2.1', '2.2']) a=oc_getstar_ucac2(id) p,a[*].mag p,a[*].id p,a[*].ra *d2r p,a[*].dec*d2r spawn, 'scat -c ucac2 -r 2 -d -t -j -n 100 ' + st(a[0].ra*r2d) + ' ' + st(a[0].dec*r2d) spawn, 'scat -c ucac2 -r 2 -d -t -j -n 100 ' + st(a[1].ra*r2d) + ' ' + st(a[1].dec*r2d) spawn, 'scat -c ucac2 -r 2 -d -t -j -n 100 ' + st(a[2].ra*r2d) + ' ' + st(a[2].dec*r2d) spawn, 'scat -c ucac2 -r 2 -d -t -j -n 100 ' + st(a[3].ra*r2d) + ' ' + st(a[3].dec*r2d) end