Extended IDL Help

This page was created by the IDL library routine mk_html_help. For more information on this routine, refer to the IDL Online Help Navigator or type:

     ? mk_html_help

at the IDL command line prompt.

Last modified: Tue Jul 11 20:44:18 2006.

• ARRGEN
• FARRGEN
• FIXPIX
• HMSTOH
• HTOHMS
• LASTTOK
• LEXECUTE
• NXNYN
• SETPS
• STRUCT_ADDFIELD
• STRUCT_ASSIGNFIELD
• STRUCT_DELFIELD
• TIMEPARSE
• TIMESTR
• TRUECOLORCONV
• UNSETPS
• XPLOT3D

Routine Descriptions

 NAME:
  arrgen
 PURPOSE: (one line)
  generate an array of evenly spaced numbers
 DESCRIPTION:
  
 CATEGORY:
  Util
 CALLING SEQUENCE:
  arrgen, x0, x1, dx
 INPUTS:
  x0 = initial value
  x1 = final value
  dx = approximate difference between successive values
 OPTIONAL INPUT PARAMETERS:
  int = 1 if integer
  long = 1 if long
  float = 1 if float
  double = 1 if doble
  
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  2005 Mar 16 Leslie Young SwRI Moved to layoung/util

(See util/arrgen.pro)

 NAME:
  farrgen
 PURPOSE: (one line)
  generate an array of evenly spaced numbers
 DESCRIPTION:
  
 CATEGORY:
  Util
 CALLING SEQUENCE:
  farrgen, x0, x1, dx
 INPUTS:
  x0 = initial 
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  nx, length of 1st dimension
  ny, length of 2nd dimension
  n   length of 3rd dimension (or 1 if d is 2d)
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  2005 Mar 16 Leslie Young SwRI Moved to layoung/util

(See util/farrgen.pro)

 given a image or stack of images and a bad pixel
 mask, will fill in bad pixels by finding the NPIX nearest
 good pixels, toss the highest and lowest ones of the bunch,
 and then arithmatically average. 

 bad pixel list is processed in order array is stored in
 memory, i.e. row by row, and is defined by:
	 0 = bad pixel
    not 0 = good pixel

 NPIX = # of adjacent pixels used for correction (default = 8)
 /weight: weight adjacent pixels by inverse of their distances
	   in averaging process

 checks to see if some pixels are equidistant; if so,
 use all of them, even if the total # of pixels then exceeds NPIX

 WARNINGS:
  - will work for entire bad columns/rows, but 
    may not be the most sensible thing to use
  - do not pass it the same array for input & output as this
    might corrupt the correction algorithm

 7/3/95 MCL

 added /noise: replace bad pixels with random noise with
 user defined sigma and dc level
 9/24/95 MCL

 badpix can now be a 2d or 3d array
 4/18/96 MCL

(See util/fixpix.pro)

 NAME:
    hmstoh
 PURPOSE: (one line)
    Convert from hours, minutes, and seconds of time to decimal hours
 DESCRIPTION:

 CATEGORY:
    Astronomy
 CALLING SEQUENCE:
    hmstorad, hour, min, sec,decimalhours
 INPUTS:
    hour : Hour.    0   <= hour < 24.
    min  : Minute.  0   <= min  < 60.
    sec  : Second.  0.0 <= sec  < 60.0.
    If more than one of these are vectors, they must be the same length.
    A mixture of scalar and vector input parameters is equivalent to all three
 inputs being vectors: The scalar inputs are treated as replicated vectors.
 OPTIONAL INPUT PARAMETERS:

 KEYWORD PARAMETERS:

 OUTPUTS:
    decimalhours  : Converted time in hours
 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
    2005 July 14 Leslie Young, 
      modified from hmstorad, M. Buie, Lowell Observatory

(See util/hmstoh.pro)

 NAME:
    htohms
 PURPOSE: (one line)
    Convert from decimal hours to hours, minutes, and seconds
 DESCRIPTION:

 CATEGORY:
    Astronomy
 CALLING SEQUENCE:
    htohms, h, hh, mm, ss
 INPUTS:
    h : time expressed in decimal hours.  May be a vector, in which case
              the outputs will be vectors.
 OPTIONAL INPUT PARAMETERS:

 KEYWORD PARAMETERS:

 OUTPUTS:
    hh : Hours
    mm : Minutes
    ss : Seconds
 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:
    The angle is reduced to its principal value then converted to hours.
    The decimal number of hours is broken up into the three pieces.  There are
  no invalid input quantities.
    Calls external function prival.pro.
 MODIFICATION HISTORY:
    2005 07 14 Leslie Young, SwRi
    based on radtohms, M Bie, Lowell Observatory

(See util/htohms.pro)

 NAME: 
  lasttok
 PURPOSE: 
  return the last token in a string
 DESCRIPTION:
 CATEGORY:
  util
 CALLING SEQUENCE:
  token = lasttok(str, toksep)
 INPUTS:
  fn: the filename
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
 OUTPUTS:
  exists (boolean): true if file exists
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
  call findfile
 MODIFICATION HISTORY:
  2002/05/30 - Initial  version written, Leslie Young SwRI

(See util/lasttok.pro)

 NAME:
  lexecute
 PURPOSE: (one line)
  execute a potentially long string
 DESCRIPTION:
  execute a string that is too long for the intrinsic execute
 CATEGORY:
  util
 CALLING SEQUENCE:
  lexecute, str, newsav, oldsav=oldsav, 
 INPUTS:
  str - the (potentially long) string or array of strings to execute
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  oldsav - a save file, if lexecute needs to get passed inputs
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  newsav - a save file, if lexecute needs to pass outputs
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  writes the file /
 RESTRICTIONS:
  If you must use the following characters within strings,
  make sure the strlen of str is < 160:
  &,()[]+-*/^ 

  The method of passing by reference doesn't seem to work.
 
 PROCEDURE:
 USAGE
  There are several ways to use this function
  
  If no variables have to be passed, then simply call
  lexecute,str

  If just a few variables have to be passed
  (eg str uses in1 and in2, assigns out1 and out2), then use keywords
  lexecute,str,in1=in1,in2=in2, out1=out1, out2=out2

  If many variable have to be passed, 
  or you don't know ahead of time what variables are used in str,
  then use save files
  oldsav=tmpfile('','sav') ; get a temporary sav filename
  save,/all,fil=oldsav     ; save variables
  lexecute,str,newsav,lexecute_oldsav=oldsav ; run, saving calcs in newsav
  restore,newsav           ; restore newsav
  file_delete,newsav       ; cleanup
 MODIFICATION HISTORY:
  2005 Dec 30 Leslie Young, SwRI
  2006 Jan  2 LAY, restored value of !quiet before executing proc

(See util/lexecute.pro)

 NAME:
  nxnyn
 PURPOSE: (one line)
  Return dimentions of a cube
 DESCRIPTION:
  
 CATEGORY:
  Util
 CALLING SEQUENCE:
  nxnyn, d, nx, ny, n
 INPUTS:
  d - a 3-d array of size [nx, ny, n]
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  nx, length of 1st dimension
  ny, length of 2nd dimension
  n   length of 3rd dimension (or 1 if d is 2d)
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  2005 Mar 16 Leslie Young SwRI Moved to layoung/util

(See util/nxnyn.pro)

 NAME:
  setps
 PURPOSE: (one line)
  Prepare to make a postscript plot
 DESCRIPTION:
  
 CATEGORY:
  Util
 CALLING SEQUENCE:
  setps, fn, LANDSCAPE = landscape
 INPUTS:
  filename
 OPTIONAL INPUT PARAMETERS:
  landscape - set for landscape
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  none
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  sets the plotting to a PS file called filename
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  2005 Oct 17 Leslie Young SwRI Moved to layoung/util

(See util/setps.pro)

 NAME:
  struct_addfield
 PURPOSE: (one line)
  add fields to an existing structure
 DESCRIPTION:
  add fields to an existing structure
 CATEGORY:
  util
 CALLING SEQUENCE:
  new = struct_addfield(old, tag, val, new_structname = new_structname)
 INPUTS:
  old - existing structure
  tag - name of field
  val - value for field
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  new_structname - if the structure is to be named (not anonymous),
                   the name of the new structure
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  new - new structure with field added
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  none
 RESTRICTIONS:
 PROCEDURE:
  Constructs a call to create_struct
  Calls lexecute to execute the long string
 USAGE
 MODIFICATION HISTORY:
  2005 Dec 31 Leslie Young

(See util/struct_addfield.pro)

 NAME:
  struct_assignfield
 PURPOSE: (one line)
  assign a field to a value in an existing structure
 DESCRIPTION:
  assign a field to a value in an existing structure, changing type
  to type of passed variable.  This allows us to 
 CATEGORY:
  util
 CALLING SEQUENCE:
  new = struct_assignfield(old, tag, new_structname = new_structname)
 INPUTS:
  old - existing structure
  tag - name of field to delete (string)
  val - value for tag
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  new_structname - if the structure is to be named (not anonymous),
                   the name
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  new - new structure with field added
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  none
 RESTRICTIONS:
 PROCEDURE:
  calls struct_delfield and struct_addfield
 USAGE
 MODIFICATION HISTORY:
  2005 Dec 31 Leslie Young

(See util/struct_assignfield.pro)

 NAME:
  struct_delfield
 PURPOSE: (one line)
  delete fields from an existing structure
 DESCRIPTION:
  delete fields from an existing structure
 CATEGORY:
  util
 CALLING SEQUENCE:
  new = struct_delfield(old, tag, new_structname = new_structname)
 INPUTS:
  old - existing structure
  tag - field to be deleted
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  new_structname - if the structure is to be named (not anonymous),
                   the name
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  new - new structure with field added
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  none
 RESTRICTIONS:
 PROCEDURE:
  Constructs a call to create_struct
  Calls lexecute to execute the long string
 USAGE
 MODIFICATION HISTORY:
  2005 Dec 31 Leslie Young

(See util/struct_delfield.pro)

 NAME:
  timeparse
 PURPOSE:
  Convert time string (hh:mm:ss.ss) to seconds
 DESCRIPTION:

 CATEGORY:
  Astronomy
 CALLING SEQUENCE:
  sec=timeparse(str)
 INPUTS:
  str - String (or array) to parse as a time
 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:

 OUTPUTS:
  return value is scalar or vector value of time in seconds
 KEYWORD OUTPUT PARAMETERS:

 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:

 MODIFICATION HISTORY:
  2005/07/14, Written by Leslie Young, SwRI, based on
      Marc Buie's haparse and raparse.

(See util/timeparse.pro)

 NAME:
    timestr
 PURPOSE: (one line)
    Convert time in hours to hours, minutes, and seconds (ASCII string).
 DESCRIPTION:

 CATEGORY:
    Astronomy
 CALLING SEQUENCE:
    timestr, hours, places, str, carry
 INPUTS:
    hours    : Time, in hours, to be converted to a string.
             May a vector, in which case the outputs will be vectors.
    places : Resolution of output string (integer).
             = -8     Decimal hours                     HH.hhhhh
             = -7     nearest hour.                     HH
             = -6     nearest 30 minutes.               HH:(00,30)
             = -5     nearest 15 minutes.               HH:(00,15,30,45)
             = -4     nearest 10 minutes.               HH:M0
             = -3     nearest 5 minutes.                HH:M(0,5)
             = -2     nearest minute.                   HH:MM
             = -1     nearest ten seconds.              HH:MM:S0
             =  0     nearest second.                   HH:MM:SS
             =  1     nearest tenth of a second.        HH:MM:SS.s
             =  2     nearest hundredth of a second.    HH:MM:SS.ss
             =  3     nearest thousandth of a second.   HH:MM:SS.sss
             =  4     nearest thousandth of a second.   HH:MM:SS.ssss
 OPTIONAL INPUT PARAMETERS:

 KEYWORD PARAMETERS:
    SEPCHAR - Separator character for the fields in the position.
                 Default=':'.  Warning, if you do not use ':' then the
                 string may not be parsable by timeparse.
 OUTPUTS:
    str   - Output string for the converted right ascension.
    carry - Flag that indicates hour rolled over after rounding.
 COMMON BLOCKS:

 SIDE EFFECTS:

 RESTRICTIONS:

 PROCEDURE:
    Time reduced to the range [0,24) then converted to a string.
    There are no imbedded blanks.
    Calls external routine htohms.
 MODIFICATION HISTORY:
  2005 07 14 Leslie Young SwRI
  Based on 2003/05/09 version of rastr,
   by Marc Buie, Lowell Observatory

(See util/timestr.pro)

 NAME:
  truecolorconv
 PURPOSE: (one line)
  Convert between 'BBGGRR'XL and [blue,green,red] formulations for truecolor
 DESCRIPTION:
  Convert between 'BBGGRR'XL and [blue,green,red] formulations for truecolor
 CATEGORY:
  util
 CALLING SEQUENCE:
  a = truecolorconv(b)
 INPUTS:
  b - either a 2-D array of longs, where the least significant
      byte is the red shade (0 for black, FF for reddest),
      the next byte is green, and the next byte is blue, OR
      a 3-D array of bytes, where b[0,*,*] is blue, b[1,*,*] is green
      and b[2,*,*] is red
 OPTIONAL INPUT PARAMETERS:
  none
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  alternate form (3-D bytes if input is 2-D long, or
  2-D long if input is 3-D bytes)
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  Written 2006 Jan 13, by Leslie Young, SwRI

(See util/truecolorconv.pro)

 NAME:
  unsetps
 PURPOSE: (one line)
  Prepare to stop making a postscript plot
 DESCRIPTION:
  
 CATEGORY:
  Util
 CALLING SEQUENCE:
  unsetps, fn
 INPUTS:
  none
 OPTIONAL INPUT PARAMETERS:
  filename - if set, look at file just made
 KEYWORD INPUT PARAMETERS:
  none
 KEYWORD OUTPUT PARAMETERS:
  none
 OUTPUTS:
  none
 COMMON BLOCKS:
  None
 SIDE EFFECTS:
  sets the plotting back to X or mac
 RESTRICTIONS:
  None
 PROCEDURE:
 MODIFICATION HISTORY:
  2005 Oct 17 Leslie Young SwRI Moved to layoung/util

(See util/unsetps.pro)

 NAME:
       xplot3d

 PURPOSE:
       Provide an interactive version of IDL's plot_3dbox
       command.

 CATEGORY:
       Widgets, Object Graphics.  Plotting.

 CALLING SEQUENCE:
       xplot3d, x, y, z

 REQUIRED INPUTS:
       None.  Fake data will be used if no data is supplied in call.

 OPTIONAL INPUTS

       x: A vector of X data values.

       y: A vector of Y data values.

       z: A vector of Z data values.

 OPTIONAL KEYWORD PARAMETERS:

       GROUP: Widget group_leader.  When the group leader
       is destroyed, this program will be destroyed.
       MODAL: If set, block other IDL widgets from receiving events.
       BLOCK: If set, block IDL command line.
       TITLE: String.  A title for the plot.
       [XYZ]TITLE: String.  Title for x, y or z axis.
       NAME: A string.  This is a name for the data curve being plotted.
           The name is displayed on xplot3d's toolbar if/when
           the curve is selected with the mouse.  (To select
           the curve with the mouse, xplot3d must
           be in select mode.  You can put xplot3d in select mode
           by clicking on the rightmost button in xplot3d's
           toolbar.)
       [XYZ]RANGE: Two element array specifying axis range.  [min, max]
       OVERPLOT: Draw the curve in the most recently created view.
           Title keywords, range keywords and the modal keyword are
           ignored if we are overplotting.

       LINESTYLE: Same as IDLgrPolyline::init keyword.
       THICK: Same as IDLgrPolyline::init keyword.
       COLOR: [r, g, b] triplet.  Color of curve.  Same as IDLgrPolyline.
       SYMBOL: Same as IDLgrPolyline::init keyword.
       TEST: If set, do not require input arguments.  Plot an example
           sinusoidal curve instead.

 EXAMPLE 1:
       IDL> x = indgen(20)
       IDL> y = sin(x/3.)
       IDL> z = x
       IDL> xplot3d, x, y, z, thick=2, name='interesting curve'

 EXAMPLE 2:
       IDL> x = indgen(20)
       IDL> y = sin(x/3.)
       IDL> z = x
       IDL> oOrb = obj_new('orb', color=[0, 0, 255])
       IDL> oOrb->Scale, .75, .1, .5
       IDL> oSymbol = obj_new('IDLgrSymbol', oOrb)
       IDL> xplot3d, x, y, z, thick=2, symbol=oSymbol

 KNOWN PROBLEMS:
       Symbols (specified via the SYMBOL keyword) are not drawn in
           a suitably muted color when projected (via the
           "2D Projection..." menu functionality).
       Heap variables may not be cleaned up properly if an error
           occurs in procedure xplot3d.

(See util/xplot3dLAY.pro)