Debian Codegraph @

program.documentation.html

raw
1 <!-- This file was generated by mk_html_help.pro -->
2 <html>
3
4 <head>
5 <TITLE>IDL Example Programs</TITLE>
6 </head>
7
8 <body>
9 <H1>IDL Example Programs</H1>
10 <P>
11 This page was created by the IDL library routine
12 <CODE>mk_html_help</CODE>. For more information on
13 this routine, refer to the IDL Online Help Navigator
14 or type: <P>
15 <PRE> ? mk_html_help</PRE><P>
16 at the IDL command line prompt.<P>
17 <STRONG>Last modified: </STRONG>Mon Jan 27 18:31:36 2014.<P>
18
19 <HR>
20
21 <A NAME="ROUTINELIST">
22 <H1>List of Routines</H1></A>
23 <UL>
24 <LI><A HREF="#ADJUSTPOSITION">ADJUSTPOSITION</A>
25 <LI><A HREF="#ANSI_VALUE">ANSI_VALUE</A>
26 <LI><A HREF="#ARCSAMPLE">ARCSAMPLE</A>
27 <LI><A HREF="#ASINHSCL">ASINHSCL</A>
28 <LI><A HREF="#ASPECT">ASPECT</A>
29 <LI><A HREF="#BINARY">BINARY</A>
30 <LI><A HREF="#BITGET">BITGET</A>
31 <LI><A HREF="#BLOB_ANALYZER__DEFINE">BLOB_ANALYZER__DEFINE</A>
32 <LI><A HREF="#CAPFIRSTLETTER">CAPFIRSTLETTER</A>
33 <LI><A HREF="#CHECKERBOARD">CHECKERBOARD</A>
34 <LI><A HREF="#CINDEX">CINDEX</A>
35 <LI><A HREF="#CLIPBOARD">CLIPBOARD</A>
36 <LI><A HREF="#CLIPSCL">CLIPSCL</A>
37 <LI><A HREF="#COLORBUTTONBITMAP">COLORBUTTONBITMAP</A>
38 <LI><A HREF="#COLORSAREIDENTICAL">COLORSAREIDENTICAL</A>
39 <LI><A HREF="#CONTRASTZOOM">CONTRASTZOOM</A>
40 <LI><A HREF="#CONVERT_TO_TYPE">CONVERT_TO_TYPE</A>
41 <LI><A HREF="#CW_DRAWCOLOR">CW_DRAWCOLOR</A>
42 <LI><A HREF="#DIRPATH">DIRPATH</A>
43 <LI><A HREF="#ERRORLOGGER__DEFINE">ERRORLOGGER__DEFINE</A>
44 <LI><A HREF="#FIND_BOUNDARY">FIND_BOUNDARY</A>
45 <LI><A HREF="#FIT_ELLIPSE">FIT_ELLIPSE</A>
46 <LI><A HREF="#FIXED_MAP_GRID">FIXED_MAP_GRID</A>
47 <LI><A HREF="#FLOATS_EQUAL">FLOATS_EQUAL</A>
48 <LI><A HREF="#FPUFIX">FPUFIX</A>
49 <LI><A HREF="#FSCCLEANUP7">FSCCLEANUP7</A>
50 <LI><A HREF="#FSCCLEANUP8">FSCCLEANUP8</A>
51 <LI><A HREF="#FSC_COLORBAR__DEFINE">FSC_COLORBAR__DEFINE</A>
52 <LI><A HREF="#FSC_COLORSELECT">FSC_COLORSELECT</A>
53 <LI><A HREF="#FSC_DROPLIST">FSC_DROPLIST</A>
54 <LI><A HREF="#FSC_FIELD">FSC_FIELD</A>
55 <LI><A HREF="#FSC_FILESELECT">FSC_FILESELECT</A>
56 <LI><A HREF="#FSC_INPUTFIELD">FSC_INPUTFIELD</A>
57 <LI><A HREF="#FSC_PLOTWINDOW">FSC_PLOTWINDOW</A>
58 <LI><A HREF="#FSC_PSCONFIG__DEFINE">FSC_PSCONFIG__DEFINE</A>
59 <LI><A HREF="#GAUSSSCL">GAUSSSCL</A>
60 <LI><A HREF="#GETIMAGE">GETIMAGE</A>
61 <LI><A HREF="#GETPRIMARYSCREENSIZE">GETPRIMARYSCREENSIZE</A>
62 <LI><A HREF="#GET_OBJECT_ID">GET_OBJECT_ID</A>
63 <LI><A HREF="#CGGMASCL">CGGMASCL</A>
64 <LI><A HREF="#HCOLORBAR">HCOLORBAR</A>
65 <LI><A HREF="#HELP_VAR">HELP_VAR</A>
66 <LI><A HREF="#HISTOMATCH">HISTOMATCH</A>
67 <LI><A HREF="#IMAGESELECT">IMAGESELECT</A>
68 <LI><A HREF="#IMAGE_BLEND">IMAGE_BLEND</A>
69 <LI><A HREF="#IMAGE_DIMENSIONS">IMAGE_DIMENSIONS</A>
70 <LI><A HREF="#INSIDE">INSIDE</A>
71 <LI><A HREF="#JD2TIME">JD2TIME</A>
72 <LI><A HREF="#LEFTJUSTIFY">LEFTJUSTIFY</A>
73 <LI><A HREF="#LINKEDLIST">LINKEDLIST</A>
74 <LI><A HREF="#LIST_SELECTOR">LIST_SELECTOR</A>
75 <LI><A HREF="#LOGSCL">LOGSCL</A>
76 <LI><A HREF="#MAXMIN">MAXMIN</A>
77 <LI><A HREF="#MAXWINDOWSIZE">MAXWINDOWSIZE</A>
78 <LI><A HREF="#NAME_SELECTOR">NAME_SELECTOR</A>
79 <LI><A HREF="#NCDF_ATTRIBUTE">NCDF_ATTRIBUTE</A>
80 <LI><A HREF="#NCDF_BROWSER">NCDF_BROWSER</A>
81 <LI><A HREF="#NCDF_CASTDATATYPE">NCDF_CASTDATATYPE</A>
82 <LI><A HREF="#NCDF_CONTAINER">NCDF_CONTAINER</A>
83 <LI><A HREF="#NCDF_DATA__DEFINE">NCDF_DATA__DEFINE</A>
84 <LI><A HREF="#NCDF_DIMENSION">NCDF_DIMENSION</A>
85 <LI><A HREF="#NCDF_FILE">NCDF_FILE</A>
86 <LI><A HREF="#NCDF_FILE_EXAMPLES">NCDF_FILE_EXAMPLES</A>
87 <LI><A HREF="#NCDF_ISVALIDFILE">NCDF_ISVALIDFILE</A>
88 <LI><A HREF="#NCDF_VARIABLE">NCDF_VARIABLE</A>
89 <LI><A HREF="#PICKCOLOR">PICKCOLOR</A>
90 <LI><A HREF="#PRECIPMAP">PRECIPMAP</A>
91 <LI><A HREF="#PRINTWINDOW">PRINTWINDOW</A>
92 <LI><A HREF="#PSWINDOW">PSWINDOW</A>
93 <LI><A HREF="#PS_BACKGROUND">PS_BACKGROUND</A>
94 <LI><A HREF="#RANDOMNUMBERGENERATOR">RANDOMNUMBERGENERATOR</A>
95 <LI><A HREF="#RANGEOF">RANGEOF</A>
96 <LI><A HREF="#REPMAT">REPMAT</A>
97 <LI><A HREF="#RESOLVE_OBJECT">RESOLVE_OBJECT</A>
98 <LI><A HREF="#REVERSE_AXES">REVERSE_AXES</A>
99 <LI><A HREF="#SAVETOMAIN">SAVETOMAIN</A>
100 <LI><A HREF="#SCALEMODIS">SCALEMODIS</A>
101 <LI><A HREF="#SCROLLWINDOW">SCROLLWINDOW</A>
102 <LI><A HREF="#SDEVSCL">SDEVSCL</A>
103 <LI><A HREF="#SELECT_OBJECTS">SELECT_OBJECTS</A>
104 <LI><A HREF="#SETDEFAULTVALUE">SETDEFAULTVALUE</A>
105 <LI><A HREF="#SHARPEN">SHARPEN</A>
106 <LI><A HREF="#SORT_ND">SORT_ND</A>
107 <LI><A HREF="#STATIONPLOT">STATIONPLOT</A>
108 <LI><A HREF="#STR_SIZE">STR_SIZE</A>
109 <LI><A HREF="#TEXTBOX">TEXTBOX</A>
110 <LI><A HREF="#TEXTLINEFORMAT">TEXTLINEFORMAT</A>
111 <LI><A HREF="#TEXTURE_SURFACE">TEXTURE_SURFACE</A>
112 <LI><A HREF="#TRANSFORM_VOLUME">TRANSFORM_VOLUME</A>
113 <LI><A HREF="#UNDEFINE">UNDEFINE</A>
114 <LI><A HREF="#VCOLORBAR">VCOLORBAR</A>
115 <LI><A HREF="#WINDBARB">WINDBARB</A>
116 <LI><A HREF="#WINDOWAVAILABLE">WINDOWAVAILABLE</A>
117 <LI><A HREF="#WINDOWIMAGE">WINDOWIMAGE</A>
118 </UL><P>
119
120 <HR>
121
122 <H1>Routine Descriptions</H1>
123 <A NAME="ADJUSTPOSITION">
124 <H2>ADJUSTPOSITION</H2></A>
125 <A HREF="#ANSI_VALUE">[Next Routine]</A>
126 <A HREF="#ROUTINELIST">[List of Routines]</A>
127 <PRE>
128 NAME:
129 AdjustPosition
130
131 PURPOSE:
132
133 This is a program for interactively adjusting the plot position
134 coordinates. The result of the function is a four-element floating
135 point array of normalized coordinates, suitable for passing to the
136 POSITION keyword of most IDL graphics commands.
137
138 AUTHOR:
139
140 FANNING SOFTWARE CONSULTING
141 David Fanning, Ph.D.
142 1645 Sheely Drive
143 Fort Collins, CO 80526 USA
144 Phone: 970-221-0438
145 E-mail: [email protected]
146 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
147
148 CATEGORY:
149
150 Graphics
151
152 CALLING SEQUENCE:
153
154 position = AdjustPosition(startingPosition)
155
156 OPTIONAL INPUTS:
157
158 startingPosition - A four-element array of normalized coordinates
159 of the form [x0, y0, x1, y1].
160
161 OUTPUTS:
162
163 position - The adjusted plot position. A four-element array of normalized coordinates.
164
165 INPUT KEYWORDS:
166
167 GROUP_LEADER - The group leader of this program. This keyword
168 is required to ensure modal operation when calling from
169 another widget program.
170
171 TITLE - The title of the window. "Adjust Plot Position in Window..." by default.
172
173 XOFFSET - The X offset of the program on the display. Calculated from the
174 upper left-hand corner of the display.
175
176 YOFFSET - The Y offset of the program on the display. Calculated from the
177 upper left-hand corner of the display.
178
179 OUTPUT KEYWORDS:
180
181 CANCEL - Returns a 1 if the user selects the Cancel button. Returns 0 otherwise.
182 Note that if the use cancels, the "position" parameter is set to the value of
183 the "startingPosition" parameter.
184
185 DEPENDENCIES:
186
187 Reqires FSC_FIELD and FSC_PLOTWINDOW from the Coyote Library:
188
189 http://www.idlcoyote.com/programs/fsc_field.pro
190 http://www.idlcoyote.com/programs/fsc_plotwindow.pro
191
192 MODIFICATION HISTORY:
193
194 Written by David Fanning, March 2001.
195 </PRE><P>
196 <STRONG>(See adjustposition.pro)</STRONG><P>
197 <HR>
198
199 <A NAME="ANSI_VALUE">
200 <H2>ANSI_VALUE</H2></A>
201 <A HREF="#ADJUSTPOSITION">[Previous Routine]</A>
202 <A HREF="#ARCSAMPLE">[Next Routine]</A>
203 <A HREF="#ROUTINELIST">[List of Routines]</A>
204 <PRE>
205 :Description:
206 Provides a way to display non-printable characters in widget elements.
207
208 :Categories:
209 Widgets
210
211 :Params:
212 str_in: in, required, type=string
213 The input string that you wish to render on a widget element.
214
215 :Keywords:
216 example: in, optional, type=boolean, default=0
217 Set this keyword to see an example of non-printable characters
218 rendered in a Dialog_Pickfile widget.
219
220 :Examples:
221 Call the built-in example::
222 IDL> void = ANSI_Value(/EXAMPLE)
223
224 :Author:
225 Bernat Puigdomenech
226
227 :History:
228 Change History::
229 Written, 2 September 2011. Bernat Puigdomenech.
230
231 :Copyright:
232 Copyright (c) 2011, Bernat Puigdomenech.
233 </PRE><P>
234 <STRONG>(See ansi_value.pro)</STRONG><P>
235 <HR>
236
237 <A NAME="ARCSAMPLE">
238 <H2>ARCSAMPLE</H2></A>
239 <A HREF="#ANSI_VALUE">[Previous Routine]</A>
240 <A HREF="#ASINHSCL">[Next Routine]</A>
241 <A HREF="#ROUTINELIST">[List of Routines]</A>
242 <PRE>
243 NAME:
244 ARCSAMPLE
245
246 PURPOSE:
247
248 Given X and Y points that describe a closed curve in 2D space,
249 this function returns an output curve that is sampled a specified
250 number of times at approximately equal arc distances.
251
252 AUTHOR:
253
254 FANNING SOFTWARE CONSULTING
255 David Fanning, Ph.D.
256 1645 Sheely Drive
257 Fort Collins, CO 80526 USA
258 Phone: 970-221-0438
259 E-mail: [email protected]
260 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
261
262 CATEGORY:
263
264 Utilities
265
266 CALLING SEQUENCE:
267
268 ArcSample, x_in, y_in, x_out, y_out
269
270 INPUT_PARAMETERS:
271
272 x_in: The input X vector of points.
273 y_in: The input Y vector of points.
274
275 OUTPUT_PARAMETERS:
276
277 x_out: The output X vector of points.
278 y_out: The output Y vector of points.
279
280 KEYWORDS:
281
282 POINTS: The number of points in the output vectors. Default: 50.
283
284 PHASE: A scalar between 0.0 and 1.0, for fine control of where interpolates
285 are sampled. Default: 0.0.
286
287 MODIFICATION HISTORY:
288
289 Written by David W. Fanning, 1 December 2003, based on code supplied
290 to me by Craig Markwardt.
291 </PRE><P>
292 <STRONG>(See arcsample.pro)</STRONG><P>
293 <HR>
294
295 <A NAME="ASINHSCL">
296 <H2>ASINHSCL</H2></A>
297 <A HREF="#ARCSAMPLE">[Previous Routine]</A>
298 <A HREF="#ASPECT">[Next Routine]</A>
299 <A HREF="#ROUTINELIST">[List of Routines]</A>
300 <PRE>
301 NAME:
302 ASINHSCL
303
304 PURPOSE:
305
306 This is a utility routine to perform an inverse hyperbolic sine
307 function intensity transformation on an image. I think of this
308 as a sort of "tuned" gamma or power-law function. The algorithm,
309 and notion of "asinh magnitudes", comes from a paper by Lupton,
310 et. al, in The Astronomical Journal, 118:1406-1410, 1999 September.
311 I've relied on the implementation of Erin Sheldon, found here:
312
313 http://cheops1.uchicago.edu/idlhelp/sdssidl/plotting/tvasinh.html
314
315 I'm also grateful of discussions with Marshall Perrin on the IDL
316 newsgroup with respect to the meaning of the "softening parameter", beta,
317 and for finding (and fixing!) small problems with the code.
318
319 Essentially this transformation allow linear scaling of noise values,
320 and logarithmic scaling of signal values, since there is a small
321 linear portion of the curve and a much large logarithmic portion of
322 the curve. (See the EXAMPLE section for some tips on how to view this
323 transformation curve.)
324
325 AUTHOR:
326
327 FANNING SOFTWARE CONSULTING
328 David Fanning, Ph.D.
329 1645 Sheely Drive
330 Fort Collins, CO 80526 USA
331 Phone: 970-221-0438
332 E-mail: [email protected]
333 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
334
335 CATEGORY:
336
337 Utilities
338
339 CALLING SEQUENCE:
340
341 outputImage = ASINHSCL(image)
342
343 ARGUMENTS:
344
345 image: The image or signal to be scaled. Written for 2D images, but arrays
346 of any size are treated alike.
347
348 KEYWORDS:
349
350 BETA: This keyword corresponds to the "softening parameter" in the Lupon et. al paper.
351 This factor determines the input level at which linear behavior sets in. Beta
352 should be set approximately equal to the amount of "noise" in the input signal.
353 IF BETA=0 there is a very small linear portion of the curve; if BETA=200 the
354 curve is essentially all linear. The default value of BETA is set to 3, which
355 is appropriate for a small amount of noise in your signal. The value is always
356 positive.
357
358 NEGATIVE: If set, the "negative" of the result is returned.
359
360 MAX: Any value in the input image greater than this value is
361 set to this value before scaling.
362
363 MIN: Any value in the input image less than this value is
364 set to this value before scaling.
365
366 OMAX: The output image is scaled between OMIN and OMAX. The
367 default value is 255.
368
369 OMIN: The output image is scaled between OMIN and OMAX. The
370 default value is 0.
371 RETURN VALUE:
372
373 outputImage: The output, scaled into the range OMIN to OMAX. A byte array.
374
375 COMMON BLOCKS:
376 None.
377
378 EXAMPLES:
379
380 Plot, ASinhScl(Indgen(256), Beta=0.0), LineStyle=0
381 OPlot, ASinhScl(Indgen(256), Beta=0.1), LineStyle=1
382 OPlot, ASinhScl(Indgen(256), Beta=1.0), LineStyle=2
383 OPlot, ASinhScl(Indgen(256), Beta=10.), LineStyle=3
384 OPlot, ASinhScl(Indgen(256), Beta=100), LineStyle=4
385
386 RESTRICTIONS:
387
388 Requires cgScaleVector from the Coyote Library:
389
390 http://www.idlcoyote.com/programs/cgScaleVector.pro
391
392 Incorporates ASINH from the NASA Astronomy Library and renamed ASINHSCL_ASINH.
393
394 http://idlastro.gsfc.nasa.gov/homepage.html
395
396 MODIFICATION HISTORY:
397
398 Written by: David W. Fanning, 24 February 2006.
399 Removed ALPHA keyword and redefined the BETA keyword to correspond
400 to the "softening parameter" of Lupton et. al., following the
401 suggestions of Marshall Perrin. 25 April 2006. DWF.
402 </PRE><P>
403 <STRONG>(See asinhscl.pro)</STRONG><P>
404 <HR>
405
406 <A NAME="ASPECT">
407 <H2>ASPECT</H2></A>
408 <A HREF="#ASINHSCL">[Previous Routine]</A>
409 <A HREF="#BINARY">[Next Routine]</A>
410 <A HREF="#ROUTINELIST">[List of Routines]</A>
411 <PRE>
412 NAME:
413 ASPECT
414
415 PURPOSE:
416
417 This function calculates and returns the normalized position
418 coordinates necessary to put a plot with a specified aspect ratio
419 into the currently active graphics window. It works on the display
420 output window as well as in a PostScript output window.
421
422 AUTHOR:
423
424 FANNING SOFTWARE CONSULTING
425 David Fanning, Ph.D.
426 1645 Sheely Drive
427 Fort Collins, CO 80526 USA
428 Phone: 970-221-0438
429 E-mail: [email protected]
430 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
431
432 CATEGORY:
433
434 Graphics
435
436 CALLING SEQUENCE:
437
438 position = ASPECT(aspectRatio)
439
440 INPUTS:
441
442 aspectRatio: A floating point value that is the desired aspect
443 ratio (ratio of heigth to width) of the plot in the current
444 graphics output window. If this parameter is missing, an aspect
445 ratio of 1.0 (a square plot) is assumed.
446
447 KEYWORD PARAMETERS:
448
449 MARGIN: The margin around the edges of the plot. The value must be
450 a floating point value between 0.0 and 0.5. It is expressed in
451 normalized coordinate units. The default margin is 0.15.
452
453 WINDOWASPECT: The aspect ratio of the target window. If not provided,
454 the value is obtained from the current graphics window.
455
456 OUTPUTS:
457
458 position: A four-element floating array of normalized coordinates.
459 The order of the elements is [x0, y0, x1, y1], similar to the
460 !P.POSITION system variable or the POSITION keyword on any IDL
461 graphic command.
462
463 EXAMPLE:
464
465 To create a plot with an aspect ratio of 1:2 and a margin of
466 0.10 around the edge of the output window, do this:
467
468 plotPosition = ASPECT(0.5, Margin=0.10)
469 PLOT, Findgen(11), POSITION=plotPosition
470
471 Notice this can be done in a single IDL command, like this:
472
473 PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10)
474
475 MODIFICATION HISTORY:
476
477 Written by: David Fanning, November 1996.
478 Added better error checking, 18 Feb 1997, DWF.
479 Added WindowAspect keyword. 10 Feb 2000. DWF
480 Added double precision tolerance for aspectRatio. 9 NOV 2001 BT
481 Officially retired in favor of cgAspect. 11 February 2013. DWF.
482 </PRE><P>
483 <STRONG>(See aspect.pro)</STRONG><P>
484 <HR>
485
486 <A NAME="BINARY">
487 <H2>BINARY</H2></A>
488 <A HREF="#ASPECT">[Previous Routine]</A>
489 <A HREF="#BITGET">[Next Routine]</A>
490 <A HREF="#ROUTINELIST">[List of Routines]</A>
491 <PRE>
492 NAME:
493 BINARY
494
495 PURPOSE:
496
497 This function is used to display a binary representation of byte,
498 integer, and long integer values.
499
500 AUTHOR:
501
502 FANNING SOFTWARE CONSULTING
503 David Fanning, Ph.D.
504 1645 Sheely Drive
505 Fort Collins, CO 80526 USA
506 Phone: 970-221-0438
507 E-mail: [email protected]
508 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
509
510 CATEGORY:
511
512 Utilities
513
514 CALLING SEQUENCE:
515
516 output = Binary(theNumber)
517
518 RETURN VALUE:
519
520 output: A string array of 0s and 1s to be printed (normally), in a
521 binary representation of the number. The number is represented with
522 the highest bits on the left and the lowest bits on the right,
523 when printed with the PRINT command.
524
525 ARGUMENTS:
526
527 theNumber: The number for which the user wants a binary representation.
528 It must be BYTE, INT, or LONG.
529
530 KEYWORDRS:
531
532 COLOR: If this keyword is set, the binary representation always
533 contains 24 bits of output.
534
535 SEPARATE: If this keyword is set, the output is separated with space
536 between each group of eight bits.
537
538 EXAMPLE:
539
540 IDL> Print, Binary(24B)
541 0 0 0 1 1 0 0 0
542 IDL> Print, Binary(24L)
543 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0
544 IDL> Print, Binary(24L, /COLOR)
545 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0
546 IDL> Print, Binary(24L, /COLOR, /SEPARATE)
547 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0
548
549 MODIFICATION HISTORY:
550
551 Written by: David W. Fanning, November 10, 2007.
552 Fixed a problem with error handling. 13 March 2008. DWF.
553 </PRE><P>
554 <STRONG>(See binary.pro)</STRONG><P>
555 <HR>
556
557 <A NAME="BITGET">
558 <H2>BITGET</H2></A>
559 <A HREF="#BINARY">[Previous Routine]</A>
560 <A HREF="#BLOB_ANALYZER__DEFINE">[Next Routine]</A>
561 <A HREF="#ROUTINELIST">[List of Routines]</A>
562 <PRE>
563 NAME:
564 BITGET
565
566 PURPOSE:
567
568 Returns the bit value (0 or 1) of a specified bit in a supplied number.
569
570 AUTHOR:
571
572 FANNING SOFTWARE CONSULTING
573 David Fanning, Ph.D.
574 1645 Sheely Drive
575 Fort Collins, CO 80526 USA
576 Phone: 970-221-0438
577 E-mail: [email protected]
578 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
579
580 CATEGORY:
581
582 Utilities
583
584 CALLING SEQUENCE:
585
586 bitValue = BitGet(number, bit)
587
588 INPUT_PARAMETERS:
589
590 number: The input number. Should be a scalar integer. If not, it is converted to
591 one by rounding.
592
593 bit: The number of the bit you are interested in. A value between 0 and 63.
594 If not supplied, all 64 bit values of the number are returned. May be
595 an array of bit numbers.
596
597 OUTPUT_PARAMETERS:
598
599 bitValue: The value, 0 or 1, of the specified bit in the number.
600
601 KEYWORDS:
602
603 SILENT: If set, suppresses informational messages regarding rounding operations.
604
605 MODIFICATION HISTORY:
606
607 Written by David W. Fanning, 14 June 2006.
608 </PRE><P>
609 <STRONG>(See bitget.pro)</STRONG><P>
610 <HR>
611
612 <A NAME="BLOB_ANALYZER__DEFINE">
613 <H2>BLOB_ANALYZER__DEFINE</H2></A>
614 <A HREF="#BITGET">[Previous Routine]</A>
615 <A HREF="#CAPFIRSTLETTER">[Next Routine]</A>
616 <A HREF="#ROUTINELIST">[List of Routines]</A>
617 <PRE>
618 NAME:
619 BLOB_ANALYZER__DEFINE
620
621 PURPOSE:
622
623 The purpose of this routine is to create a system for analyzing
624 regions of interest (ROIs) or (more commonly) "blobs" inside images.
625 In particular, given a suitable image (this will require judgement on
626 your part), the program will automatically select "blobs" or connected
627 regions in the image and make it possible for you to analyze these
628 blobs. An example program is provided to show you one way the program
629 can be used.
630
631 The code is a wrapper, essentially, for LABEL_REGION and HISTOGRAM, with
632 a couple of my other image processing routines (FIND_BOUNDARY and FIT_ELLIPSE)
633 used in a supporting role.
634
635 AUTHOR:
636
637 FANNING SOFTWARE CONSULTING
638 David Fanning, Ph.D.
639 1645 Sheely Drive
640 Fort Collins, CO 80526 USA
641 Phone: 970-221-0438
642 E-mail: [email protected]
643 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
644
645 CATEGORY:
646
647 Analysis, Image Processing
648
649 CALLING SEQUENCE:
650
651 analyzer = Obj_New("BLOB_ANALYZER", image)
652
653 INPUTS:
654
655 image: A two-dimensional image array. To make this program memory efficient,
656 a copy of the image is *not* stored in the object. You will be responsible
657 for image operations outside this program.
658
659 KEYWORDS:
660
661 ALL_NEIGHBORS: Set this keyword to look at all eight neighbors when searching
662 for connectivity. The default is to look for four neighbors on
663 each side of the starting pixel. Passed directly to LABEL_REGION.
664
665 MASK: A two-dimensional array, the same size as image, that identifies the
666 foreground and background pixels in the image. Applying the mask
667 should result in a bi-level image of 0s and 1s, where 1 identifies the
668 blobs you wish to analyze. If a mask is not provided, the mask is created
669 like this:
670
671 mask = image > 0
672
673 SCALE: A one- or two-dimensional given the pixel scaling parameters. By default [1.0, 1.0].
674 If passed a scalar, the scale parameter is applied to both the X and Y directions of
675 each pixel. Statistical output is reported with scaling unless the NOSCALE keyword
676 is set. Scaling also effects the data that is output from the various methods.
677
678 OBJECT METHODS:
679
680 The following methods are provided. Please see the documentation header for each method for
681 information on arguments and keywords that can be used with the method.
682
683 FitEllipse: This method fits an ellipse to the blob. It returns information about the fitted
684 ellipse, including the points that all the ellipse to be drawn.
685
686 GetIndices: This method returns the indices for a particular blob in the image.
687
688 GetStats: This method returns a structure containing statistics for a particular blob in the image.
689 The structure is defined as follows:
690
691 stats = {INDEX: indexNumber, $ ; The index number of this blob.
692 COUNT: N_Elements(indices), $ ; The number of indices in this blob.
693 PERIMETER_PTS: boundaryPts, $ ; A [2,n] array of points that describe the blob perimeter.
694 PIXEL_AREA: pixelArea, $ ; The area as calculated by pixels in the blob.
695 PERIMETER_AREA: perimeterArea, $ ; The area as calculated by the blob perimeter. (Smaller than pixel area.)
696 CENTER: centroid[0:1], $ ; The [x,y] array that identifies the centroid of the blob.
697 PERIMETER_LENGTH: perimeter_length, $ ; The perimenter length (scaled unless the NOSCALE keyword is set).
698 SCALE: scale, $ ; The [xscale, yscale] array used in scaling.
699 MINCOL: Min(xyindices[0,*]), $ ; The minimum column index in the blob.
700 MAXCOL: Max(xyindices[0,*]), $ ; The maximum column index in the blob.
701 MINROW: Min(xyindices[1,*]), $ ; The minimum row index in the blob.
702 MAXROW: Max(xyindices[1,*])} ; The maximum row index in the blob.
703
704 NumberOfBlobs: The number of blobs identified in the image.
705
706 ReportStats: This methods reports statistics on every identified blob in the image. The
707 report can be sent to the display (the default) or to a file. The format for
708 the report works for most images, but you may have to change the format or override
709 this method for your particular image. The reported statistics are basically the
710 output of the GetStats and FitEllipse methods.
711
712 Here is an example of statistical output from the example program below.
713
714 INDEX NUM_PIXELS CENTER_X CENTER_Y PIXEL_AREA PERIMETER_AREA PERIMETER_LENGTH MAJOR_AXIS MINOR_AXIS ANGLE
715 0 426 107.89 9.78 106.50 98.00 37.56 12.15 11.29 -8.05
716 1 580 151.97 10.22 145.00 134.25 49.21 17.49 11.77 -0.99
717 2 812 266.29 15.36 203.00 190.75 52.56 17.88 14.65 -107.48
718 3 1438 204.53 43.29 359.50 344.13 70.23 21.68 21.12 -76.47
719
720 RESTRICTIONS:
721
722 Requires programs from the Coyote Library. At the very least, those below are required.
723 It is *highly* recommended that you install the entire library. FIT_ELLIPSE has been
724 changed specifically for this release, so by sure you get a copy of that with this
725 source code.
726
727 The program currently works only with 2D bi-level images.
728
729 EXAMPLE:
730
731 To run an example program. Compile the file and type "example" at the IDL command line.
732
733 IDL> .compile blob_analyzer__define
734 IDL> example
735
736 MODIFICATION HISTORY:
737
738 Written by David W. Fanning, Fanning Software Consulting, 17 August 2008.
739 Ideas taken from discussion with Ben Tupper and Ben's program HBB_ANALYZER.
740 </PRE><P>
741 <STRONG>(See blob_analyzer__define.pro)</STRONG><P>
742 <HR>
743
744 <A NAME="CAPFIRSTLETTER">
745 <H2>CAPFIRSTLETTER</H2></A>
746 <A HREF="#BLOB_ANALYZER__DEFINE">[Previous Routine]</A>
747 <A HREF="#CHECKERBOARD">[Next Routine]</A>
748 <A HREF="#ROUTINELIST">[List of Routines]</A>
749 <PRE>
750 NAME:
751 CAPFIRSTLETTER
752
753 PURPOSE:
754
755 Given a string, separates the parts by white space, commas,
756 semi-colons, or colons. Each part has the first letter capitalized.
757 The returned string has the capitalized parts separated by a space.
758
759 AUTHOR:
760
761 FANNING SOFTWARE CONSULTING
762 David Fanning, Ph.D.
763 1645 Sheely Drive
764 Fort Collins, CO 80526 USA
765 Phone: 970-221-0438
766 E-mail: [email protected]
767 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
768
769 CATEGORY:
770
771 Utilities
772
773 CALLING SEQUENCE:
774
775 capitalizedString = CatFirstLetter(theString)
776
777 AUGUMENTS:
778
779 theString: The input string.
780
781 RETURN_VALUE:
782
783 capitalizedString: The capitalized output string. There is a space between parts
784 (words) of the input string.
785
786 KEYWORDS:
787
788 None.
789
790 MODIFICATION HISTORY:
791
792 Written by David W. Fanning, 29 July 2005.
793 </PRE><P>
794 <STRONG>(See capfirstletter.pro)</STRONG><P>
795 <HR>
796
797 <A NAME="CHECKERBOARD">
798 <H2>CHECKERBOARD</H2></A>
799 <A HREF="#CAPFIRSTLETTER">[Previous Routine]</A>
800 <A HREF="#CINDEX">[Next Routine]</A>
801 <A HREF="#ROUTINELIST">[List of Routines]</A>
802 <PRE>
803 NAME:
804 Checkerboard
805
806 PURPOSE:
807 This function returns a 2D image, with boxes of alternating colors.
808 Checkerboard images are useful in certain types of image processing
809 procedures and for making blended image masks.
810
811 AUTHOR:
812 FANNING SOFTWARE CONSULTING
813 David Fanning, Ph.D.
814 1645 Sheely Drive
815 Fort Collins, CO 80526 USA
816 Phone: 970-221-0438
817 E-mail: [email protected]
818 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
819
820 CATEGORY:
821
822 Image Processing
823
824 CALLING SEQUENCE:
825
826 board = Checkerboard()
827
828 RETURN VALUE:
829
830 board: A 2D long array of alternating colored boxes.
831
832 ARGUMENTS:
833
834 boxes: The number of boxes of alternating colors on each side
835 of the resulting image. Must be an even integer greater
836 than or equal to two. Optional. Default is 8 (normal
837 checkerboard).
838
839 INPUT KEYWORDS:
840
841 BLACK: The value of the "black" boxes. By default, 0.
842
843 WHITE: The value of the "white" boxes. By default, 255.
844
845 XSIZE: The X size of the returned image. By default, 400.
846
847 YSIZE: The Y size of the returned image. By default, 400.
848
849 COMMON BLOCKS:
850
851 None.
852
853 EXAMPLE:
854
855 IDL> cgImage, Checkerboard()
856
857 MODIFICATION HISTORY:
858
859 Written by David W. Fanning, 26 September 2007, based on suggestions
860 of JD Smith on IDL newsgroup 25-26 Septermber 2007.
861 </PRE><P>
862 <STRONG>(See checkerboard.pro)</STRONG><P>
863 <HR>
864
865 <A NAME="CINDEX">
866 <H2>CINDEX</H2></A>
867 <A HREF="#CHECKERBOARD">[Previous Routine]</A>
868 <A HREF="#CLIPBOARD">[Next Routine]</A>
869 <A HREF="#ROUTINELIST">[List of Routines]</A>
870 <PRE>
871 NAME:
872 CIndex
873
874 PURPOSE:
875 This is a program for viewing the current colors in the
876 colortable with their index numbers overlayed on each color.
877 On 24-bit systems you must click the cursor in the graphics window
878 to see the colors in the current color table.
879
880 AUTHOR:
881 FANNING SOFTWARE CONSULTING
882 David Fanning, Ph.D.
883 1645 Sheely Drive
884 Fort Collins, CO 80526 USA
885 Phone: 970-221-0438
886 E-mail: [email protected]
887 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
888
889 CATEGORY: Graphics
890
891 CALLING SEQUENCE: CIndex
892
893 INPUTS: None.
894
895 INPUT KEYWORDS:
896
897 BREWER: If this keyword is set, the BREWER colors will be loaded with the
898 Change Colors button. (Assuming the brewer color table file, fsc_brewer.tbl,
899 has been installed.
900
901 OUTPUTS: None
902
903 OPTIONAL OUTPUTS: None
904
905 OUTPUT KEYWORDS:
906
907 NOTIFYID: A two-element array containing the Change Colors button widget
908 identifier and the identifier of the top-level base widget. This
909 array is meant to be sent to an XCOLORS routine via its NOTIFYID
910 keyword. This will allow instant updating of the CINDEX interface.
911
912 COMMON BLOCKS: None
913
914 SIDE EFFECTS: None
915
916 RESTRICTIONS: Reqires XCOLORS and cgImage from the Coyote Library:
917
918 http://www.idlcoyote.com/programs/xcolors.pro
919 http://www.idlcoyote.com/programs/cgImage.pro
920
921 PROCEDURE:
922
923 Draws a 31x25 set of small rectangles in 256 different colors.
924 Writes the color index number on top of each rectangle.
925
926 MODIFICATION HISTORY: Written by David Fanning, May 1995
927
928 Widgetized and made it work in 24-bit color. Colors are
929 updated by clicking in window. 22 Oct 98. DWF
930 Replace POLYFILL with TV command to avoid underflow error in
931 Z-buffer. 8 March 99. DWF
932 Fixed a problem with 24-bit devices with color decomposition ON. 15 Feb 2000. DWF.
933 Added the NOTIFYID keyword, 15 Dec 2005. DWF.
934 Added BREWER keyword, 19 May 2008. DWF.
935 Replaced TV commands with cgImage, 12 June 2013. DWF.
936 </PRE><P>
937 <STRONG>(See cindex.pro)</STRONG><P>
938 <HR>
939
940 <A NAME="CLIPBOARD">
941 <H2>CLIPBOARD</H2></A>
942 <A HREF="#CINDEX">[Previous Routine]</A>
943 <A HREF="#CLIPSCL">[Next Routine]</A>
944 <A HREF="#ROUTINELIST">[List of Routines]</A>
945 <PRE>
946 NAME:
947 CLIPBOARD
948
949 PURPOSE:
950
951 The purpose of this program is to copy the contents of a
952 graphics window to the clipboard for subsequent pasting into
953 applications such as Photoshop or Powerpoint.
954
955 AUTHOR:
956
957 FANNING SOFTWARE CONSULTING
958 David Fanning, Ph.D.
959 1645 Sheely Drive
960 Fort Collins, CO 80526 USA
961 Phone: 970-221-0438
962 E-mail: [email protected]
963 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
964
965 CATEGORY:
966
967 Graphics.
968
969 CALLING SEQUENCE:
970
971 CLIPBOARD, window_index
972
973 OPTIONAL INPUTS:
974
975 window_index: The window index number of the graphics window to
976 copy. If absent, the current graphics window is used
977 by default.
978
979 KEYWORDS:
980
981 All COLOR_QUAN keywords are allowed. In particular, if you are
982 taking snapshots of line plots with few colors in them, you may
983 get better results by calling the program with the CUBE=6 keyword
984 set. Otherwise, white colors can sometimes be a bit gray.
985
986 OUTPUTS:
987 None.
988
989 COMMON BLOCKS:
990 None.
991
992 DEPENDENCIES:
993
994 Uses the IDLgrClipboard object introduced in IDL 5.2(?).
995
996 PROCEDURE:
997
998 Copies the window contents to a clipboard object.
999
1000 EXAMPLE:
1001
1002 IDL> Window
1003 IDL> Plot, Findgen(11)
1004 IDL> CLIPBOARD
1005
1006 RESTRICTIONS:
1007
1008 May not work for all applications. Applications tested successfully
1009 include: Framemaker, Powerpoint, Photoshop, Excel, Microsoft Word.
1010 Converts 24-bit images to 2D images with color tables.
1011
1012 MODIFICATION HISTORY:
1013
1014 Written by: David W. Fanning, 24 October 2001.
1015 Added _EXTRA keyword to pass COLOR_QUAN keywords along. 28 Oct 2002. DWF.
1016 </PRE><P>
1017 <STRONG>(See clipboard.pro)</STRONG><P>
1018 <HR>
1019
1020 <A NAME="CLIPSCL">
1021 <H2>CLIPSCL</H2></A>
1022 <A HREF="#CLIPBOARD">[Previous Routine]</A>
1023 <A HREF="#COLORBUTTONBITMAP">[Next Routine]</A>
1024 <A HREF="#ROUTINELIST">[List of Routines]</A>
1025 <PRE>
1026 NAME:
1027 CLIPSCL
1028
1029 PURPOSE:
1030
1031 This is a utility routine to perform linear scaling (similar to BYTSCL)
1032 on image arrays. If differs from BYTSCL only in that a user-specified
1033 percentage of pixels can be clipped from the image histogram, prior to
1034 scaling. By default, two percent of the pixels are clipped. Clipping
1035 occurs at both ends of the image histogram.
1036
1037 AUTHOR:
1038
1039 FANNING SOFTWARE CONSULTING
1040 David Fanning, Ph.D.
1041 1645 Sheely Drive
1042 Fort Collins, CO 80526 USA
1043 Phone: 970-221-0438
1044 E-mail: [email protected]
1045 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1046
1047 CATEGORY:
1048
1049 Utilities
1050
1051 CALLING SEQUENCE:
1052
1053 scaledImage = CLIPSCL(image, clipPercent)
1054
1055 ARGUMENTS:
1056
1057 image: The image to be scaled. Written for 2D images, but arrays
1058 of any size are treated alike.
1059
1060 clipPercent: The percent of image clipping. Optional argument is set
1061 to 2 by default. Must be value between 0 and 49. Clipping
1062 occurs from both ends of image histogram, so a clip of 2
1063 linearly scales approximately 96% of the image histogram.
1064 Clipping percents are approximations only, and depend
1065 entirely on the distribution of pixels in the image. For
1066 interactive scaling, see cgStretch.
1067
1068 INPUT KEYWORDS:
1069
1070
1071 NEGATIVE: If set, the "negative" of the result is returned.
1072
1073 OMAX: The output image is scaled between OMIN and OMAX. The
1074 default value is 255.
1075
1076 OMIN: The output image is scaled between OMIN and OMAX. The
1077 default value is 0.
1078 OUTPUT KEYWORDS:
1079
1080
1081 THRESHOLD: A two-element array containing the image thresholds for clipping.
1082
1083 RETURN VALUE:
1084
1085 scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
1086
1087 COMMON BLOCKS:
1088 None.
1089
1090 EXAMPLES:
1091
1092 LoadCT, 0 ; Gray-scale colors.
1093 image = cgDemoData(22) ; Load image.
1094 TV, ClipScl(image, 4)
1095
1096 RESTRICTIONS:
1097
1098 Requires cgScaleVector from the Coyote Library:
1099
1100 http://www.idlcoyote.com/programs/cgScaleVector.pro
1101
1102 MODIFICATION HISTORY:
1103
1104 Written by: David W. Fanning, 6 September 2007.
1105 Not sure what this program was doing, but not what I thought. I've reworked
1106 the algorithm to scale the data appropriately. 25 Oct 2011. DWF.
1107 </PRE><P>
1108 <STRONG>(See clipscl.pro)</STRONG><P>
1109 <HR>
1110
1111 <A NAME="COLORBUTTONBITMAP">
1112 <H2>COLORBUTTONBITMAP</H2></A>
1113 <A HREF="#CLIPSCL">[Previous Routine]</A>
1114 <A HREF="#COLORSAREIDENTICAL">[Next Routine]</A>
1115 <A HREF="#ROUTINELIST">[List of Routines]</A>
1116 <PRE>
1117 NAME:
1118 ColorButtonBitmap
1119
1120 PURPOSE:
1121
1122 The purpose of this program is to create a 24-bit bitmap that can be used to
1123 create a colored widget button.
1124
1125 AUTHOR:
1126
1127 FANNING SOFTWARE CONSULTING
1128 David Fanning, Ph.D.
1129 1645 Sheely Drive
1130 Fort Collins, CO 80526 USA
1131 Phone: 970-221-0438
1132 E-mail: [email protected]
1133 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1134
1135 CATEGORY:
1136
1137 Widget Programming
1138
1139 CALLING SEQUENCE:
1140
1141 bitmap = ColorButtonBitmap(theText)
1142 button = Widget_Button(tlb, Value=bitmap)
1143
1144 REQUIRED INPUTS:
1145
1146 theText - The text you wish to have on the button.
1147
1148 OUTPUTS:
1149
1150 bitmap - A 3xMxN byte array, representing a 24-bit image that is used
1151 as a button value.
1152
1153 OPTIONAL KEYWORDS:
1154
1155 BGCOLOR - The name of the background color. For example, 'Yellow', 'Tan', etc.
1156 The name must be compatible with names appropriate for cgColor.
1157
1158 FGCOLOR - The name of the foreground color. For example, 'Navy', 'Black', etc.
1159 The name must be compatible with names appropriate for cgColor.
1160
1161
1162 DEPENDENCIES:
1163
1164 Reqires cgColor from the Coyote Library:
1165
1166 http://www.idlcoyote.com/programs/cgColor.pro
1167
1168 EXAMPLE:
1169
1170 tlb = Widget_Base(/Row, /Exclusive)
1171 button1 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 1')) ; Normal button.
1172 button2 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 2', FGCOLOR='YELLOW', BGCOLOR='NAVY'))
1173 button3 = Widget_Button(tlb, Value=ColorButtonBitmap('Button 3', BGCOLOR='YELLOW', FGCOLOR='NAVY'))
1174 Widget_Control, tlb, /Realize
1175
1176 MODIFICATION HISTORY:
1177
1178 Written by David Fanning, May 25, 2007 based on code named BitmapForButtonText supplied to the IDL
1179 newsgroup by Dick Jackson: http://www.idlcoyote.com/tip_examples/bitmapforbuttontext.pro.
1180 Fixed a problem with foreground and background colors that caused them to work correctly only
1181 when color decomposition is on--as it should be :-). 6 May 2009.
1182 </PRE><P>
1183 <STRONG>(See colorbuttonbitmap.pro)</STRONG><P>
1184 <HR>
1185
1186 <A NAME="COLORSAREIDENTICAL">
1187 <H2>COLORSAREIDENTICAL</H2></A>
1188 <A HREF="#COLORBUTTONBITMAP">[Previous Routine]</A>
1189 <A HREF="#CONTRASTZOOM">[Next Routine]</A>
1190 <A HREF="#ROUTINELIST">[List of Routines]</A>
1191 <PRE>
1192 :Description:
1193 Returns a 1 if the two input colors refer to the same color, otherwise returns a 0.
1194
1195 :Categories:
1196 Graphics Utility
1197
1198 :Params:
1199 color_1: in, required, type=string/integer/long
1200 The first color to compare for "equality".
1201 color_2: in, required, type=string/integer/long
1202 The second color to compare for "equality".
1203
1204 :Keywords:
1205 None.
1206
1207 :Examples:
1208 Used to compare if two different colors are the same color::
1209 IDL> Print, ColorsAreIdentical('white', cgColor('white'))
1210 IDL> Print, ColorsAreIdentical(252, !P.Color)
1211 IDL> Print, ColorsAreIdentical('white', '255')
1212
1213 :Author:
1214 FANNING SOFTWARE CONSULTING::
1215 David W. Fanning
1216 1645 Sheely Drive
1217 Fort Collins, CO 80526 USA
1218 Phone: 970-221-0438
1219 E-mail: [email protected]
1220 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1221
1222 :History:
1223 Change History::
1224 Written, 24 December 2010. DWF.
1225 Fixed a typo when first color is INTEGER and second color is STRING. 3 Jan 2011. DWF.
1226 Added error handling for out of bounds color values. 25 May 2011. DWF.
1227
1228 :Copyright:
1229 Copyright (c) 2010, Fanning Software Consulting, Inc.
1230 </PRE><P>
1231 <STRONG>(See colorsareidentical.pro)</STRONG><P>
1232 <HR>
1233
1234 <A NAME="CONTRASTZOOM">
1235 <H2>CONTRASTZOOM</H2></A>
1236 <A HREF="#COLORSAREIDENTICAL">[Previous Routine]</A>
1237 <A HREF="#CONVERT_TO_TYPE">[Next Routine]</A>
1238 <A HREF="#ROUTINELIST">[List of Routines]</A>
1239 <PRE>
1240 NAME:
1241 CONTRASTZOOM
1242
1243 PURPOSE:
1244
1245 The purpose of this program is to demonstrate how to
1246 zoom an image "in place" and how to window and level
1247 (set "contrast and brightness") an image using object
1248 graphics functionality. The exercise involves using
1249 multiple views in an object graphics scene, and being
1250 able to interact with different views in different ways.
1251
1252 AUTHOR:
1253
1254 FANNING SOFTWARE CONSULTING
1255 David Fanning, Ph.D.
1256 1645 Sheely Drive
1257 Fort Collins, CO 80526 USA
1258 Phone: 970-221-0438
1259 E-mail: [email protected]
1260 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1261
1262 CATEGORY:
1263
1264 Widgets, Object Graphics.
1265
1266 CALLING SEQUENCE:
1267
1268 ContrastZoom, image
1269
1270 REQUIRED INPUTS:
1271
1272 None. The image "mr_knee.dcm" from the examples/data directory
1273 is used if no data is supplied in call.
1274
1275 OPTIONAL INPUTS
1276
1277 image: A 2D image array of any data type.
1278
1279 OPTIONAL KEYWORD PARAMETERS:
1280
1281 COLORTABLE: The number of a color table to use as the image palette.
1282 Color table 0 (grayscale) is used as a default.
1283
1284 GROUP_LEADER: The group leader for this program. When the group leader
1285 is destroyed, this program will be destroyed.
1286
1287 COMMON BLOCKS:
1288
1289 None.
1290
1291 SIDE EFFECTS:
1292
1293 None.
1294
1295 RESTRICTIONS:
1296
1297 None. The Coyote Library program VCOLORBAR is included.
1298
1299 EXAMPLE:
1300
1301 To use this program with your 8-bit image data and a red-temperature
1302 color scale, type:
1303
1304 IDL> ContrastZoom, image, Colortable=3
1305
1306 NOTES:
1307
1308 The left image is used to "zoom" into a portion of the image.
1309 The aspect ratio of the sub-image is always preserved. To see
1310 the entire image, click and release the mouse button in this
1311 window.
1312
1313 The center image is used to adjust the contrast and brightness
1314 (sometimes called the "window" and "level" of the image. Click and
1315 drag the mouse vertically to set contrast. Click and drag the mouse
1316 horizontally to set brightness. To return to original values (25%
1317 contrast and 75% brightness), click and release in the center image.
1318
1319 The color bars shows the image values of the image.
1320
1321 MODIFICATION HISTORY:
1322
1323 Written by David Fanning, 18 November 2001.
1324 Added second colorbar to show the relationship of the clamped
1325 colors to the overall image values. 19 November 2001. DWF.
1326 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
1327 </PRE><P>
1328 <STRONG>(See contrastzoom.pro)</STRONG><P>
1329 <HR>
1330
1331 <A NAME="CONVERT_TO_TYPE">
1332 <H2>CONVERT_TO_TYPE</H2></A>
1333 <A HREF="#CONTRASTZOOM">[Previous Routine]</A>
1334 <A HREF="#CW_DRAWCOLOR">[Next Routine]</A>
1335 <A HREF="#ROUTINELIST">[List of Routines]</A>
1336 <PRE>
1337 NAME:
1338 CONVERT_TO_TYPE
1339
1340 PURPOSE:
1341
1342 Converts its input argument to a specified data type.
1343
1344 AUTHOR:
1345
1346 FANNING SOFTWARE CONSULTING
1347 David Fanning, Ph.D.
1348 1645 Sheely Drive
1349 Fort Collins, CO 80526 USA
1350 Phone: 970-221-0438
1351 E-mail: [email protected]
1352 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1353
1354 CATEGORY:
1355
1356 Utilities
1357
1358 CALLING SEQUENCE:
1359
1360 result = Convert_To_Type(input, type)
1361
1362 INPUT_PARAMETERS:
1363
1364 input: The input data to be converted.
1365 type: The data type. Accepts values as given by Size(var, /TNAME) or Size(var, /TYPE).
1366 If converting to integer types, values are truncated (similar to FLOOR keyword below),
1367 unless keywords are set.
1368
1369 OUTPUT_PARAMETERS:
1370
1371 result: The input data is converted to specified data type.
1372
1373 KEYWORDS:
1374
1375 CEILING: If set and converting to an integer type, the CEIL function is applied before conversion.
1376
1377 FLOOR: If set and converting to an integer type, the FLOOR function is applied before conversion.
1378
1379 ROUND: If set and converting to an integer type, the ROUND function is applied before conversion.
1380
1381
1382 RESTRICTIONS:
1383
1384 Data types STRUCT, POINTER, and OBJREF are not allowed.
1385
1386 MODIFICATION HISTORY:
1387
1388 Written by David W. Fanning, 19 February 2006.
1389 Typo had "UNIT" instead of "UINT". 23 February 2009. DWF.
1390 Added CEILING, FLOOR, and ROUND keywords. 1 April 2009. DWF.
1391 Modified so that the "type" variable is not changed by the program. 5 May 2009. DWF.
1392 </PRE><P>
1393 <STRONG>(See convert_to_type.pro)</STRONG><P>
1394 <HR>
1395
1396 <A NAME="CW_DRAWCOLOR">
1397 <H2>CW_DRAWCOLOR</H2></A>
1398 <A HREF="#CONVERT_TO_TYPE">[Previous Routine]</A>
1399 <A HREF="#DIRPATH">[Next Routine]</A>
1400 <A HREF="#ROUTINELIST">[List of Routines]</A>
1401 <PRE>
1402 NAME:
1403 CW_DRAWCOLOR
1404
1405 PURPOSE:
1406
1407 This compound widget is used to place a label or color name next
1408 to a color patch. Clicking on the color patch allows the user
1409 to select another color
1410
1411 AUTHOR:
1412
1413 FANNING SOFTWARE CONSULTING
1414 David Fanning, Ph.D.
1415 1645 Sheely Drive
1416 Fort Collins, CO 80526 USA
1417 Phone: 970-221-0438
1418 E-mail: [email protected]
1419 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1420
1421 CATEGORY:
1422
1423 Graphics
1424
1425 CALLING SEQUENCE:
1426
1427 colorpatchID = CW_DrawColor(parent)
1428
1429 REQUIRED INPUTS:
1430
1431 parent - The identifier of a parent base widget.
1432
1433 OUTPUTS:
1434
1435 colorpatchID - The widget identifier of the top-level base of this compound widget
1436
1437 INPUT KEYWORDS:
1438
1439 COLOR - The name of the color to be displayed. Color names come from cgPickColorName.
1440 COLUMN - Set this keyword to stack widgets in a column. Default is in a row.
1441 EVENT_FUNC - The name of an event handler function for this compound widget.
1442 EVENT_PRO -The name of an event handler procedure for this compound widget.
1443 INDEX - An index number where the color should be loaded. !D.Table_Size-2, by default.
1444 FILENAME - An optional input to cgPickColorName specifying different
1445 colors. See the cgPickColorName documenation for the file format.
1446 LABEL_LEFT - Set this keyword to have the label text aligned on the left of the label. Default is to center.
1447 LABEL_RIGHT - Set this keyword to have the label text aligned on the right of the label. Default is to center.
1448 LABELSIZE - This is the X size of the label widget (containing the label) in device coordinates. Default is natural size.
1449 LABELTEXT - This is the text on the label. Example, "Background Color", etc.
1450 TITLE - This is the title on the cgPickColorName program that allows the user to select another color.
1451 UVALUE - A user value for the widget.
1452 XSIZE - The xsize (in pixel units) of the color patch. By default, 20.
1453 YSIZE - The xsize (in pixel units) of the color patch. By default, 20.
1454
1455 OUTPUT KEYWORDS:
1456
1457 OBJECT - The object reference. Use this to call methods, etc.
1458
1459 OBJECT PROCEDURE METHODS:
1460
1461 Set_Value -- this method takes one argument, the new color name.
1462 It will change the color of the widget if it has
1463 already been realized.
1464
1465 Get_Value -- this method returns the color name the widget is displaying
1466
1467 DEPENDENCIES:
1468
1469 Reqires cgColor and cgPickColorName from the Coyote Library:
1470
1471 http://www.idlcoyote.com/programs/cgColor.pro
1472 http://www.idlcoyote.com/programs/cgPickColorName.pro
1473
1474 MODIFICATION HISTORY:
1475
1476 Written by David W. Fanning, March 2001.
1477 Fixed a problem with self object cleanup. 7 March 2006. DWF.
1478 Allow addition to already realized widget hierarchies, October 2007. L. Anderson.
1479 Added set_value and get_value methods to the widget can be
1480 updated after being realized. October 2007. L. Anderson.
1481 Added option to pass filename on to cgPickColorName. October
1482 2007. L. Anderson
1483 </PRE><P>
1484 <STRONG>(See cw_drawcolor.pro)</STRONG><P>
1485 <HR>
1486
1487 <A NAME="DIRPATH">
1488 <H2>DIRPATH</H2></A>
1489 <A HREF="#CW_DRAWCOLOR">[Previous Routine]</A>
1490 <A HREF="#ERRORLOGGER__DEFINE">[Next Routine]</A>
1491 <A HREF="#ROUTINELIST">[List of Routines]</A>
1492 <PRE>
1493 NAME:
1494 DIRPATH
1495
1496 PURPOSE:
1497
1498 The purpose of this function is to return a device-independent
1499 name of a directory. It is similar to the IDL-supplied FILEPATH
1500 routine, except that a file name is not required.
1501
1502 AUTHOR:
1503
1504 FANNING SOFTWARE CONSULTING
1505 David Fanning, Ph.D.
1506 1645 Sheely Drive
1507 Fort Collins, CO 80526 USA
1508 Phone: 970-221-0438
1509 E-mail: [email protected]
1510 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
1511
1512 CATEGORY:
1513
1514 Utility.
1515
1516 CALLING SEQUENCE:
1517
1518 IDL> theDirectory = DIRPATH('examples')
1519 IDL> Print, theDirectory
1520 C:\IDL\IDL56\examples
1521
1522 INPUTS:
1523
1524 subDirectory: This is a string argument containing the name of the
1525 sub-directory you wish to use. It can be a string
1526 array of sub-directory names. By default, the subDirectory
1527 is set to ['examples', 'data']. To only return the Root_Directory,
1528 set the subDirectory to a null string ("").
1529
1530 KEYWORDS:
1531
1532 ROOT_DIRECTORY: The name of the root directory to use. By default,
1533 the root directory is set to !DIR.
1534
1535 OUTPUTS:
1536
1537 The machine-independent directory path.
1538
1539 MODIFICATION HISTORY:
1540
1541 Written by: David W. Fanning, 28 April 2003.
1542 </PRE><P>
1543 <STRONG>(See dirpath.pro)</STRONG><P>
1544 <HR>
1545
1546 <A NAME="ERRORLOGGER__DEFINE">
1547 <H2>ERRORLOGGER__DEFINE</H2></A>
1548 <A HREF="#DIRPATH">[Previous Routine]</A>
1549 <A HREF="#FIND_BOUNDARY">[Next Routine]</A>
1550 <A HREF="#ROUTINELIST">[List of Routines]</A>
1551 <PRE>
1552 NAME:
1553 ErrorLogger__Define
1554
1555 PURPOSE:
1556
1557 The purpose of this program is to log program errors or text messages during
1558 program execution as an aid to debugging such a program at a later date. The
1559 ErrorLogger program is written as an object so that it will persist in the IDL
1560 session until it is destroyed.
1561
1562 AUTHOR:
1563
1564 FANNING SOFTWARE CONSULTING
1565 David Fanning, Ph.D.
1566 1645 Sheely Drive
1567 Fort Collins, CO 80526 USA
1568 Phone: 970-221-0438
1569 E-mail: [email protected]
1570 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1571
1572 CATEGORY:
1573
1574 Utilities
1575
1576 CALLING SEQUENCE:
1577
1578 errorLogger = Obj_New("ErrorLogger")
1579
1580 ARGUMENTS:
1581
1582 filename: The name of the error log file. If not provided, a default name
1583 will be created, based on the current system time. (Optional)
1584
1585 KEYWORDS:
1586
1587 ALERT: The default behavior of the error logger is simply to write text to a file.
1588 But if the ALERT keyword is set, the program will alert the user via a
1589 message dialog that an error has occurred when using the AddError method.
1590 Default is 0. (Input)
1591
1592 DELETE_ON_DESTROY: If this keyword is set, the error log file will be deleted when the
1593 ErrorLogger object is destroyed, but only if the ErrorLogger object is not
1594 in an error state at that time (error status = 2). Default is 0. (Input)
1595
1596 NOCLUTTER: Believe it or not, some people who use an ErrorLogger prefer that an error log
1597 file is never left behind. (They prefer that the program act like cgErrorMsg.)
1598 For those people, the NOCLUTTER keyword provides a way for them to automatically
1599 set the ALERT and DESTROY_ON_DELETE keywords to 1. It also prevents the error
1600 logger from ever setting the error status to 2. Thus, when the ErrorLogger is
1601 destroyed, the file is always deleted. Default is 0. When set, overrides ALERT
1602 and DELETE_ON_DESTROY settings. (Input)
1603
1604 NOTRACEBACK: Set this keyword to suppress traceback information in the error log output
1605 and in any alerts issued by the program. Default is 0. (Input)
1606
1607 TIMESTAMP: Set this keyword if you wish a time stamp to be appended to the provided
1608 filename. Otherwise, the filename is used as defined. Default filenames
1609 always have a timestamp appended to the file name. (Input)
1610
1611 METHODS:
1612
1613 AddError: Adds an error text string or array to the error log file. By default,
1614 it will add the HELP, LAST_MESSAGE=1, /TRACEBACE traceback
1615 information to the file. (Procedure)
1616
1617 AddText: Adds a text string or array to the error log file. (Procedure)
1618
1619 ClearLog: Erases all the text currently in the error log file. (Procedure)
1620
1621 CloseFile: Closes the currently open error log file. (Procedure)
1622
1623 Flush: Forces a write of any current information to the disk (Procedure)
1624
1625 GetProperty: Gets properties of the object. (Procedure)
1626
1627 LastMessage: Returns the last message text written into the error log file. (Function)
1628
1629 OpenFile: Opens the error log file for writing. (Function)
1630
1631 PrintLastMessage: Writes the last message text written into the error log file to
1632 standard output. (Procedure)
1633
1634 Status: Returns the current status of the error logger. (0 - waiting for input,
1635 1 - normal operation, 2 - error operation.) (Function)
1636
1637 SetProperty: Sets properties of the object. (Procedure)
1638
1639 SetStatus: Sets the current status of the error logger. Normally not used by the
1640 user, but used internally. (Procedure)
1641
1642 MODIFICATION HISTORY:
1643
1644 Written by David W. Fanning, November 2009.
1645 Modified and expanded the way errors are written into the log file and displayed.
1646 Also made it possible to automatically delete the log file when the object is
1647 destroyed, if the error logger is not in an error state at the time. Added
1648 DELETE_ON_DESTROY and NOTRACEBACK keywords to the INIT and SetProperty
1649 methods. 28 Jan 2010. DWF.
1650 Modified default filenames so that I am now guaranteed to get unique file names
1651 by using cgTimestamp program from the Coyote Library. 8 Feb 2010. DWF.
1652 Added NOCLUTTER keyword. 15 February 2010. DWF.
1653 Added PRINT keyword to AddText method to allow users to log statements that should
1654 also be printed easily to a file. 17 February 2010. DWF.
1655 Small documentation changes to the program. 22 June 2010. DWF.
1656 Made a change so that the file is not opened until something needs to be written
1657 to it. 22 June 2010. DWF.
1658 Added FLUSH method and keyword IMMEDIATE to the INIT method (defaults to 1) which
1659 will immediately flush the log information to disk when log information is
1660 added to the object. This will prevent missing information that is buffered
1661 when a program crashes. Matt Savoie suggestion. DWF, 10 Sept 2010.
1662 Now calling cgTimeStamp rather than TimeStamp to avoid problems with IDL code. 6 Feb 2013. DWF.
1663 </PRE><P>
1664 <STRONG>(See errorlogger__define.pro)</STRONG><P>
1665 <HR>
1666
1667 <A NAME="FIND_BOUNDARY">
1668 <H2>FIND_BOUNDARY</H2></A>
1669 <A HREF="#ERRORLOGGER__DEFINE">[Previous Routine]</A>
1670 <A HREF="#FIT_ELLIPSE">[Next Routine]</A>
1671 <A HREF="#ROUTINELIST">[List of Routines]</A>
1672 <PRE>
1673 NAME:
1674 FIND_BOUNDARY
1675
1676 PURPOSE:
1677
1678 This program finds the boundary points about a region of interest (ROI)
1679 represented by pixel indices. It uses a "chain-code" algorithm for finding
1680 the boundary pixels.
1681
1682 AUTHOR:
1683
1684 FANNING SOFTWARE CONSULTING
1685 David Fanning, Ph.D.
1686 1645 Sheely Drive
1687 Fort Collins, CO 80526 USA
1688 Phone: 970-221-0438
1689 E-mail: [email protected]
1690 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1691
1692 CATEGORY:
1693
1694 Graphics, math.
1695
1696 CALLING SEQUENCE:
1697
1698 boundaryPts = Find_Boundary(indices, XSize=xsize, YSize=ysize)
1699
1700 OPTIONAL INPUTS:
1701
1702 indices - A 1D vector of pixel indices that describe the ROI. For example,
1703 the indices may be returned as a result of the WHERE function.
1704
1705 OUTPUTS:
1706
1707 boundaryPts - A 2-by-n points array of the X and Y points that describe the
1708 boundary. The points are scaled if the SCALE keyword is used.
1709
1710 INPUT KEYWORDS:
1711
1712 SCALE - A one-element or two-element array of the pixel scale factors, [xscale, yscale],
1713 used to calculate the perimeter length or area of the ROI. The SCALE keyword is
1714 NOT applied to the boundary points. By default, SCALE=[1,1].
1715
1716 XSIZE - The X size of the window or array from which the ROI indices are taken.
1717 Set to !D.X_Size by default.
1718
1719 YSIZE - The Y size of the window or array from which the ROI indices are taken.
1720 Set to !D.Y_Size by default.
1721
1722 OUTPUT KEYWORDS:
1723
1724 AREA - A named variable that contains the pixel area represented by the input pixel indices,
1725 scaled by the SCALE factors.
1726
1727 CENTER - A named variable that contains a two-element array containing the center point or
1728 centroid of the ROI. The centroid is the position in the ROI that the ROI would
1729 balance on if all the index pixels were equally weighted. The output is a two-element
1730 floating-point array in device coordinate system, unless the SCALE keyword is used,
1731 in which case the values will be in the scaled coordinate system.
1732
1733 PERIM_AREA - A named variable that contains the (scaled) area represented by the perimeter
1734 points, as indicated by John Russ in _The Image Processing Handbook, 2nd Edition_ on
1735 page 490. This is the same "perimeter" that is returned by IDLanROI in its
1736 ComputeGeometry method, for example. In general, the perimeter area will be
1737 smaller than the pixel area.
1738
1739 PERIMETER - A named variable that will contain the perimeter length of the boundary
1740 upon returning from the function, scaled by the SCALE factors.
1741
1742 EXAMPLE:
1743
1744 LoadCT, 0, /Silent
1745 image = BytArr(400, 300)+125
1746 image[125:175, 180:245] = 255B
1747 indices = Where(image EQ 255)
1748 Window, XSize=400, YSize=300
1749 TV, image
1750 PLOTS, Find_Boundary(indices, XSize=400, YSize=300, Perimeter=length), $
1751 /Device, Color=cgColor('red')
1752 Print, length
1753 230.0
1754
1755 MODIFICATION HISTORY:
1756
1757 Written by David W. Fanning, April 2002. Based on an algorithm written by Guy
1758 Blanchard and provided by Richard Adams.
1759 Fixed a problem with distinction between solitary points and
1760 isolated points (a single point connected on a diagonal to
1761 the rest of the mask) in which the program can't get back to
1762 the starting pixel. 2 Nov 2002. DWF
1763 Added the ability to return the perimeter length with PERIMETER and
1764 SCALE keywords. 2 Nov 2002. DWF.
1765 Added AREA keyword to return area enclosed by boundary. 2 Nov 2002. DWF.
1766 Fixed a problem with POLYFILLV under-reporting the area by removing
1767 POLYFILLV and using a pixel counting method. 10 Dec 2002. DWF.
1768 Added the PERIM_AREA and CENTER keywords. 15 December 2002. DWF.
1769 Replaced the cgErrorMsg routine with the latest version. 15 December 2002. DWF.
1770 Fixed a problem in which XSIZE and YSIZE have to be specified as integers to work. 6 March 2006. DWF.
1771 Fixed a small problem with very small ROIs that caused the program to crash. 1 October 2008. DWF.
1772 Modified the algorithm that determines the number of boundary points for small ROIs. 28 Sept 2010. DWF.
1773 </PRE><P>
1774 <STRONG>(See find_boundary.pro)</STRONG><P>
1775 <HR>
1776
1777 <A NAME="FIT_ELLIPSE">
1778 <H2>FIT_ELLIPSE</H2></A>
1779 <A HREF="#FIND_BOUNDARY">[Previous Routine]</A>
1780 <A HREF="#FIXED_MAP_GRID">[Next Routine]</A>
1781 <A HREF="#ROUTINELIST">[List of Routines]</A>
1782 <PRE>
1783 NAME:
1784 Fit_Ellipse
1785
1786 PURPOSE:
1787
1788 This program fits an ellipse to an ROI given by a vector of ROI indices.
1789
1790 AUTHOR:
1791
1792 FANNING SOFTWARE CONSULTING
1793 David Fanning, Ph.D.
1794 1645 Sheely Drive
1795 Fort Collins, CO 80526 USA
1796 Phone: 970-221-0438
1797 E-mail: [email protected]
1798 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
1799
1800 CATEGORY:
1801
1802 Graphics, math.
1803
1804 CALLING SEQUENCE:
1805
1806 ellipsePts = Fit_Ellipse(indices)
1807
1808 OPTIONAL INPUTS:
1809
1810 indices - A 1D vector of pixel indices that describe the ROI. For example,
1811 the indices may be returned as a result of the WHERE function.
1812
1813 OUTPUTS:
1814
1815 ellipsePts - A 2-by-npoints array of the X and Y points that describe the
1816 fitted ellipse. The points are in the device coodinate system.
1817
1818 INPUT KEYWORDS:
1819
1820 NPOINTS - The number of points in the fitted ellipse. Set to 120 by default.
1821
1822 SCALE - A two-element array that gives the scaling parameters for each X and Y pixel, respectively.
1823 Set to [1.0,1.0] by default.
1824
1825 XSIZE - The X size of the window or array from which the ROI indices are taken.
1826 Set to !D.X_Size by default.
1827
1828 YSIZE - The Y size of the window or array from which the ROI indices are taken.
1829 Set to !D.Y_Size by default.
1830
1831 OUTPUT KEYWORDS:
1832
1833 CENTER -- Set to a named variable that contains the X and Y location of the center
1834 of the fitted ellipse in device coordinates.
1835
1836 ORIENTATION - Set to a named variable that contains the orientation of the major
1837 axis of the fitted ellipse. The direction is calculated in degrees
1838 counter-clockwise from the X axis.
1839
1840 AXES - A two element array that contains the length of the major and minor
1841 axes of the fitted ellipse, respectively.
1842
1843 SEMIAXES - A two element array that contains the length of the semi-major and semi-minor
1844 axes of the fitted ellipse, respectively. (This is simple AXES/2.)
1845
1846 EXAMPLE:
1847
1848 LoadCT, 0, /Silent
1849 image = BytArr(400, 300)+125
1850 image[180:245, 125:175] = 255B
1851 indices = Where(image EQ 255)
1852 Window, XSize=400, YSize=300
1853 TV, image
1854 PLOTS, Fit_Ellipse(indices, XSize=400, YSize=300), /Device, Color=cgColor('red')
1855
1856 MODIFICATION HISTORY:
1857
1858 Written by David W. Fanning, April 2002. Based on algorithms provided by Craig Markwardt
1859 and Wayne Landsman in his TVEllipse program.
1860 Added SCALE keyword and modified the algorithm to use memory more efficiently.
1861 I no longer have to make huge arrays. The arrays are only as big as the blob
1862 being fitted. 17 AUG 2008. DWF.
1863 Fixed small typo that caused blobs of indices with a longer X axis than Y axis
1864 to misrepresent the center of the ellipse. 23 February 2009.
1865 </PRE><P>
1866 <STRONG>(See fit_ellipse.pro)</STRONG><P>
1867 <HR>
1868
1869 <A NAME="FIXED_MAP_GRID">
1870 <H2>FIXED_MAP_GRID</H2></A>
1871 <A HREF="#FIT_ELLIPSE">[Previous Routine]</A>
1872 <A HREF="#FLOATS_EQUAL">[Next Routine]</A>
1873 <A HREF="#ROUTINELIST">[List of Routines]</A>
1874 <PRE>
1875 NAME:
1876 FIXED_MAP_GRID
1877
1878 PURPOSE:
1879 The MAP_GRID procedure draws the graticule of parallels and meridians,
1880 according to the specifications established by MAP_SET. MAP_SET must be called
1881 before MAP_GRID to establish the projection type, the center of the
1882 projection, polar rotation and geographical limits.
1883
1884 CATEGORY:
1885 Mapping.
1886
1887 CALLING SEQUENCE:
1888 MAP_GRID
1889
1890 INPUTS:
1891 NONE
1892
1893 OPTIONAL INPUTS:
1894 NONE
1895
1896 KEYWORD PARAMETERS:
1897
1898
1899 BOX_AXES: Surround the map window with a "box" style axes with
1900 annotations, outside the box, where the parallels intersect the
1901 sides, and the meridians intersect the bottom and top edges of the
1902 box. The border of the box is drawn in alternating foreground and
1903 background colors, with color changes at each intersection with
1904 a parallel or meridian. This keyword determines the thickness of
1905 the box's border, in millimeters. If LABEL is not explicitly
1906 specified, it defaults to 1 when this keyword is present. If this
1907 feature is selected, be sure to leave enough room around the map
1908 window for the annotation, usually by specifying the XMARGIN and
1909 YMARGIN keywords to MAP_SET. See the example below.
1910 CHARSIZE: The size of the characters used for the labels. The default is 1.
1911 COLOR: The color index for the grid lines.
1912 FILL_HORIZON: Fills the current map_horizon.
1913 HORIZON: Draws the current map horizon.
1914 INCREMENT: Determines the spacing between graticle points.
1915 GLINESTYLE: If set, the line style used to draw the grid of parallels and
1916 meridians. See the IDL User's Guide for options. The default is
1917 dotted.
1918 GLINETHICK: The thickness of the grid lines. Default is 1.
1919 LABEL: Set this keyword to label the parallels and meridians with their
1920 corresponding latitudes and longitudes. Setting this keyword to
1921 an integer will cause every LABEL gridline to be labeled (i.e,
1922 if LABEL=3 then every third gridline will be labeled). The
1923 starting point for determining which gridlines are labeled is the
1924 minimum latitude or longitude (-180 to 180), unless the LATS or
1925 LONS keyword is set to a single value. In this case, the starting
1926 point is the value of LATS or LONS.
1927 LATALIGN: This keyword controls the alignment of the text baseline for
1928 latitude labels. A value of 0.0 left justifies the label,
1929 1.0 right justifies it, and 0.5 centers it.
1930 LATDEL: The spacing in degrees between parallels of latitude in the grid.
1931 If not set, a suitable value is determined from the current map
1932 projection.
1933 LATS: The desired latitudes to be drawn (and optionally labeled). If
1934 this keyword is omitted, appropriate latitudes will be generated
1935 with consideration of the optional LATDEL keyword. If this
1936 keyword is set to a single value, drawn (and optionally labeled)
1937 latitudes will be automatically generated as
1938 [...,LATS-LATDEL,LATS,LATS+LATDEL,...] over the extent of the
1939 map. The single valued LATS is taken to be the starting point
1940 for labelling (See the LABEL keyword).
1941 LATLAB: The longitude at which to place latitude labels. The default is
1942 the center longitude on the map.
1943 LATNAMES: An array specifing the names to be used for the latitude labels.
1944 By default, this array is automatically generated in units of
1945 degrees. This array can be a string array or numeric, but should
1946 not be of mixed type. When LATNAMES is specified, LATS must also
1947 be specified, but the number of elments in the two arrays need not
1948 be equal. Extra LATNAMES are ignored, while LATNAMES not supplied
1949 are automatically reported in degrees. LATNAMES can be used when
1950 LATS is set to a single value. It this case, the LATS used will
1951 start at the specified latitude and progress northward, wrapping
1952 around the globe if appropriate. Caution should be used when
1953 using LATNAMES in conjunction with a single LATS, since the
1954 number of visible latitude gridlines is dependent on many factors.
1955 LONALIGN: This keyword controls the alignment of the text baseline for
1956 longitude labels. A value of 0.0 left justifies the label,
1957 1.0 right justifies it, and 0.5 centers it.
1958 LONDEL: The spacing in degrees between meridians of longitude in the grid.
1959 If not set, a suitable value is determined from the current map
1960 projection.
1961 LONLAB: The latitude at which to place longitude labels. The default is
1962 the center latitude on the map.
1963 LONS: The desired longitudes to be drawn (and optionally labeled). If
1964 this keyword is omitted, appropriate longitudes will be generated
1965 with consideration of the optional LONDEL keyword. If this
1966 keyword is set to a single value, drawn (and optionally labeled)
1967 longitudes will be automatically generated as
1968 [...,LONS-LONDEL,LONS,LONS+LONDEL,...] over the extent of the map.
1969 The single valued LONS is taken to be the starting point for
1970 labeling (See the LABEL keyword).
1971 LONNAMES: An array specifing the names to be used for the longitude labels.
1972 By default, this array is automatically generated in units of
1973 degrees. This array can be a string array or numeric, but should
1974 not be of mixed type. When LONNAMES is specified, LATS must also
1975 be specified, but the number of elments in the two arrays need not
1976 be equal. Extra LONNAMES are ignored, while LATNAMES not supplied
1977 are automatically reported in degrees. LONNAMES can be used when
1978 LONS is set to a single value. It this case, the LONS used will
1979 start at the specified longitude and progress eastward, wrapping
1980 around the globe if appropriate. Caution should be used when
1981 using LONNAMES in conjunction with a single LONS, since the number
1982 of visible longitude gridlines is dependent on many factors.
1983
1984 MAP_STRUCTURE: Set this keyword to a !MAP structure, as returned from
1985 MAP_PROJ_INIT. If this keyword is set then the gridlines are passed
1986 through MAP_PROJ_FORWARD and the resulting lines are drawn using
1987 Cartesian coordinates. If this keyword is not set then it is assumed
1988 that MAP_SET has been called to set up a map projection.
1989
1990 NO_GRID: Set this keyword if you only want labels but not gridlines.
1991
1992 ORIENTATION: Specifies the clockwise angle in degrees from horizontal
1993 of the text baseline that the labels should be rotated. Note,
1994 that the rotation used in MAP_SET is also clockwise, but XYOUTS
1995 is normally counterclockwise.
1996
1997 T3D: Set this keyword to indicate that the generalized transformation
1998 matrix in !P.T is to be used. If not present, the user-supplied
1999 coordinates are simply scaled to screen coordinates.
2000
2001 ZVALUE: Sets the Z coordinate, in normalized coordinates in the
2002 range of 0 to 1, at which to output the continents.
2003
2004 Note - This keyword has effect only if keyword T3D is set and the
2005 transformation is stored in !P.T
2006
2007 OUTPUTS:
2008 Draws gridlines and labels on the current map.
2009
2010 EXAMPLE:
2011 map_set,10,20,23.5,/cont,/ortho,/horizon ; establish a projection
2012 lats=[-65,-52,-35,-20,-2.59,15,27.6,35,45,55,75,89]
2013 ; choose the parallels to draw
2014 map_grid,lats=lats,londel=20,lons=-13,label=2,lonlab=-2.5,latlab=7
2015 ;draw the grid
2016 Make a map with a grid surrounded by a box style axis:
2017 map_set, /STEREO, 40, -90,scale=50e6,/CONTINENTS, XMARGIN=3, YMARGIN=3
2018 map_grid, /BOX_AXES, COLOR=3, CHARSIZE=1.5 ;
2019
2020 MODIFICATION HISTORY:
2021 Written by: SVP, May, 23 1996.
2022 DMS, Feb, 1996 Note that this version plots all gridlines
2023 unless a 4 element LIMIT was specified to MAP_SET.
2024 SVP, Nov 1996 Changed over !map1 (new IDL5 maps)
2025 SVP, May 1996 Map_Grid used to live inside of map_set.pro, now
2026 it lives here.
2027 SVP, May 1996 Changed LABEL to determine the skip between labelled
2028 gridlines.
2029 Also, added the LATS and LONS keywords to give complete
2030 control over where the labels go.
2031 SVP, Sept 1996 Added LATNAMS,LONAMES, and ORIENTATION keywords
2032 DMS, Nov, 1996 Rev 2 of maps.
2033 DMS, Jul, 1997 Added Box Axes
2034 CT, Jan 2004: Added MAP_STRUCTURE keyword.
2035 Renamed the function FIXED_MAP_GRID with fixed at lines 555-556 and
2036 664-665 as described here: http://www.dfanning.com/map_tips/missinggrid.html.
2037 This is required to get proper grid output in some applications, but
2038 it breaks other code.
2039 </PRE><P>
2040 <STRONG>(See fixed_map_grid.pro)</STRONG><P>
2041 <HR>
2042
2043 <A NAME="FLOATS_EQUAL">
2044 <H2>FLOATS_EQUAL</H2></A>
2045 <A HREF="#FIXED_MAP_GRID">[Previous Routine]</A>
2046 <A HREF="#FPUFIX">[Next Routine]</A>
2047 <A HREF="#ROUTINELIST">[List of Routines]</A>
2048 <PRE>
2049 NAME:
2050 FLOATS_EQUAL
2051
2052 PURPOSE:
2053
2054 The purpose of this function is to compare two floating-point values or
2055 arrays to determine if the values or arrays are equal. Arrays are equal
2056 if they have the same number of elements, and each element is equal.
2057
2058 To learn why determing if floats are equal is hard (and probably not done
2059 correctly in this program), please read the following article::
2060
2061 http://www.cygnus-software.com/papers/comparingfloats/comparingfloats.htm
2062
2063 AUTHOR:
2064
2065 FANNING SOFTWARE CONSULTING
2066 David Fanning, Ph.D.
2067 1645 Sheely Drive
2068 Fort Collins, CO 80526 USA
2069 Phone: 970-221-0438
2070 E-mail: [email protected]
2071 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
2072
2073 CATEGORY:
2074
2075 Utilities
2076
2077 CALLING SEQUENCE:
2078
2079 result = FLOATS_EQUAL(array_1, array_2)
2080
2081 ARGUMENTS:
2082
2083 array_1 Any single or double precision value or array. Required parameter.
2084
2085 array_2 Any single or double precision value or array. Required parameter.
2086
2087 KEYWORDS:
2088
2089 ULP UNIT in the LAST PLACE. It is the gap or difference between two
2090 floating point numbers in the last digit that can distinguish the
2091 two numbers. Must be a positive integer. Set to 1 by default. Set
2092 to a larger value if you suspect accumulative round-off errors
2093 in your arrays.
2094
2095 RETURN VALUE:
2096
2097 result Set to 1 if the arrays are equal, which means that the arrays have
2098 the same number of elements and each element is equal to the same
2099 element in the other array. Set to 0 if the arrays are not equal.
2100 COMMON BLOCKS:
2101 None.
2102
2103 EXAMPLE:
2104
2105 IDL> a = Findgen(11)
2106 IDL> b = Findgen(11)
2107 IDL> Print, Floats_Equal(a,b)
2108 1
2109 IDL> b[4] = b[4] + 0.0001
2110 IDL> Print, Floats_Equal(a,b)
2111 0
2112
2113 RESTRICTIONS:
2114
2115 None.
2116
2117 MODIFICATION HISTORY:
2118
2119 Written by: David W. Fanning, 29 August 2007.
2120 Fixed a problem when using large numbers with the TOTAL command
2121 by setting the INTEGER keyword. 22 June 2011. DWF.
2122 </PRE><P>
2123 <STRONG>(See floats_equal.pro)</STRONG><P>
2124 <HR>
2125
2126 <A NAME="FPUFIX">
2127 <H2>FPUFIX</H2></A>
2128 <A HREF="#FLOATS_EQUAL">[Previous Routine]</A>
2129 <A HREF="#FSCCLEANUP7">[Next Routine]</A>
2130 <A HREF="#ROUTINELIST">[List of Routines]</A>
2131 <PRE>
2132 NAME:
2133 FPUFIX
2134
2135 PURPOSE:
2136
2137 This is a utility routine to examine a variable and fix problems
2138 that will create floating point underflow errors.
2139
2140 AUTHOR:
2141
2142 FANNING SOFTWARE CONSULTING
2143 David Fanning, Ph.D.
2144 1645 Sheely Drive
2145 Fort Collins, CO 80526 USA
2146 Phone: 970-221-0438
2147 E-mail: [email protected]
2148 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
2149
2150 CATEGORY:
2151
2152 Utilities
2153
2154 CALLING SEQUENCE:
2155
2156 fixedData = FPUFIX(data)
2157
2158 ARGUMENTS:
2159
2160 data : A numerical variable to be checked for values that will cause
2161 floating point underflow errors. Suspect values are set to 0.
2162
2163 KEYWORDS:
2164
2165 None.
2166
2167 RETURN VALUE:
2168
2169 fixedData: The output is the same as the input, except that any values that
2170 will cause subsequent floating point underflow errors are set to 0.
2171
2172 COMMON BLOCKS:
2173 None.
2174
2175 EXAMPLES:
2176
2177 data = FPTFIX(data)
2178
2179 RESTRICTIONS:
2180
2181 None.
2182
2183 MODIFICATION HISTORY:
2184
2185 Written by David W. Fanning, from Mati Meron's example FPU_FIX. Mati's
2186 program is more robust that this (ftp://cars3.uchicago.edu/midl/),
2187 but this serves my needs and doesn't require other programs from
2188 Mati's library. 24 February 2006.
2189 </PRE><P>
2190 <STRONG>(See fpufix.pro)</STRONG><P>
2191 <HR>
2192
2193 <A NAME="FSCCLEANUP7">
2194 <H2>FSCCLEANUP7</H2></A>
2195 <A HREF="#FPUFIX">[Previous Routine]</A>
2196 <A HREF="#FSCCLEANUP8">[Next Routine]</A>
2197 <A HREF="#ROUTINELIST">[List of Routines]</A>
2198 <PRE>
2199 This procedure cleans up any open graphics windows and widget windows for
2200 versions of IDL prior to IDL 8.
2201
2202 :Categories:
2203 Utility
2204
2205 :Keywords:
2206 all: in, optional, type=boolean, default=1
2207 Set this keyword if you wish to clean up windows of all types.
2208 cg: in, optional, type=boolean, default=0
2209 Set this keyword if you wish to clean up only Coyote Graphics windows.
2210 dg: in, optional, type=boolean, default=0
2211 Set this keyword if you wish to clean up only Direct Graphics windows.
2212
2213 :Examples:
2214 For example, to destroy all windows on the display::
2215 IDL> FSCCleanup7
2216
2217 :Author:
2218 FANNING SOFTWARE CONSULTING::
2219 David W. Fanning
2220 1645 Sheely Drive
2221 Fort Collins, CO 80526 USA
2222 Phone: 970-221-0438
2223 E-mail: [email protected]
2224 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
2225
2226 :History:
2227 Written, 6 October 2012.
2228
2229 :Copyright:
2230 Copyright (c) 2012, Fanning Software Consulting, Inc.
2231 </PRE><P>
2232 <STRONG>(See fsccleanup7.pro)</STRONG><P>
2233 <HR>
2234
2235 <A NAME="FSCCLEANUP8">
2236 <H2>FSCCLEANUP8</H2></A>
2237 <A HREF="#FSCCLEANUP7">[Previous Routine]</A>
2238 <A HREF="#FSC_COLORBAR__DEFINE">[Next Routine]</A>
2239 <A HREF="#ROUTINELIST">[List of Routines]</A>
2240 <PRE>
2241 This procedure cleans up any open graphics windows and widget windows for
2242 versions of IDL from IDL 8 onward.
2243
2244 :Categories:
2245 Utility
2246
2247 :Keywords:
2248 all: in, optional, type=boolean, default=1
2249 Set this keyword if you wish to clean up windows of all types.
2250 cg: in, optional, type=boolean, default=0
2251 Set this keyword if you wish to clean up only Coyote Graphics windows.
2252 dg: in, optional, type=boolean, default=0
2253 Set this keyword if you wish to clean up only Direct Graphics windows.
2254 fg: in, optional, type=boolean, default=0
2255 Set this keyword if you wish to clean up only Function Graphics windows.
2256
2257 :Examples:
2258 For example, to destroy all windows on the display::
2259 IDL> FSCCleanup8
2260
2261 :Author:
2262 FANNING SOFTWARE CONSULTING::
2263 David W. Fanning
2264 1645 Sheely Drive
2265 Fort Collins, CO 80526 USA
2266 Phone: 970-221-0438
2267 E-mail: [email protected]
2268 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
2269
2270 :History:
2271 Written, 6 October 2012.
2272
2273 :Copyright:
2274 Copyright (c) 2012, Fanning Software Consulting, Inc.
2275 </PRE><P>
2276 <STRONG>(See fsccleanup8.pro)</STRONG><P>
2277 <HR>
2278
2279 <A NAME="FSC_COLORBAR__DEFINE">
2280 <H2>FSC_COLORBAR__DEFINE</H2></A>
2281 <A HREF="#FSCCLEANUP8">[Previous Routine]</A>
2282 <A HREF="#FSC_COLORSELECT">[Next Routine]</A>
2283 <A HREF="#ROUTINELIST">[List of Routines]</A>
2284 <PRE>
2285 NAME:
2286 FSC_COLORBAR__DEFINE
2287 Note: The name of the routine has been changed from COLORBAR__DEFINE
2288 on 25 Sept 2010 to avoid conflicts with an IDL 8.0 routine of the
2289 same name. See the article "IDL 8 Name Conflicts" here:
2290
2291 http://www.idlcoyote.com/ng_tips/idl8_name_conflicts.html
2292
2293 PURPOSE:
2294 The purpose of this routine is to implement a FSC_COLORBAR object
2295 class. The ColorBar is rendered in the direct graphics system.
2296
2297 AUTHOR:
2298 FANNING SOFTWARE CONSULTING
2299 David Fanning, Ph.D.
2300 1645 Sheely Drive
2301 Fort Collins, CO 80526 USA
2302 Phone: 970-221-0438
2303 E-mail: [email protected]
2304 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
2305
2306 CATEGORY:
2307 Graphics.
2308
2309 CALLING SEQUENCE:
2310 colorbar = Obj_New("FSC_COLORBAR")
2311
2312 INPUTS:
2313 All inputs to the program are via keyword parameters.
2314
2315 KEYWORD PARAMETERS:
2316
2317 Background: Background color. This is the color with which the colorbar is
2318 erased. The default color is !P.Background.
2319 Bottom: Bottom color index of colors allocated to colorbar.
2320 Charsize: Character size of annotation. Default is 1.0.
2321 Color: Color of annotation and outline. Default is !P.Color.
2322 Font: Font to use for annotation. Default is -1, Hershey fonts.
2323 Format: Format of annotation. Default is "(F8.2)".
2324 Major: The number of major tick intervals. Default is 5.
2325 Minor: The number of minor tick intervals. Default is 2.
2326 MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
2327 that resizes the colorbar into the window.
2328 NColors: The number of colors allocated to colorbar. Default is (256 <
2329 !D.N_Colors).
2330 Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
2331 0 (Bilinear).
2332 Position: The position of colorbar in normalized coordinates. Default for a
2333 horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
2334 vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
2335 designed for a 400 by 400 window.
2336 Range: The data range on colorbar. Default is [0, 255].
2337 TickLen: The length of tick marks. Default is -0.1
2338 TickV: Locations for the tick marks in data units. This is the same as
2339 the [XY]TickV keyword. Default is to do what IDL would do
2340 normally.
2341 Vertical: Set this keyword if you want a vertical colorbar. Default is
2342 horizontal.
2343 XEraseBox: A five-element vector of X points (normalized) for erasing the
2344 colorbar plot. Normally this keyword will not have to be used.
2345 The program uses the plot REGION for erasing. But larger
2346 character sizes can result in annotation going outside the
2347 region enclosed by the plot. If that is the case, then use this
2348 keyword along with YEraseBox to specify a larger-than-normal
2349 erasure area. The points are sent to the POLYFILL command for
2350 erasing.
2351
2352 POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background
2353
2354 YEraseBox: A five-element vector of Y points (normalized) for erasing the
2355 colorbar plot.
2356
2357 OBJECT METHODS:
2358
2359 Clamp: This procedure method allows the color bar range to be "clamped"
2360 to a particular data range.
2361
2362 Draw: This procedure method draws the colorbar in the display window. The
2363 ERASE keyword to this method will erase the current colorbar (by
2364 calling the ERASE method) before drawing the colorbar in the display
2365 window.
2366
2367 colorbar->Draw
2368
2369 Erase: This procedure method erases the colorbar object in the window. It
2370 accomplishes this by performing a POLYFILL in the background color.
2371 This method is primarily useful for interactive graphics display
2372 devices.
2373 colorbar->Erase
2374
2375 GetProperty: This procedure method allows one to obtain the current state
2376 of the object via the keyword parameters listed above.
2377
2378 colorbar->GetProperty, Range=currentRange, Title=currentTitle
2379 Print, currentRange, currentTitle
2380
2381 SetProperty: This procedure method allows one to set the properties of the
2382 colorbar object via the keywords described above. In addition,
2383 a DRAW and ERASE keyword are provided so that the colorbar can
2384 be immediately drawn when the new property is set.
2385
2386 colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw
2387
2388 COMMON BLOCKS:
2389 None.
2390
2391 SIDE EFFECTS:
2392 The display window is not erased first.
2393
2394 RESTRICTIONS:
2395 None.
2396
2397 EXAMPLE:
2398 To create a colorbar, use it, then destroy it, type:
2399
2400 colorbar = Obj_New("FSC_COLORBAR", Title='Colorbar Values', Range=[0,1000],$
2401 Format='(I4)')
2402 Window
2403 LoadCT, 5
2404 colorbar->Draw
2405 colorbar->SetProperty, Range=[0,500], /Erase, /Draw
2406 Obj_Destroy, colorbar
2407
2408 MODIFICATION HISTORY:
2409 Written by: David Fanning, Fanning Software Consulting,
2410 26 November 1998.
2411 Added Horizontal keyword to SetProperty method and fixed problem in
2412 going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
2413 Added LoadCT method and current color table index to object.
2414 6 December 1998.
2415 Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
2416 Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
2417 29 Aug 1999. DWF.
2418 10 Oct 99. Modified the program so that current plot and map coordinates
2419 are saved and restored after the colorbar is drawn. DWF.
2420 26 May 2000 Added {XY}TICKV capability to the draw method. This
2421 required adding TickV to the object data structure, and to the
2422 INIT, GetProperty and SetProperty methods.
2423 Changed default tick length to -0.1. DWF (and Jack Saba)
2424 18 Nov 2001. Added Clamp method. DWF.
2425 25 September 2010. Renamed to FSC_Colorbar__Define to avoid conflict with a
2426 Colorbar__Define program introduced with IDL 8.0. DWF.
2427 </PRE><P>
2428 <STRONG>(See fsc_colorbar__define.pro)</STRONG><P>
2429 <HR>
2430
2431 <A NAME="FSC_COLORSELECT">
2432 <H2>FSC_COLORSELECT</H2></A>
2433 <A HREF="#FSC_COLORBAR__DEFINE">[Previous Routine]</A>
2434 <A HREF="#FSC_DROPLIST">[Next Routine]</A>
2435 <A HREF="#ROUTINELIST">[List of Routines]</A>
2436 <PRE>
2437 NAME:
2438 FSC_COLORSELECT
2439
2440 PURPOSE:
2441
2442 The purpose of this compound widget is to provide a means for selecting
2443 a new color or color table in a widget program. The program consists of
2444 a label, a non-editable text widget, and a button to make a color or
2445 color table selection interactively. (See the example program.)
2446
2447 AUTHOR:
2448 FANNING SOFTWARE CONSULTING
2449 David Fanning, Ph.D.
2450 1645 Sheely Drive
2451 Fort Collins, CO 80526 USA
2452 Phone: 970-221-0438
2453 E-mail: [email protected]
2454 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
2455
2456 CATEGORY:
2457
2458 General programming.
2459
2460 CALLING SEQUENCE:
2461
2462 objectRef = FSC_COLORSELECT(parent, Title='Annotate Color ", Color='red')
2463
2464 INPUT PARAMETERS:
2465
2466 parent -- The parent widget ID of the compound widget. Required.
2467
2468 INPUT KEYWORDS:
2469
2470 BREWER: Set if you want Brewer color tables, rather than the normal IDL color tables.
2471 This requires the file fsc_brewer.tbl to be in your IDL path.
2472
2473 CFONT: Set to the name of a font to display the color name in.
2474
2475 COLOR: The name of the color to be displayed in the widget. If color
2476 is not used, or if it is set to a null string, then the widget
2477 will allow selection of a color table, instead of a color name.
2478
2479 CT_INDEX: The color table index number you wish to use. The actual name of the
2480 color table will be displayed in the widget.
2481
2482 EVENT_FUNC: Set this keyword to the name of an Event Function. If this
2483 keyword is undefined and the Event_Pro keyword is undefined,
2484 all compound widget events are handled internally and not
2485 passed on to the parent widget.
2486
2487 EVENT_PRO: Set this keyword to the name of an Event Procedure. If this
2488 keyword is undefined and the Event_Func keyword is undefined,
2489 all compound widget events are handled internally and not
2490 passed on to the parent widget.
2491
2492 FRAME: Set this keyword to put a frame around the compound widget.
2493
2494 LABELALIGN: Set this keyword to align label text. [0-center (default), 1-left, 2-right].
2495
2496 LABELFONT: The font name for the text in the Label Widget.
2497
2498 LABELSIZE: The X screen size of the Label Widget.
2499
2500 NAME: A scalar string name of the object. (Default = ''.)
2501
2502 SCR_XSIZE: The X screen size of the compound widget.
2503
2504 SCR_YSIZE: The Y screen size of the compound widget.
2505
2506 STYLE: The "style" of the text in the Text Widget. A value of 0 (the default)
2507 capitalizes the first letter in the name. A style of 1 uses all lowercase.
2508 A style of 2 uses all uppercase.
2509
2510 TITLE: The text to go on the Label Widget.
2511
2512 UVALUE: A user value for any purpose.
2513
2514 XSIZE: The X size of the Text Widget.
2515
2516 In addition, any keyword defined for WIDGET_TEXT, but not defined here (e.g., SENSITIVE), is
2517 passed along without inspection to the text widget. Use of "extra" keywords is discouraged.
2518
2519 COMMON BLOCKS:
2520
2521 None.
2522
2523 RESTRICTIONS:
2524
2525 None.
2526
2527 EVENT STRUCTURE:
2528
2529 All events are handled internally unless either the Event_Pro or Event_Func
2530 keywords are used to assign an event handler to the compound widget.
2531
2532 event = { FSC_ColorSelect_Event, $; The name of the event structure.
2533 ID: 0L, $ ; The ID of the compound widget's top-level base.
2534 TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
2535 HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
2536 Color: "", $ ; The name of the current color or color table.
2537 Index: 0L, $ ; The color table index selected if color tables are used.
2538 Brewer: 0L, $ ; A flag that indicated Brewer color tables are being used.
2539 NColors: 0L, $ ; The number of colors used for the color table.
2540 ObjRef:Obj_New()} ; The "self" object.
2541
2542 GETTING and SETTING VALUES:
2543
2544 Almost all the properties of the widget can be obtained or set via
2545 the object's GetProperty and SetProperty methods (described below).
2546 But since traditional compound widgets have the ability to get and
2547 set the value of the compound widget, this capability is implemented
2548 as special methods: Get_Color/Set_Color and Get_Color_Index/Set_Color_Index.
2549
2550 To get the color of the widget, do this: color = objectRef->Get_Color()
2551 To set the color of the widget, do this: objectRef->Set_Color, 'blue'.
2552 Valid colors are those returned by FSC_Color. Getting and setting the
2553 color table index number works similarly.
2554
2555 EXAMPLE:
2556
2557 An example program is provided at the end of the FSC_COLORSELECT code. To run it,
2558 type these commands:
2559
2560 IDL> .Compile FSC_COLORSELECT
2561 IDL> Example
2562
2563 DEPENDENCIES:
2564
2565 Requires the Coyote Library:
2566 http://www.idlcoyote.com/programs/coyoteprograms.zip
2567
2568 MODIFICATION HISTORY:
2569
2570 Written by: David W. Fanning, 26 JULY 2010.
2571 </PRE><P>
2572 <STRONG>(See fsc_colorselect.pro)</STRONG><P>
2573 <HR>
2574
2575 <A NAME="FSC_DROPLIST">
2576 <H2>FSC_DROPLIST</H2></A>
2577 <A HREF="#FSC_COLORSELECT">[Previous Routine]</A>
2578 <A HREF="#FSC_FIELD">[Next Routine]</A>
2579 <A HREF="#ROUTINELIST">[List of Routines]</A>
2580 <PRE>
2581 NAME:
2582 FSC_DROPLIST
2583
2584 PURPOSE:
2585
2586 The purpose of this compound widget is to provide an alternative
2587 to the DROPLIST widget offered in the IDL distribution. What has
2588 always annoyed me about a droplist is that you can't get the current
2589 "value" of a droplist easily. This compound widget makes this and
2590 other tasks much easier.
2591
2592 AUTHOR:
2593
2594 FANNING SOFTWARE CONSULTING
2595 David Fanning, Ph.D.
2596 1645 Sheely Drive
2597 Fort Collins, CO 80526 USA
2598 Phone: 970-221-0438
2599 E-mail: [email protected]
2600 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
2601
2602 CATEGORY:
2603
2604 General programming.
2605
2606 CALLING SEQUENCE:
2607
2608 droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)
2609
2610 The return value of the FSC_Droplist (droplistObj in this example) is
2611 an object reference. Interaction with the droplist will occur through
2612 object methods.
2613
2614 INPUT PARAMETERS:
2615
2616 parent -- The parent widget ID of the compound widget. Required.
2617
2618 INPUT KEYWORDS:
2619
2620 Any keyword that is appropriate for the Widget_Droplist function can be used.
2621 In addition, these keywords are explicitly defined.
2622
2623 EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
2624 EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
2625 FORMAT -- A format specifier for the "format" of the values in the droplist.
2626 INDEX -- The index number of the current selection.
2627 SPACES -- A two-element array that indicates the number of blank spaces to be added
2628 to the the beginning and end of the formatted values. If a single number
2629 is provided, this number of blank spaces is added to both the beginning
2630 and the end of the value.
2631 TITLE -- The title of the droplist widget.
2632 UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
2633 UVALUE -- The normal "user value" of the droplist.
2634 VALUE -- An array of the droplist "selections". May be any data type.
2635
2636 COMMON BLOCKS:
2637
2638 None.
2639
2640 EVENT STRUCTURE:
2641
2642 An event is returned each time the droplist value is changed. The event structure
2643 is defined like this:
2644
2645 event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure.
2646 ID: 0L, $ ; The ID of the compound widget's top-level base.
2647 TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
2648 HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
2649 INDEX: 0L, $ ; The index number of the current selection.
2650 SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
2651 SELF:Obj_New() } ; The object reference of the compound widget.
2652
2653 PUBLIC OBJECT METHODS:
2654
2655 GetID -- A function with no arguments that returns the widget identifier
2656 of the droplist widget.
2657
2658 droplistID = droplistObj->GetID()
2659
2660 GetIndex -- A function with no arguments that returns the index
2661 number of the current droplist selection.
2662
2663 currentIndex = droplistObj->GetIndex()
2664
2665 GetSelection -- A function with no arguments that returns the current
2666 droplist selection.
2667
2668 currentSelection = droplistObj->GetSelection()
2669
2670 GetUValue -- A function with no arguments that returns the "user value"
2671 of the compound widget i.e., the value set with the UVALUE keyword).
2672
2673 myUValue = droplistObj->GetUValue()
2674
2675 GetValues -- A function with no arguments that returns the "values" or
2676 "selections" for the droplist.
2677
2678 possibleSelections = droplistObj->GetValues()
2679
2680 Resize -- A procedure that sets the X screen size of the droplist. It is
2681 defined like this:
2682
2683 PRO Resize, newSize, ParentSize=parentSize
2684
2685 The "newSize" keyword is the new X screen size. If this argument is
2686 missing, the screen X size of the compound widget's parent is used.
2687 The parentSize keyword is an output keyword that returns the X screen
2688 size of the compound widget's parent.
2689
2690 droplistObj->Resize, 400
2691
2692 Note that not all devices (e.g., X Windows devices) support droplist resizing.
2693
2694 SetIndex -- A procedure that sets the current droplist selection based on
2695 the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex
2696
2697 droplistObj->SetIndex, newIndex
2698
2699 SetSelection -- Whereas a regular droplist widget can only be set by index
2700 number, this compound widget can also be set by a "selection". The new selection
2701 can be any data type and corresponds to one of the "values" of the droplist.
2702
2703 droplistObj->SetSelection, newSelection
2704
2705 SetValues -- Sets the possible selections of the droplist widget. The CurrentIndex keyword
2706 will allow the current index of the selection to be changed to:
2707
2708 newChoices = ['dog', 'cat', 'coyote']
2709 droplistObj->SetValues, newChoices, CurrentIndex=2
2710
2711
2712 EXAMPLE:
2713
2714 An example program is provided at the end of the FSC_DROPLIST code. To run it,
2715 type these commands:
2716
2717 IDL> .Compile FSC_DROPLIST
2718 IDL> Example
2719
2720 MODIFICATION HISTORY:
2721
2722 Written by: David W Fanning, 17 Jan 2000. DWF.
2723 Added FORMAT and SPACES keywords 28 April 2000. DWF.
2724 Fixed a small problem with event processing when the EVENT_FUNC keyword
2725 was used. 29 Dec 2000. DWF.
2726 Attached the UNAME value to the TLB of the compound widget instead
2727 of to the droplist widget itself. 11 Jan 2001. DWF.
2728 Fixed a problem when the droplist was part of a modal widget and used the
2729 EVENT_PRO keyword. 27 Oct 2003. DWF.
2730 Added a SetValue method for setting all the values in the droplist at once. 12 Nov 2004. DWF.
2731 Fixed type on line 346/ 6 Feb 2008. DWF.
2732 </PRE><P>
2733 <STRONG>(See fsc_droplist.pro)</STRONG><P>
2734 <HR>
2735
2736 <A NAME="FSC_FIELD">
2737 <H2>FSC_FIELD</H2></A>
2738 <A HREF="#FSC_DROPLIST">[Previous Routine]</A>
2739 <A HREF="#FSC_FILESELECT">[Next Routine]</A>
2740 <A HREF="#ROUTINELIST">[List of Routines]</A>
2741 <PRE>
2742 NAME:
2743 FSC_FIELD
2744
2745 PURPOSE:
2746
2747 The purpose of this compound widget is to provide an alternative
2748 to the CW_FIELD widget offered in the IDL distribution. One weakness
2749 of the CW_FIELD compound widget is that the text widgets do not
2750 look editable to the users on Windows platforms. This program
2751 corrects that deficiency and adds some features that I think
2752 will be helpful. For example, you can now assign an event handler
2753 to the compound widget, ask for positive numbers only, and limit
2754 the number of digits in a number, or the number of digits to the
2755 right of a decimal point. The program is written as a widget object,
2756 which allows the user to call object methods directly, affording
2757 even more flexibility in use. This program replaces the earlier
2758 programs FSC_INPUTFIELD and COYOTE_FIELD.
2759
2760 The program consists of a label widget next to a one-line text widget.
2761 The "value" of the compound widget is shown in the text widget. If the
2762 value is a number, it will not be possible (generally) to type
2763 alphanumeric values in the text widget. String values behave like
2764 strings in any one-line text widget.
2765
2766 AUTHOR:
2767
2768 FANNING SOFTWARE CONSULTING
2769 David Fanning, Ph.D.
2770 1645 Sheely Drive
2771 Fort Collins, CO 80526 USA
2772 Phone: 970-221-0438
2773 E-mail: [email protected]
2774 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
2775
2776 CATEGORY:
2777
2778 General programming.
2779
2780 TYPICAL CALLING SEQUENCE:
2781
2782 fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
2783
2784 INPUT PARAMETERS:
2785
2786 parent -- The parent widget ID of the compound widget. Required.
2787
2788 INPUT KEYWORDS:
2789
2790 COLUMN Set this keyword to have the Label widget above the Text widget.
2791 The default is to have the Label widget in a row with the Text widget.
2792
2793 CR_ONLY Set this keyword if you only want Carriage Return events returned to
2794 your event handler. If this keyword is not set, all events are returned.
2795 Setting this keyword has no effect unless either the EVENT_PRO or
2796 EVENT_FUNC keyword is used.
2797
2798 DECIMAL Set this keyword to the number of digits to the right of the decimal
2799 point in floating point or double precision numbers. Ignored for STRING values.
2800
2801 DIGITS Set this keyword to the number of digits permitted in integer numbers.
2802
2803 EVENT_FUNC Set this keyword to the name of an event handler function. If this
2804 keyword is undefined and the Event_Pro keyword is undefined,
2805 all compound widget events are handled internally and not
2806 passed on to the parent widget.
2807
2808 EVENT_PRO Set this keyword to the name of an event handler procedure. If this
2809 keyword is undefined and the Event_Func keyword is undefined,
2810 all compound widget events are handled internally and not
2811 passed on to the parent widget.
2812
2813 FIELDFONT The font name for the text in the text widget.
2814
2815 FRAME Set this keyword to put a frame around the compound widget.
2816
2817 FOCUS_EVENTS Set this keyword to enable event generation for keyboard focus
2818 events. Ignored unless EVENT_FUNC or EVENT_PRO keywords are specified.
2819
2820 HIGHLIGHT Set this keyword to highlight the existing text if the widget gain
2821 the keyboard focus. This keyword MUST be set for tabbing to work naturally
2822 in IDL 6.2 and higher.
2823
2824 LABEL_LEFT Set this keyword to align the text on the label to the left.
2825
2826 LABEL_RIGHT Set this keyword to align the text on the label to the right.
2827
2828 LABELFONT The font name for the text in the label widget.
2829
2830 LABELSIZE The X screen size of the label widget.
2831
2832 NAME A string containing the name of the object. The default is ''.
2833
2834 NOEDIT Set this keyword to allow no user editing of the input text widget.
2835
2836 NONSENSITIVE Set this keyword to make the input text widget non-sensitive.
2837
2838 POSITIVE Set this keyword if you want only positive numbers allowed.
2839
2840 SCR_XSIZE The X screen size of the compound widget.
2841
2842 SCR_YSIZE The Y screen size of the compound widget.
2843
2844 TITLE The string text placed on the label widget.
2845
2846 UNDEFINED Set this keyword to the value to use for "undefined" values. If
2847 not set, then !Value.F_NAN is used for numerical fields and a
2848 NULL string is used for string fields. This applies to values
2849 obtained with the GET_VALUE method or the GET_VALUE function.
2850
2851 UVALUE A user value for any purpose.
2852
2853 VALUE The "value" of the compound widget. Any type of integer, floating, or string
2854 variable is allowed. The data "type" is determined automatically from the
2855 value supplied with this keyword. Be sure you set the type appropriately for
2856 your intended use of the value.
2857
2858 XSIZE The X size of the text widget in the usual character units.
2859
2860 OUTPUT KEYWORDS:
2861
2862 OBJECT Set this keyword to a named variable to receive the compound widget's
2863 object reference. This is required if you wish to call methods on the object.
2864 Note that the object reference is also available in the event structure
2865 generated by the widget object. Note that the object reference will be
2866 necessary if you want to get or set values in the compound widget.
2867
2868 COMMON BLOCKS:
2869
2870 None.
2871
2872 RESTRICTIONS:
2873
2874 Requires cgDblToStr from the Coyote Library:
2875 http://www.idlcoyote.com/programs/cgdbltostr.pro
2876
2877 EVENT STRUCTURE:
2878
2879 All events are handled internally unless either the Event_Pro or Event_Func
2880 keywords are used to assign an event handler to the compound widget. By
2881 default all events generated by the text widget are passed to the assigned
2882 event handler. If you wish to receive only Carriage Return events, set the
2883 CR_Only keyword.
2884
2885 event = { FSC_FIELD_EVENT, $ ; The name of the event structure.
2886 ID: 0L, $ ; The ID of the compound widget's top-level base.
2887 TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
2888 HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
2889 OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
2890 VALUE: Ptr_New(), $ ; A pointer to the widget value.
2891 TYPE:"" ; A string indicating the type of data in the VALUE field.
2892 }
2893
2894 Note that if the field is "empty", the VALUE will be a pointer
2895 to an undefined variable. You should check this value before you
2896 use it. You code will look something like this:
2897
2898 IF N_Elements(*event.value) EQ 0 THEN $
2899 Print, 'Current Value UNDEFINED.' ELSE $
2900 Print, 'Current Value: ', *event.value
2901
2902 GETTING and SETTING VALUES:
2903
2904 Almost all the properties of the widget can be obtained or set via
2905 the object's GetProperty and SetProperty methods (described below).
2906 Traditional compound widgets have the ability to get and set the "value"
2907 of the compound widget identifier (e.g., fieldID in the calling
2908 sequence above). Unfortunately, it is impossible to retreive a variable
2909 in this way when the variable is undefined. In practical terms, this
2910 means that the undefined variable must be set to *something*. You can
2911 determine what that something is with the UNDEFINED keyword, or I will set
2912 it to !VALUES.F_NAN for numerical fields and to the null string for string
2913 fields. In any case, you will have to check for undefined variables before
2914 you try to do something with the value. For a numerical field, the code
2915 might look something like this:
2916
2917 fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
2918 currentValue = fieldObject->Get_Value()
2919 IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue
2920
2921 Additional examples are provided in the numerical example fields in Example Program below.
2922
2923 Setting the value of the compound widget is the same as calling the Set_Value
2924 method on the object reference. In other words, these two statements are equivalent.
2925
2926 fieldObject->Set_Value, 45.4
2927 Widget_Control, fieldID, Set_Value=45.4
2928
2929 The data type of the value is determined from the value itself. Be sure you set it appropriately.
2930
2931 OBJECT PROCEDURE METHODS:
2932
2933 GetProperty -- This method allows various properties of the widget to be
2934 returned via output keywords. The keywords that are available are:
2935
2936 CR_Only -- A flag, if set, means only report carriage return events.
2937 DataType -- The data type of the field variable.
2938 Decimal -- Set this keyword to the number of digits to the right of the decimal
2939 point in FLOATVALUE and DOUBLEVALUE numbers.
2940 Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
2941 Event_Func -- The name of the event handler function.
2942 Event_Pro -- The name of the event handler function.
2943 Has_Focus -- Set to 1 if the text widget currently has the keyboard focus.
2944 Highlight -- The highlight flag.
2945 NoEdit -- The NoEdit flag.
2946 NonSensitive -- The NonSensitive flag.
2947 Undefined -- The "value" of any undefined value.
2948 UValue -- The user value assigned to the compound widget.
2949 Value -- The "value" of the compound widget.
2950 Name -- A scalar string name of the object.
2951
2952 Resize -- This method allows you to resize the compound widget's text field.
2953 The value parameter is an X screen size for the entire widget. The text
2954 widget is sized by using the value obtained from this value minus the
2955 X screen size of the label widget.
2956
2957 objectRef->Resize, screen_xsize_value
2958
2959 Set_Value -- This method allows you to set the "value" of the field. It takes
2960 one positional parameter, which is the value.
2961
2962 objectRef->Set_Value, 5
2963
2964 SetProperty -- This method allows various properties of the widget to be
2965 set via input keywords. The keywords that are available are:
2966
2967 CR_Only -- Set this keyword if you only want Carriage Return events.
2968 Decimal -- Set this keyword to the number of digits to the right of the decimal
2969 point in FLOAT and DOUBLE numbers.
2970 Digits -- Set this keyword to the number of digits permitted in INTERGER and LONG numbers.
2971 Event_Func -- Set this keyword to the name of an Event Function.
2972 Event_Pro -- Set this keyword to the name of an Event Procedure.
2973 Highlight -- Set this keyword to highlight the existing text
2974 when the widget gets the keyboard focus
2975 LabelSize -- The X screen size of the Label Widget.
2976 Name -- A scalar string name of the object. (default = '')
2977 NoEdit -- Set this keyword to make the text widget uneditable
2978 NonSensitive -- Set this keyword to make the widget nonsensitive
2979 Scr_XSize -- The X screen size of the text widget.
2980 Scr_YSize -- The Y screen size of the text widget.
2981 Title -- The text to go on the Label Widget.
2982 UValue -- A user value for any purpose.
2983 Value -- The "value" of the compound widget.
2984 XSize -- The X size of the Text Widget.
2985
2986 SetTabNext -- This method allows you to specify which field to go to when a TAB character
2987 is typed in the text widget. See the Example program below for an example of how to
2988 use this method.
2989
2990 OBJECT FUNCTIONS METHODS:
2991
2992 Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
2993 if a "number" field is blank. Should be checked before using:
2994
2995 IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
2996
2997 GetID -- Returns the widget identifier of the compound widget's top-level base.
2998 (The first child of the parent widget.) No parameters.
2999
3000 GetLabelSize -- Returns the X screen size of the label widget. No parameters.
3001
3002 GetTextID -- Returns the widget identifier of the compound widget's text widget.
3003 No parameters.
3004
3005 GetTextSize -- Returns the X screen size of the text widget. No parameters.
3006
3007 PRIVATE OBJECT METHODS:
3008
3009 Although there is really no such thing as a "private" method in IDL's
3010 object implementation, some methods are used internally and not meant to
3011 be acessed publicly. Here are a few of those methods. I list them because
3012 it may be these private methods are ones you wish to override in subclassed
3013 objects.
3014
3015 MoveTab -- This method moves the focus to the widget identified in the "next" field,
3016 which must be set with the SetTabNext method. No parameters. Called automatically
3017 when a TAB character is typed in the text widget.
3018
3019 Text_Events -- The main event handler method for the compound widget. All
3020 text widget events are processed here.
3021
3022 ReturnValue -- This function method accepts a string input value and converts
3023 it to the type of data requested by the user.
3024
3025 Validate -- This function method examines all text input and removes unwanted
3026 characters, depending upon the requested data type for the field. It makes it
3027 impossible, for example, to type alphanumeric characters in an INTEGER field.
3028
3029 EXAMPLE:
3030
3031 An example program is provided at the end of the FSC_FIELD code. To run it,
3032 type these commands:
3033
3034 IDL> .Compile FSC_Field
3035 IDL> Example
3036
3037 MODIFICATION HISTORY:
3038
3039 Written by: David W. Fanning, 18 October 2000. Based heavily on an earlier
3040 FSC_INPUTFIELD program and new ideas about the best way to write
3041 widget objects.
3042 Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
3043 Modified the way the value is returned in the GET_VALUE method and the
3044 GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
3045 Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
3046 methods. 19 Jan 2001. DWF.
3047 Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
3048 Added GetTextSize and GetLabelSize methods for obtaining the X screen
3049 size of the text and label widgets, respectively. 21 July 2001. DWF.
3050 Fixed a problem in SetProperty method where I was setting self.xsize, which doesn't exist. 24 April 2002. DWF.
3051 Small modification to the SetEdit method. 6 August 2003. DWF.
3052 Added Highlight keyword. Ported Focus_Events keyword from
3053 fsc_inputfield.pro. Updated documentation. 17 November
3054 2004. DWF and Benjamin Hornberger
3055 Added Has_Focus keyword to the GetProperty method. 18 November
3056 2004. Benjamin Hornberger
3057 Fixed bug in GetProperty method (set value to *self.undefined if
3058 *self.value is undefined. 24 Feb 2004. Benjamin Hornberger
3059 Modified FOCUS_EVENTS keyword handling so that *all* focus events are now
3060 passed to specified event handlers. Check event.select to see if the
3061 widget is gaining or losing focus. 10 August 2005. DWF.
3062 Added new tabbing functionality, introduced in IDL 6.2. To use tabbing
3063 functionality natually, the HIGHTLIGHT keywords must be set.
3064 See included EXAMPLE program for details. 10 August 2005. DWF.
3065 Added functionality to covert double precision values to strings properly. 30 Nov 2005. DWF.
3066 Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
3067 Fixed a problem with validating a float or double value when it was written with
3068 exponential notation. 2 April 2010. DWF.
3069 </PRE><P>
3070 <STRONG>(See fsc_field.pro)</STRONG><P>
3071 <HR>
3072
3073 <A NAME="FSC_FILESELECT">
3074 <H2>FSC_FILESELECT</H2></A>
3075 <A HREF="#FSC_FIELD">[Previous Routine]</A>
3076 <A HREF="#FSC_INPUTFIELD">[Next Routine]</A>
3077 <A HREF="#ROUTINELIST">[List of Routines]</A>
3078 <PRE>
3079 NAME:
3080 FSC_FILESELECT
3081
3082 PURPOSE:
3083
3084 The purpose of this compound widget is to provide a means
3085 by which the user can type or select a file name. The
3086 program is written as an "object widget", meaning that
3087 the guts of the program is an object of class FSC_FILESELECT.
3088 This is meant to be an example of the obvious advantages of
3089 writing compound widget programs as objects.
3090
3091 AUTHOR:
3092
3093 FANNING SOFTWARE CONSULTING
3094 David Fanning, Ph.D.
3095 1645 Sheely Drive
3096 Fort Collins, CO 80526 USA
3097 Phone: 970-221-0438
3098 E-mail: [email protected]
3099 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
3100
3101 CATEGORY:
3102
3103 General programming.
3104
3105 CALLING SEQUENCE:
3106
3107 filenameID = FSC_FileSelect(parent)
3108
3109 INPUT PARAMETERS:
3110
3111 parent -- The parent widget ID of the compound widget. Required.
3112
3113 INPUT KEYWORDS:
3114
3115 Event_Pro -- The event handler procedure for this compound widget.By default: "".
3116 Event_Func -- The event handler function for this compound widget. By default: "".
3117
3118 If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.
3119
3120 DirectoryName -- The initial name of the directory. By defaut: current directory.
3121 Filename -- The initial file name in the filename text widget.
3122 Filter -- The file filter. By default: "*".
3123 Frame -- Set this keyword for a frame around the compound widget.
3124 LabelFont -- The font for the label widget. By default: "".
3125 LabelName -- The text on the label widgt. By default: "Filename: ".
3126 LabelSize -- The X screen size of the label widget. By default: 0.
3127 MustExist -- A flag that indicates selected files must exist. By default: 0.
3128 NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.
3129
3130 If this keyword is not set, the compound widget will automatically resize itself to
3131 the largest widget in its parent base widget. It will do this by changing the size of
3132 the text widgets holding the file and directory names.
3133
3134 Read -- Set this keyword to have file selection for reading a file. By default: 1.
3135 SelectDirectory -- The default directory for file selection. In other words, this is the
3136 default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
3137 SelectFont -- The font for the "Browse" button. By default: "".
3138 SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
3139 TextFont -- The font for the filename text widget. By default: "".
3140 UValue -- User value for any purpose.
3141 Write -- Set this keyword to open a file for writing. By default: 0.
3142 XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.
3143
3144 OUTPUT KEYWORDS:
3145
3146 ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
3147 With the object reference you can call object methods to easily change many properties of
3148 the compound widget.
3149
3150 COMMON BLOCKS:
3151
3152 None.
3153
3154 EVENT STRUCTURE:
3155
3156 All events are handled internally unless either the Event_Pro or Event_Func
3157 keywords are used to assign an event handler to the compound widget. All events
3158 generated by the text widgets are passed to the assigned event handler.
3159
3160 event = { CW_FILESELECT, $ ; The name of the event structure.
3161 ID: 0L, $ ; The ID of the compound widget's top-level base.
3162 TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
3163 HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
3164 Basename: "", $ ; The base filename without directory specifiers.
3165 Filename: "", $ ; The fully qualified filename.
3166 Directory: "", $ ; The name of the current file directory.
3167 }
3168
3169 EXAMPLE:
3170
3171 An example program is provided at the end of the FSC_FILESELECT code. To run it,
3172 type these commands:
3173
3174 IDL> .Compile fsc_fileselect
3175 IDL> Example
3176
3177 Or, if you want to obtain the object reference, type this:
3178
3179 IDL> Example, theObject
3180
3181 Now you can call the object's methods. For example:
3182
3183 IDL theObject->SetProperty, XSize=150
3184
3185 GETTING and SETTING VALUES:
3186
3187 So as not to disrupt the accepted paradigm in using compound widgets, you
3188 can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
3189 get and set the "value" of the widget.
3190
3191 Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'
3192
3193 The program will automatically separate the file name portion of the value
3194 from the directory portion and put things in the correct text widgets.
3195
3196 Similarly, you can get the "value" of the widget:
3197
3198 Widget_Control, filenameID, Get_Value=theValue
3199 Print, theValue
3200
3201 C:\RSI\IDL52\DATA\cyclone.dat
3202
3203 The return value is the fully qualified file path to the file.
3204
3205 USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES:
3206
3207 If you obtain the object reference, you have a great deal more control
3208 over the properties of the compound widget. You obtain the object reference
3209 by calling the function like this:
3210
3211 filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)
3212
3213 OBJECT PROCEDURE METHODS:
3214
3215 GetProperty -- This method allows various properties of the widget to be
3216 returned via output keywords. The keywords that are available are:
3217
3218 DirectoryName -- The current directory.
3219 Event_Func -- The name of the event handler function for this compound widget.
3220 Event_Pro -- The name of the event handler procedure for this compound widget.
3221 Filename -- The current base filename.
3222 Filter -- The current file filter.
3223 LabelName -- The text on the label widget.
3224 LabelSize -- The X screen size of the label widget.
3225 MustExist -- A flag that indicates selected files must exist to be selected.
3226 Parent -- The parent widget of the compound widget.
3227 Read=read -- The file selection for reading flag.
3228 SelectTitle -- The title bar text on the file selection dialog.
3229 TLB -- The top-level base of the compound widget.
3230 UValue -- The user value of the compound widget.
3231 Write -- The file selection for writing flag.
3232 XSize -- The X size of the text widget holding the filename.
3233
3234 LabelSize -- This method makes sure that the directory name and file name labels
3235 are the same size. Normally, this procedure is called internally. No parameters.
3236
3237 MatchSize -- This method resizes the compound widget so that it is as long as the
3238 the longest widget in the parent base widget. This is done automatically upon
3239 realization unless the NOMAXSIZE keyword is set. The method aids in writing
3240 resizeable widget programs.
3241
3242 SetProperty -- This method allows various properties of the widget to be
3243 set via input keywords. The keywords that are available are:
3244
3245 DirectoryName -- The current directory.
3246 Event_Func -- The name of the event handler function for this compound widget.
3247 Event_Pro -- The name of the event handler procedure for this compound widget.
3248 Filename -- The current base filename.
3249 Filter -- The current file filter.
3250 LabelName -- The text on the label widget.
3251 LabelSize -- The X screen size of the label widget.
3252 MustExist -- A flag that indicates selected files must exist to be selected.
3253 Read -- The file selection for reading flag.
3254 SelectTitle -- The title bar text on the file selection dialog.
3255 UValue -- The user value of the compound widget.
3256 Write -- The file selection for writing flag.
3257 XSize -- The X size of the text widget holding the filename.
3258
3259 TextSelect - Allows you to create a selection in filename text widget. See the
3260 documentation for the SET_TEXT_SELECT keyword to Widget_Control.
3261
3262 selection -- A two-element array containing the starting position and selection length.
3263
3264 OBJECT FUNCTION METHODS:
3265
3266 GetFileName -- Returns the fully qualified filename. No parameters.
3267
3268 GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.
3269
3270 Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.
3271
3272 directoryName -- The name of the directory from the directory text widget.
3273 textSelection -- The current text selection position.
3274
3275 At the moment all this does is remove any blank characters from either
3276 end of the directory name and makes sure the last character of the directory
3277 name does not end in a subdirectory specifier (except for VMS).
3278
3279 Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.
3280
3281 filename -- The name of the file from the filename text widget.
3282 textSelection -- The current text selection position.
3283
3284 At the moment all this does is remove any blank characters from either
3285 end of the file name
3286
3287 MODIFICATION HISTORY:
3288
3289 Written by: David W. Fanning, 21 NOV 1999.
3290 Fixed bug in File Name selection button. 18 MAR 2000. DWF.
3291 Fixed an error in which directory the Browse buttons should start
3292 searching. 29 SEP 2000. DWF.
3293 Previously returned events only for typing in text widgets. Now
3294 Browse button events are also returned. 29 SEP 2000. DWF.
3295 Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
3296 Removed the Directory Browse button 10 AUG 2002. DWF.
3297 Added cgErrorMsg to error handling. 10 AUG 2002. DWF.
3298 Changed the ability to specify a file filter as a string array, instead
3299 of just as a scalar string. This required the use of a pointer, which
3300 meant that I had to remove the FILTER field from the CW_FILESELECT
3301 event structure to avoid likely memory leakage. This is a dangerous
3302 change because it means programs that relied on this (I expect there
3303 are very, very few) will break and it goes against my philosopy of
3304 keeping my programs backward compatible. Let me know if you have
3305 problems. In testing, I discoved no problems in my own code. 31 OCT 2002. DWF.
3306 Fixed a problem with DIALOG_PICKFILE that sometimes allowed users to change
3307 directories without selecting a file. 3 Nov 2002. DWF.
3308 Fixed a problem with widget resizing with the help of Bob Portman that had plagued
3309 me from the beginning. Thanks, Bob! 5 August 2003. DWF
3310 Added TEXTSELECT method. 5 Aug 2003. DWF.
3311 Had to add FORWARD_FUNCTION statement to get error handler compiled when using
3312 DIRECTORY keyword. 24 Nov 2003. DWF.
3313 Fixed a problem with too many events going to an event handler specified with
3314 the EVENT_PRO or EVENT_FUNC keyword from the text widget. Now only Carriage
3315 Return events are passed on to the user-specified event handler. 8 July 2004. DWF.
3316 Replace all "\" characters with "/" characters in directory names. 8 Januay 2006. DWF.
3317 Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
3318 </PRE><P>
3319 <STRONG>(See fsc_fileselect.pro)</STRONG><P>
3320 <HR>
3321
3322 <A NAME="FSC_INPUTFIELD">
3323 <H2>FSC_INPUTFIELD</H2></A>
3324 <A HREF="#FSC_FILESELECT">[Previous Routine]</A>
3325 <A HREF="#FSC_PLOTWINDOW">[Next Routine]</A>
3326 <A HREF="#ROUTINELIST">[List of Routines]</A>
3327 <PRE>
3328 NAME:
3329 FSC_INPUTFIELD
3330
3331 PURPOSE:
3332
3333 The purpose of this compound widget is to provide an alternative
3334 to the CW_FIELD widget offered in the IDL distribution. What has
3335 always bothered me about CW_FIELD is that the text widgets do not
3336 look editable to the users on Windows platforms. This program
3337 corrects that deficiency and adds some features that I think
3338 would be helpful. For example, you can now assign an event handler
3339 to the compound widget. The program is written entirely as an object.
3340 A companion program, COYOTE_FIELD, has much the same functionality,
3341 but is written as a traditional compound widget. The point of writing
3342 the same program in two different ways is to give you the opportunity
3343 to compare and contrast the two methods. I personally think there
3344 is no substitute for the power of object programs. :-)
3345
3346 AUTHOR:
3347 FANNING SOFTWARE CONSULTING
3348 David Fanning, Ph.D.
3349 1645 Sheely Drive
3350 Fort Collins, CO 80526 USA
3351 Phone: 970-221-0438
3352 E-mail: [email protected]
3353 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
3354
3355 CATEGORY:
3356
3357 General programming.
3358
3359 CALLING SEQUENCE:
3360
3361 objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue)
3362
3363 INPUT PARAMETERS:
3364
3365 parent -- The parent widget ID of the compound widget. Required.
3366
3367 INPUT KEYWORDS:
3368
3369 Column -- Set this keyword to have the Label Widget above the Text Widget.
3370 CR_Only -- Set this keyword if you only want Carriage Return events. Note that no
3371 events are returned unless the EVENT_PRO or EVENT_FUNC keywords are also used.
3372 Decimal -- Set this keyword to the number of digits to the right of the decimal
3373 point in FLOATVALUE and DOUBLEVALUE numbers.
3374 Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
3375 DoubleValue -- Set this keyword if you want DOUBLE values returned.
3376 Event_Func -- Set this keyword to the name of an Event Function. If this
3377 keyword is undefined and the Event_Pro keyword is undefined,
3378 all compound widget events are handled internally and not
3379 passed on to the parent widget.
3380 Event_Pro -- Set this keyword to the name of an Event Procedure. If this
3381 keyword is undefined and the Event_Func keyword is undefined,
3382 all compound widget events are handled internally and not
3383 passed on to the parent widget.
3384 FieldFont -- The font name for the text in the Text Widget.
3385 FloatValue -- Set this keyword for FLOAT values.
3386 Focus_Events -- Set this keyword if you only want text events when the keyboard focus is
3387 moved out of the text widget. Note that no events are returned unless the
3388 EVENT_PRO or EVENT_FUNC keywords are also used.
3389 Frame -- Set this keyword to put a frame around the compound widget.
3390 IntegerValue -- Set this keyword for INTEGER values.
3391 LabelAlign -- Set this keyword to align label text. [0-center (default), 1-left, 2-right].
3392 LabelFont -- The font name for the text in the Label Widget.
3393 LabelSize -- The X screen size of the Label Widget.
3394 LongValue -- Set this keyword for LONG values.
3395 Name -- A scalar string name of the object. (default = '')
3396 Positive -- Set this keyword if you want only positive numbers allowed.
3397 Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
3398 Scr_XSize -- The X screen size of the compound widget.
3399 Scr_YSize -- The Y screen size of the compound widget.
3400 StringValue -- Set this keyword for STRING values. (The default.)
3401 Title -- The text to go on the Label Widget.
3402 UValue -- A user value for any purpose.
3403 Value -- The "value" of the compound widget.
3404 XSize -- The X size of the Text Widget.
3405
3406 In addition, any keyword defined for WIDGET_TEXT, but not defined here (e.g., SENSITIVE), is
3407 passed along without inspection to the text widget. Use of "extra" keywords is discouraged.
3408
3409 COMMON BLOCKS:
3410
3411 None.
3412
3413 RESTRICTIONS:
3414
3415 None.
3416
3417 EVENT STRUCTURE:
3418
3419 All events are handled internally unless either the Event_Pro or Event_Func
3420 keywords are used to assign an event handler to the compound widget. By
3421 default all events generated by the text widget are passed to the assigned
3422 event handler. If you wish to receive only Carriage Return events, set the
3423 CR_Only keyword.
3424
3425 event = { FSC_INPUTFIELD_EVENTS, $ ; The name of the event structure.
3426 ID: 0L, $ ; The ID of the compound widget's top-level base.
3427 TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
3428 HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
3429 ObjRef: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
3430 Value: Ptr_New(), $ ; A pointer to the widget value.
3431 Type:"" ; A string indicating the type of data in the VALUE field.
3432 } ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".
3433
3434 GETTING and SETTING VALUES:
3435
3436 Almost all the properties of the widget can be obtained or set via
3437 the object's GetProperty and SetProperty methods (described below).
3438 But since traditional compound widgets have the ability to get and
3439 set the value of the compound widget, this capability is implemented
3440 as special methods.
3441
3442 To get the value of the field, do this: value = objectRef->Get_Value()
3443 To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue
3444
3445 The proper keyword should be used to set the data type of the value. If a keyword
3446 is not used, the data type is determined from the value itself.
3447
3448 OBJECT PROCEDURE METHODS:
3449
3450 GetProperty -- This method allows various properties of the widget to be
3451 returned via output keywords. The keywords that are available are:
3452
3453 CR_Only -- A flag, if set, means only report carriage return events.
3454 DataType -- The data type of the field variable.
3455 Decimal -- Set this keyword to the number of digits to the right of the decimal
3456 point in FLOATVALUE and DOUBLEVALUE numbers.
3457 Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
3458 Event_Func -- The name of the event handler function.
3459 Event_Pro -- The name of the event handler function.
3460 Positive -- Indicates if the Positive number flag is set (1) or not (0).
3461 UValue -- The user value assigned to the compound widget.
3462 Value -- The "value" of the compound widget.
3463 Name -- A scalar string name of the object.
3464
3465 Resize -- This method allows you to resize the compound widget's text field.
3466 The value parameter is an X screen size for the entire widget. The text
3467 widget is sized by using the value obtained from this value minus the
3468 X screen size of the label widget.
3469
3470 objectRef->Resize, screen_xsize_value
3471
3472 Set_Value -- This method allows you to set the "value" of the field. It takes
3473 one positional parameter, which is the value.
3474
3475 objectRef->Set_Value, 5
3476
3477 Keywords available are these to set the type of the data. If keywords
3478 are not used, the data type is determined from the value.
3479
3480 DoubleValue -- Set this keyword if you want DOUBLE values returned.
3481 FloatValue -- Set this keyword for FLOAT values.
3482 IntegerValue -- Set this keyword for INTEGER values.
3483 LongValue -- Set this keyword for LONG values.
3484 StringValue -- Set this keyword for STRING values. (The default.)
3485
3486 SetProperty -- This method allows various properties of the widget to be
3487 set via input keywords. The keywords that are available are:
3488
3489 CR_Only -- Set this keyword if you only want Carriage Return events.
3490 Decimal -- Set this keyword to the number of digits to the right of the decimal
3491 point in FLOATVALUE and DOUBLEVALUE numbers.
3492 Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
3493 DoubleValue -- Set this keyword if you want DOUBLE values returned.
3494 Event_Func -- Set this keyword to the name of an Event Function.
3495 Event_Pro -- Set this keyword to the name of an Event Procedure.
3496 FloatValue -- Set this keyword for FLOAT values.
3497 IntegerValue -- Set this keyword for INTEGER values.
3498 LabelSize -- The X screen size of the Label Widget.
3499 LongValue -- Set this keyword for LONG values.
3500 Name -- A scalar string name of the object. (default = '')
3501 Positive -- Set this keyword to indicate only positive numbers are allowed.
3502 Scr_XSize -- The X screen size of the text widget.
3503 Scr_YSize -- The Y screen size of the text widget.
3504 Sensitive -- Set to 1 to make the widget sensitive, and to 0 to make it insensitive.
3505 StringValue -- Set this keyword for STRING values. (The default.)
3506 Title -- The text to go on the Label Widget.
3507 UValue -- A user value for any purpose.
3508 Value -- The "value" of the compound widget.
3509 XSize -- The X size of the Text Widget.
3510
3511 SetTabNext -- This method allows you to specify which field to go to when a TAB character
3512 is typed in the text widget. See the Example program below for an example of how to
3513 use this method.
3514
3515 OBJECT FUNCTIONS METHODS:
3516
3517 Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
3518 if a "number" field is blank. Should be checked before using:
3519
3520 IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
3521
3522 GetID -- Returns the widget identifier of the compound widget's top-level base.
3523 (The first child of the parent widget.) No parameters.
3524
3525 GetLabelSize -- Returns the X screen size of the label widget. No parameters.
3526
3527 GetTextID -- Returns the widget identifier of the compound widget's text widget.
3528 No parameters.
3529
3530 GetTextSize -- Returns the X screen size of the text widget. No parameters.
3531
3532 PRIVATE OBJECT METHODS:
3533
3534 Although there is really no such thing as a "private" method in IDL's
3535 object implementation, some methods are used internally and not meant to
3536 be acessed publicly. Here are a few of those methods. I list them because
3537 it may be these private methods are ones you wish to override in subclassed
3538 objects.
3539
3540 MoveTab -- This method moves the focus to the widget identified in the "next" field,
3541 which must be set with the SetTabNext method. No parameters. Called automatically
3542 when a TAB character is typed in the text widget.
3543
3544 Text_Events -- The main event handler method for the compound widget. All
3545 text widget events are processed here.
3546
3547 ReturnValue -- This function method accepts a string input value and converts
3548 it to the type of data requested by the user.
3549
3550 Validate -- This function method examines all text input and removes unwanted
3551 characters, depending upon the requested data type for the field. It makes it
3552 impossible, for example, to type alphanumeric characters in an INTEGER field.
3553
3554 EXAMPLE:
3555
3556 An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
3557 type these commands:
3558
3559 IDL> .Compile FSC_InputField
3560 IDL> Example
3561
3562 NOTES:
3563
3564 IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
3565 is now supported, but FOCUS_EVENTS *must* be set on the widget for the new TAB events to
3566 behave properly. See the EXAMPLE program for examples.
3567
3568 DEPENDENCIES:
3569
3570 Requires cgDblToStr from the Coyote Library:
3571 http://www.idlcoyote.com/programs/cgdbltostr.pro
3572
3573 MODIFICATION HISTORY:
3574
3575 Written by: David W. Fanning, 23 NOV 1999.
3576 Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
3577 Changed the calling sequence to that of a function rather than an object
3578 creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
3579 Added GetID and Resize methods. 7 Jan 00. DWF.
3580 Added the Positive keyword and functionality. 12 Jan 00. DWF
3581 Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
3582 If a number field is blank, the Get_Value method will now return an undefined variable.
3583 Be sure you check this value before you use it for something! 17 Jan 00. DWF.
3584 Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
3585 Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
3586 MoveTab, and GetTextID methods. 31 July 2000. DWF.
3587 Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
3588 Added ObjRef field to the FSC_FIELD event structure and added field selection
3589 for the TAB events added 31 July. 7 AUG 2000. DWF
3590 Added GetTextSize and GetLabelSize methods for obtaining the X screen
3591 size of the text and label widgets, respectively. 30 Jan 2001. DWF.
3592 Added FOCUS_EVENTS keyword and fixed a problem with the event structure.
3593 Also added better error handling. 5 January 2003. DWF.
3594 Fixed a small problem in which input values were cast to strings inadvertently. 9 January 2004. DWF.
3595 Fixed a small problem with error messages and using EVENT_FUNC. 14 January 2004. DWF.
3596 Fixed a problem when setting ROW keyword. 23 February 2004. DWF.
3597 IDL 6.2 introduced new TAB behavior, which broke the previous TAB behavior. New TAB behavior
3598 is now supported, but FOCUS_EVENTS *must* be set for the new TAB events to behave properly.
3599 10 August 2005. DWF.
3600 Modified to covert double precision values to strings properly. 30 November 2005. DWF.
3601 Added POSITIVE keyword to SETPROPERTY and GETPROPERTY methods. 25 February 2006. DWF.
3602 Set the DYNAMIC_RESIZE keyword on the label widget. 25 February 2006. DWF.
3603 Added SENSITIVE keyword to SetProperty documentation. 10 November 2006. DWF.
3604 Fixed a small problem in which doubles were not being initialized correctly due
3605 to an inadvertant extra line of code. 3 July 2007. DWF.
3606 Fixed a small problem with input validation when the input is of BYTE type. 1 Oct 2008. DWF.
3607 Set the default fonts to be the current widget font, rather than the default widget font. 4 Oct 2008. DWF.
3608 Fixed a problem with validating a float or double value when it was written with
3609 exponential notation. 2 April 2010. DWF.
3610 </PRE><P>
3611 <STRONG>(See fsc_inputfield.pro)</STRONG><P>
3612 <HR>
3613
3614 <A NAME="FSC_PLOTWINDOW">
3615 <H2>FSC_PLOTWINDOW</H2></A>
3616 <A HREF="#FSC_INPUTFIELD">[Previous Routine]</A>
3617 <A HREF="#FSC_PSCONFIG__DEFINE">[Next Routine]</A>
3618 <A HREF="#ROUTINELIST">[List of Routines]</A>
3619 <PRE>
3620 NAME:
3621 FSC_PLOTWINDOW
3622
3623 PURPOSE:
3624
3625 The purpose of this compound widget is to create a resizeable
3626 "plot window" inside a larger "page window". I'm not sure it
3627 has any value except as a utility routine for the PostScript
3628 configuration object FSC_PSCONFIG__DEFINE, but it's a neat
3629 program anyway. :-)
3630
3631 AUTHOR:
3632
3633 FANNING SOFTWARE CONSULTING
3634 David Fanning, Ph.D.
3635 1645 Sheely Drive
3636 Fort Collins, CO 80526 USA
3637 Phone: 970-221-0438
3638 E-mail: [email protected]
3639 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
3640
3641 CATEGORY:
3642
3643 Utility routine for FSC_PSCONFIG__DEFINE.
3644
3645 CALLING SEQUENCE:
3646
3647 plotwindowObject = CW_PlotWindow(parent)
3648
3649 REQUIRED INPUT PARAMETERS:
3650
3651 parent - The parent base widget of this compound widget.
3652
3653 RETURN VALUE:
3654
3655 plotwindowObject - The object reference of the compound widget.
3656
3657 KEYWORDS:
3658
3659 COLOR - If set, display the window in "color". This is the default on 24-bit devices.
3660 DEBUG - Set this keyword to turn traceback error handling on in the error handling code.
3661 EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally.
3662 LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode.
3663 PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY".
3664 UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "".
3665 UVALUE - A user value for the caller of this program.
3666 WINDOWCOLOR - A three-element array specifying the background window color (RGB).
3667 WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1].
3668
3669 EVENT STRUCTURE:
3670
3671 The event structure that is returned from this compound widget is defined like this,
3672 where the sizes and offsets locate the target "window" on the page in normalized units:
3673
3674 event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0}
3675
3676 MODIFICATIONS:
3677
3678 Written by David Fanning, 31 January 2000.
3679 Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF.
3680 Added a "DISPLAY" page size, so the program can be used to position
3681 plots and other graphics in a display window. The "page area" will
3682 have the same aspect ratio is the current graphics window. 17 March 2001. DWF.
3683 Changed some of the tolerances for "closeness" from 0.1 to 0.025 to allow smaller
3684 sizing for colorbars and other small objects. 6 July 2005. DWF.
3685 </PRE><P>
3686 <STRONG>(See fsc_plotwindow.pro)</STRONG><P>
3687 <HR>
3688
3689 <A NAME="FSC_PSCONFIG__DEFINE">
3690 <H2>FSC_PSCONFIG__DEFINE</H2></A>
3691 <A HREF="#FSC_PLOTWINDOW">[Previous Routine]</A>
3692 <A HREF="#GAUSSSCL">[Next Routine]</A>
3693 <A HREF="#ROUTINELIST">[List of Routines]</A>
3694 <PRE>
3695 NAME:
3696 FSC_PSCONFIG__DEFINE
3697
3698 PURPOSE:
3699
3700 The purpose of this program is to implement an object that
3701 can keep track of--and allow the user to change--the current
3702 configuration of the PostScript device.
3703
3704 AUTHOR:
3705
3706 FANNING SOFTWARE CONSULTING
3707 David Fanning, Ph.D.
3708 1645 Sheely Drive
3709 Fort Collins, CO 80526 USA
3710 Phone: 970-221-0438
3711 E-mail: [email protected]
3712 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
3713
3714 CATEGORY:
3715
3716 General programming.
3717
3718 DOCUMENTATION:
3719
3720 Complete documentation for the FSC_PSCONFIG object, including
3721 keyword and method descriptions, and example programs using the object
3722 can be found on the Coyote's Guide to IDL Programming web page:
3723
3724 http://www.idlcoyote.com/programs/docs/fsc_psconfig.html
3725
3726 Or, if you would prefer, you can download a self-contained PDF file:
3727
3728 http://www.idlcoyote.com/programs/docs/fsc_psconfig.pdf
3729
3730 KEYWORDS:
3731
3732 Any keyword accepted by the FSC_PSCONFIG object can be used with
3733 this program. Here are a few of the most popular keywords.
3734
3735 Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
3736 Color - Set this keyword to select Color PostScript output. Turned on by default.
3737 Decomposed - Set this keyword to 0 to select indexed color and to 1 to select decomposed color.
3738 DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
3739 create and add your own to the source code) are the following:
3740
3741 "System (Portrait)" - The normal "default" system set-up. Also, "System".
3742 "System (Landscape)" - The normal "default" landscape system set-up.
3743 "Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
3744 "Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
3745 "Square (Portrait)" - A square plot, centered on the page.
3746 "Square (Landscape)" - A square plot, centered on the landscape page.
3747 "Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
3748 "Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
3749 "Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
3750 "Color (Landscape)" - A "centered" landscape plot, with color turned on.
3751
3752 Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
3753 Encapsulated - Set this keyword to select Encapsulated PostScript output. Turned off by default.
3754 European - This keyword has been depreciated in favor of METRIC.
3755 Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
3756 Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by Metric keyword by default.
3757 Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
3758 Language_Level - Set this keyword to select the Language Level interpreter. Default is 1.
3759 Metric - Set this keyword to indicate metric mode (i.e., A4 page and centimeter units). Turned off by default.
3760 PageType - Set this keyword to the "type" of page. Possible values are:
3761 "Letter" - 8.5 by 11 inches. (Default, unless the Metric keyword is set.)
3762 "Legal" - 8.5 by 14 inches.
3763 "Ledger" - 11 by 17 inches.
3764 "A4" - 21.0 by 29.7 centimeters. (Default, if the Metric keyword is set.)
3765 XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
3766 XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
3767 YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
3768 YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.
3769
3770 In addition, the following keywords can be used:
3771
3772 CANCEL -- An output keyword that will be set to 1 if the user
3773 chooses the Cancel button on the form. It will be 0 otherwise.
3774
3775 FONTINFO -- Set this keyword is you wish to have font information
3776 appear on the form. The default is to not include font information.
3777
3778 FONTTYPE -- Set this keyword to a named variable that will indicate
3779 the user's preference for font type. Values will be -1 (Hershey fonts),
3780 0 (hardware fonts), and 1 (true-type fonts). This keyword will always
3781 return -1 unless the FONTINFO keyword has also been set.
3782
3783 GROUP_LEADER -- Set this keyword to a widget identifier of the widget
3784 you wish to be a group leader for this program.
3785
3786 EXAMPLE:
3787
3788 A simple sequence of using the object would look something like this:
3789
3790 psObject = Obj_New("FSC_PSCONFIG")
3791 psObject->GUI
3792 psKeywords = psObject->GetKeywords()
3793 thisDevice = !D.Name
3794 Set_Plot, 'PS'
3795 Device, _Extra=psKeywords
3796 cgImage, image
3797 Device, /Close_File
3798 Set_Plot, thisDevice
3799 Obj_Destroy, psObject
3800
3801 Note that the object can also be called from the cgPS_Config interface:
3802
3803 psKeywords = cgPS_Config()
3804
3805 OTHER PROGRAMS NEEDED:
3806
3807 The following programs are required to run this one:
3808
3809 fsc_droplist.pro
3810 fsc_fileselect.pro
3811 fsc_field.pro
3812 fsc_plotwindow
3813
3814 MODIFICATIONS:
3815
3816 Written by David W. Fanning, 31 January 2000.
3817 Added capability to call GUI methods when the current graphics device
3818 doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF.
3819 Changed the default value for the Color keyword to 1. 16 May 2000. DWF.
3820 Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF.
3821 Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF.
3822 Added the ability to Get and Set the object's name via the SetProperty
3823 and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF.
3824 Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF.
3825 Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF.
3826 Fixed a bug when setting file and directory names with the SetProperty method. 18 Dec 2000. DWF.
3827 Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF.
3828 Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF.
3829 Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF.
3830 Increased the length of the file/directory name fields. 7 Jan 2001. DWF.
3831 Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF.
3832 Seems I only half fixed the previous problem. :-( 26 April 2001. DWF.
3833 Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF.
3834 Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF.
3835 Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF.
3836 Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF.
3837 Fixed a small problem in not setting new page sizes appropriately. 22 May 2002. DWF.
3838 Fixed a problem that occurred when the Accept button was not named "Accept". 6 May 2003.DWF.
3839 Whoops! I was a bit overly agressive on that last fix. :-( 17 July 2003. DWF.
3840 Fixed a problem with setting page types when using the DEFAULTSETUP keyword. 31 July 2003. DWF.
3841 Fixed a problem with turning encapsulation on in the GUI. Renamed ENCAPSULATE keyword ENCAPSULATED
3842 to avoid obvious errors. 31 July 2003. DWF.
3843 Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
3844 Now honoring EUROPEAN keyword when setting system default setups in the INIT method. 12 Nov 2004. DWF.
3845 Added CMYK output option 24 August 2007. Assumes LANGUAGE_LEVEL=2 printer. L. Anderson.
3846 Fixed a problem with the filename on WINDOWS computers coming back with forward slashes instead of
3847 backward slashes. 20 May 2008. DWF.
3848 Modified the program to return as the default, ISOLATIN1=1. 18 July 2008. DWF.
3849 Fixed a problem with filenames when a DEFAULTSETUP was used with it. 12 Nov 2008. DWF.
3850 Changed default window size when LANDSCAPE keyword is set. 10 April 2009. DWF.
3851 Changed the default window size for PORTRAIT mode to be a bit larger. 10 April 2009. DWF.
3852 Updated for IDL 7.1 and 24-bit color PostScript support. 24 May 2009. DWF.
3853 Added PAGETYPE field to returned structure to allow PostScript page type to be determined. 8 August 2009. DWF.
3854 Fixed a problem with 24-bit color support that allowed only IDL 7 versions to work correctly. 20 Sept 2009. DWF.
3855 Added a LANGUAGE_LEVEL keyword. 13 Dec 2010. DWF.
3856 Added the FONTYPE value to the keyword return structure. 14 Dec 2010. DWF.
3857 Modified the return structure to turn landscape mode off and set offsets to zero if in
3858 encapsulated mode. 19 Feb 2011. DWF.
3859 Changes to handle inability to create raster files from PS encapsulated files in
3860 landscape mode. Also removed changes of 19 Feb 2011 as no longer needed. 26 Aug 2011. DWF.
3861 The PAGETYPE was not getting set properly in the return keywords when the Metric
3862 option was selected on the GUI. 12 October 2011. DWF.
3863 The program now remembers the last directory you used and will start in that
3864 directory, unless told otherwise. 26 Oct 2011. DWF.
3865 Parsing of full filename failing. Fixed 27 Oct 2011. DWF.
3866 </PRE><P>
3867 <STRONG>(See fsc_psconfig__define.pro)</STRONG><P>
3868 <HR>
3869
3870 <A NAME="GAUSSSCL">
3871 <H2>GAUSSSCL</H2></A>
3872 <A HREF="#FSC_PSCONFIG__DEFINE">[Previous Routine]</A>
3873 <A HREF="#GETIMAGE">[Next Routine]</A>
3874 <A HREF="#ROUTINELIST">[List of Routines]</A>
3875 <PRE>
3876 NAME:
3877 GAUSSSCL
3878
3879 PURPOSE:
3880
3881 This is a utility routine to perform a gaussian gray-level pixel
3882 transformation stretch on a image.
3883
3884 AUTHOR:
3885
3886 FANNING SOFTWARE CONSULTING
3887 David Fanning, Ph.D.
3888 1645 Sheely Drive
3889 Fort Collins, CO 80526 USA
3890 Phone: 970-221-0438
3891 E-mail: [email protected]
3892 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
3893
3894 CATEGORY:
3895
3896 Utilities
3897
3898 CALLING SEQUENCE:
3899
3900 scaledImage = GAUSSSCL(image)
3901
3902 ARGUMENTS:
3903
3904 image: The image to be scaled. Written for 2D images, but arrays
3905 of any size are treated alike.
3906
3907 KEYWORDS:
3908
3909 SIGMA: The sigma value or width of the Gaussian
3910 function. Set to 1 by default.
3911
3912
3913 MAX: Any value in the input image greater than this value is
3914 set to this value before scaling.
3915
3916 MIN: Any value in the input image less than this value is
3917 set to this value before scaling.
3918
3919 NEGATIVE: If set, the "negative" of the result is returned.
3920
3921 OMAX: The output image is scaled between OMIN and OMAX. The
3922 default value is 255.
3923
3924 OMIN: The output image is scaled between OMIN and OMAX. The
3925 default value is 0.
3926 RETURN VALUE:
3927
3928 scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
3929
3930 COMMON BLOCKS:
3931 None.
3932
3933 EXAMPLES:
3934
3935 LoadCT, 0 ; Gray-scale colors.
3936 image = cgDemoData(11) ; Load image.
3937 TV, GaussScl(image)
3938
3939 RESTRICTIONS:
3940
3941 Requires cgScaleVector from the Coyote Library:
3942
3943 http://www.idlcoyote.com/programs/cgScaleVector.pro
3944
3945 MODIFICATION HISTORY:
3946
3947 Written by: David W. Fanning, 5 September 2007.
3948 Now setting NAN keyword on all MIN and MAX functions. 2 Dec 2011. DWF.
3949 </PRE><P>
3950 <STRONG>(See gaussscl.pro)</STRONG><P>
3951 <HR>
3952
3953 <A NAME="GETIMAGE">
3954 <H2>GETIMAGE</H2></A>
3955 <A HREF="#GAUSSSCL">[Previous Routine]</A>
3956 <A HREF="#GETPRIMARYSCREENSIZE">[Next Routine]</A>
3957 <A HREF="#ROUTINELIST">[List of Routines]</A>
3958 <PRE>
3959 NAME:
3960 GETIMAGE
3961
3962 PURPOSE:
3963
3964 The purpose of this function is to allow the user to open either
3965 unformmated or XDR binary image files of up to eight dimensions.
3966
3967 CATEGORY:
3968
3969 Widgets, File I/O.
3970
3971 CALLING SEQUENCE:
3972
3973 image = GETIMAGE(filename)
3974
3975 OPTIONAL INPUTS:
3976
3977 filename: The name of the file to open for reading.
3978
3979 OPTIONAL KEYWORD PARAMETERS:
3980
3981 CANCEL: An output variable that can be set to a named variable.
3982 The value of the return variable will be 1 if the user clicked
3983 the "Cancel" button or if there was a problem reading the file.
3984
3985 DATATYPE: The "type" of data you wish to read out of the file.
3986 The data type corresponds to the Size(image, /TYPE) value. Here
3987 are the types supported:
3988
3989 BYTE 1 (default)
3990 INTEGER 2
3991 LONG INTEGER 3
3992 FLOAT 4
3993 DOUBLE 5
3994 UNSIGNED INTEGER 12
3995 UNSIGNED LONG INTEGER 13
3996 64-bit LONG 14
3997 64-bit UNSIGNED LONG 15
3998
3999
4000
4001 DIMENSIONS: A vector of image dimensions. The default value is [256, 256].
4002
4003 DIRECTORY: The name of the directory the file is located in. By
4004 default the program looks in the "coyote" directory under the
4005 main IDL directory, if one exists. Otherwise, it defaults to the
4006 current directory.
4007
4008 ENDIAN: Set this keyword to an integer that indicates the byte
4009 ordering of the data file. If you don't know what byte order means,
4010 or you don't know anything about the byte order of the data, or
4011 if you are sure the data was created on the same type of machine
4012 you are now running IDL on, then just accept the default of 0 or
4013 "native" ordering. If you are wrong, you will soon know it and you
4014 can set the keyword to another value on your next try. :-)
4015
4016 If you know the machine was created on a big endian machine (such
4017 as a Sun or HP workstation), set this value to 1 (Big Endian). If e
4018 you are sur the image data was create on a little endian machine (such
4019 as a Windows PC or laptop running LINUX), set the value to 2 (Little Endian).
4020
4021 HEADER: The size of any header information in the file in BYTES.
4022 Default is 0.
4023
4024 HEADDATA: An optional output keyword that will contain the header
4025 information read from the file.
4026
4027 PARENT: The group leader for this widget program. The PARENT is
4028 required if GETIMAGE is called from another widget program in order
4029 to make this program a MODAL widget program.
4030
4031 XDR: Set this keyword if the binary file is of XDR type. The default
4032 type is "Unformatted".
4033
4034 XOFFSET: This is the X offset of the program on the display. The
4035 program will be placed approximately in the middle of the display
4036 by default.
4037
4038 YOFFSET: This is the Y offset of the program on the display. The
4039 program will be placed approximately in the middle of the display
4040 by default.
4041
4042 COMMON BLOCKS:
4043
4044 None.
4045
4046 SIDE EFFECTS:
4047
4048 A "CANCEL" operation is indicated by a 0 return value.
4049 Any error in reading the file results in a 0 return value.
4050
4051 EXAMPLE:
4052 To load the image "galaxy.dat" in the $IDL/examples/data
4053 directory, type:
4054
4055 image = GETIMAGE('galaxy.dat', DIRECTORY=!DIR + '/examples/data', $
4056 DIMENSIONS=[256,256], Cancel=cancelled, Parent=event.top)
4057 IF NOT cancelled THEN TV, image
4058
4059 MODIFICATION HISTORY:
4060 Written by: David Fanning, 3 February 96.
4061 Fixed bug that prevented reading INTEGER data. 19 Dec 96.
4062 Modifed program for IDL 5 MODAL operation. 19 Oct 97.
4063 Added CANCEL keyword. 27 Oct 97. DWF.
4064 Fixed CANCLE keyword spelling. Sigh... 29 JUN 98. DWF.
4065 Added COYOTE_FIELD, improved appearance. 19 NOV 99. DWF.
4066 Updated with latest version of COYOTE_FIELD. 18 FEB 2000. DWF.
4067 Added CATCH keyword so the program will break when I want
4068 it to. :-) 18 MAR 2000. DWF.
4069 Added GROUP_LEADER keyword, which is synonymous with PARENT. 31 MAR 2000. DWF.
4070 Updated obsolete PICKFILE call to DIALOG_PICKFILE. 17 JAN 2001. DWF.
4071 Extensive update for IDL Programming Techniques, 3rd Edition. 1 November 2006. DWF.
4072 XSIZE, YSIZE, CATCH, and FRAMES keyword made obsolete.
4073 HEADDATA, ENDIAN, DATATYPE, DIMENSIONS keywords added.
4074 Added ability to parse fully qualified file names passed from Dialog_Pickfile. 30 Oct 2010. DWF.
4075 IF a file name is not passed into the program, it asks the user to select one now. 10 Jan 2011. DWF.
4076 Problem with SWAP_ENDIAN keywords fixed. 7 March 2011. DWF.
4077 </PRE><P>
4078 <STRONG>(See getimage.pro)</STRONG><P>
4079 <HR>
4080
4081 <A NAME="GETPRIMARYSCREENSIZE">
4082 <H2>GETPRIMARYSCREENSIZE</H2></A>
4083 <A HREF="#GETIMAGE">[Previous Routine]</A>
4084 <A HREF="#GET_OBJECT_ID">[Next Routine]</A>
4085 <A HREF="#ROUTINELIST">[List of Routines]</A>
4086 <PRE>
4087 :Description:
4088 Provides a way to get the screen size of the primary monitor, especially when
4089 there are several being used.
4090
4091 :Categories:
4092 Graphics
4093
4094 :Params:
4095 none
4096
4097 :Keywords:
4098 exclude_taskbar: in, optional, boolean, default=0
4099 Set this keyword to exclude the taskbar from the monitor size.
4100 This keyword is ignored on all but Windows machines.
4101
4102 :Author:
4103 Dick Jackson, www.dick-jackson.com
4104
4105 :History:
4106 Change History::
4107 Written, 8 March 2011. DJ
4108 Modified to only use IDLsysMonitorInfo for IDL 6.3 and higher. 23 Feb 2012. DWF.
4109
4110 :Copyright:
4111 Copyright (c) 2011, Fanning Software Consulting, Inc.
4112 </PRE><P>
4113 <STRONG>(See getprimaryscreensize.pro)</STRONG><P>
4114 <HR>
4115
4116 <A NAME="GET_OBJECT_ID">
4117 <H2>GET_OBJECT_ID</H2></A>
4118 <A HREF="#GETPRIMARYSCREENSIZE">[Previous Routine]</A>
4119 <A HREF="#CGGMASCL">[Next Routine]</A>
4120 <A HREF="#ROUTINELIST">[List of Routines]</A>
4121 <PRE>
4122 NAME:
4123 GET_OBJECT_ID
4124
4125 PURPOSE:
4126
4127 The purpose of this function is to be able to obtain a unique
4128 object identifier string for a heap variable (object or pointer).
4129
4130 AUTHOR:
4131
4132 FANNING SOFTWARE CONSULTING
4133 David Fanning, Ph.D.
4134 1645 Sheely Drive
4135 Fort Collins, CO 80526 USA
4136 Phone: 970-221-0438
4137 E-mail: [email protected]
4138 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
4139
4140 CATEGORY:
4141
4142 Utility.
4143
4144 CALLING SEQUENCE:
4145
4146 objectID = Get_Object_ID(theObject)
4147
4148 INPUTS:
4149
4150 theObject: The object or pointer for which an identifier is requested. If
4151 this is a null object, the function returns the string
4152 "NullObject". If it is a null pointer, "NullPointer".
4153
4154 OUTPUTS:
4155
4156 objectID: The unique object or pointer identifier.
4157
4158 KEYWORDS:
4159
4160 NUMBER: If this keyword is set, the function returns the unique
4161 number identifier associated with a valid pointer or object.
4162 The number is returned as a STRING variable. The string
4163 "-999" is returned if the pointer or object is invalid and
4164 this keyword is set.
4165
4166 EXAMPLE:
4167
4168 Create a trackball object and obtain its unique object ID.
4169
4170 IDL> theObject = Obj_New('TRACKBALL', [100,100], 50)
4171 IDL> objectID = Get_Object_ID(theObject, NUMBER=number)
4172 IDL> Print, objectID
4173 ObjHeapVar71(TRACKBALL)
4174 IDL> Print, number
4175 71
4176
4177 MODIFICATION HISTORY:
4178
4179 Written by: David W. Fanning, 4 September 2003.
4180 Added NUMBER keyword. DWF, 22 September 2008.
4181 </PRE><P>
4182 <STRONG>(See get_object_id.pro)</STRONG><P>
4183 <HR>
4184
4185 <A NAME="CGGMASCL">
4186 <H2>CGGMASCL</H2></A>
4187 <A HREF="#GET_OBJECT_ID">[Previous Routine]</A>
4188 <A HREF="#HCOLORBAR">[Next Routine]</A>
4189 <A HREF="#ROUTINELIST">[List of Routines]</A>
4190 <PRE>
4191 NAME:
4192 CGGMASCL
4193
4194 PURPOSE:
4195
4196 This is a utility routine to perform basic gray-level pixel
4197 transformations of images. I think of it as BYTSCL on steroids.
4198 It is similar to IMADJUST in _Digital Image Processing with MATLAB_
4199 by Gonzales, Wood, and Eddins. It performs a log scaling of the
4200 image array.
4201
4202 AUTHOR:
4203
4204 FANNING SOFTWARE CONSULTING
4205 David Fanning, Ph.D.
4206 1645 Sheely Drive
4207 Fort Collins, CO 80526 USA
4208 Phone: 970-221-0438
4209 E-mail: [email protected]
4210 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
4211
4212 CATEGORY:
4213
4214 Utilities
4215
4216 CALLING SEQUENCE:
4217
4218 scaledImage = CGGMASCL(image)
4219
4220 ARGUMENTS:
4221
4222 image: The image to be scaled. Written for 2D images, but arrays
4223 of any size are treated alike.
4224
4225 KEYWORDS:
4226
4227 GAMMA: The exponent in a power-law transformation (image^gamma). A gamma
4228 value of 1 results in a linear distribution of values between
4229 OMIN and OMAX. Gamma values less than 1 map darker image values
4230 into a wider range of output values, and Gamma values
4231 greater than 1 maps lighter image values into a wider
4232 range of output values. The gamma value is constrained to
4233 be greater than 1.0e-6.
4234
4235 MAX: Any value in the input image greater than this value is
4236 set to this value before scaling.
4237
4238 MIN: Any value in the input image less than this value is
4239 set to this value before scaling.
4240
4241 NEGATIVE: If set, the "negative" of the result is returned.
4242
4243 OMAX: The output image is scaled between OMIN and OMAX. The
4244 default value is 255.
4245
4246 OMIN: The output image is scaled between OMIN and OMAX. The
4247 default value is 0.
4248 RETURN VALUE:
4249
4250 scaledImage: The output, scaled into the range OMIN to OMAX. A byte array.
4251
4252 COMMON BLOCKS:
4253 None.
4254
4255 EXAMPLES:
4256
4257 LoadCT, 0 ; Gray-scale colors.
4258 image = cgDemoData(11) ; Load image.
4259 TV, cgGmaScl(image, Min=30, Max=100) ; Similar to BytScl.
4260 TV, cgGmaScl(image, /Negative) ; Produce negative image.
4261 power = Shift(ALog(Abs(FFT(image,-1))), 124, 124) ; Create power spectrum.
4262 TV, cgGmaScl(power, Gamma=2.5) ; View power specturm with gamma correction.
4263 TV, cgGmaScl(power, Gamma=2.5, /Negative) ; Reverse power spectrum.
4264
4265 RESTRICTIONS:
4266
4267 Requires cgScaleVector from the Coyote Library:
4268
4269 http://www.idlcoyote.com/programs/cgScaleVector.pro
4270
4271 MODIFICATION HISTORY:
4272
4273 Written by: David W. Fanning, 17 February 2006.
4274 Fixed a problem with output scaling. 1 July 2009. DWF (with input from Bo Milvang-Jensen).
4275 Now setting NAN keyword on all MIN and MAX functions. 2 Dec 2011. DWF.
4276 </PRE><P>
4277 <STRONG>(See cggmascl.pro)</STRONG><P>
4278 <HR>
4279
4280 <A NAME="HCOLORBAR">
4281 <H2>HCOLORBAR</H2></A>
4282 <A HREF="#CGGMASCL">[Previous Routine]</A>
4283 <A HREF="#HELP_VAR">[Next Routine]</A>
4284 <A HREF="#ROUTINELIST">[List of Routines]</A>
4285 <PRE>
4286 NAME:
4287 HCOLORBAR
4288
4289 FILENAME:
4290
4291 hcolorbar__define.pro
4292 ;
4293 PURPOSE:
4294
4295 The purpose of this program is to create a horizontal
4296 colorbar object to be used in conjunction with other
4297 IDL 5 graphics objects.
4298
4299 AUTHOR:
4300
4301 FANNING SOFTWARE CONSULTING
4302 David Fanning, Ph.D.
4303 1645 Sheely Drive
4304 Fort Collins, CO 80526 USA
4305 Phone: 970-221-0438
4306 E-mail: [email protected]
4307 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
4308
4309 CATEGORY:
4310
4311 Object Graphics.
4312
4313 CALLING SEQUENCE:
4314
4315 thisColorBar = Obj_New('HColorBar')
4316
4317 REQUIRED INPUTS:
4318
4319 None.
4320
4321 INIT METHOD KEYWORD PARAMETERS:
4322
4323 COLOR: A three-element array representing the RGB values of a color
4324 for the colorbar axes and annotation. The default value is
4325 white: [255,255,255].
4326
4327 FONTSIZE: A floating value that is the point size of the font
4328 used for the axis and title annotations. Set to 8 point by default.
4329
4330 NAME: The name associated with this object.
4331
4332 NCOLORS: The number of colors associated with the colorbar. The
4333 default is 256.
4334
4335 MAJOR: The number of major tick divisions on the colorbar axes.
4336 The default is 5.
4337
4338 MINOR: The number of minor tick marks on the colorbar axes.
4339 The default is 4.
4340
4341 PALETTE: A palette object for the colorbar. The default palette
4342 is a gray-scale palette object.
4343
4344 POSITION: A four-element array specifying the position of the
4345 colorbar in normalized coordinate space. The default position
4346 is [0.10, 0.90, 0.90, 0.95].
4347
4348 RANGE: The range associated with the colorbar axis. The default
4349 is [0, NCOLORS].
4350
4351 TITLE: A string containing a title for the colorbar axis
4352 annotation. The default is a null string.
4353
4354 OTHER METHODS:
4355
4356 Clamp (Procedure): Given a two-element array in the data range of
4357 the colorbar, the colorbar image is clamped to this range. In
4358 other words, the range of colors is clamped to the specified
4359 range. Values above or below the range in the colorbar are set to
4360 the minimum and maximum range values, respectively.
4361
4362 GetProperty (Procedure): Returns colorbar properties in keyword
4363 parameters as defined for the INIT method. Keywords allowed are:
4364
4365 COLOR
4366 MAJOR
4367 MINOR
4368 NAME
4369 PALETTE
4370 POSITION
4371 RANGE
4372 TEXT
4373 TITLE
4374 TRANSFORM
4375
4376 SetProperty (Procedure): Sets colorbar properties in keyword
4377 parameters as defined for the INIT method. Keywords allowed are:
4378
4379 COLOR
4380 MAJOR
4381 MINOR
4382 NAME
4383 PALETTE
4384 POSITION
4385 RANGE
4386 TEXT
4387 TITLE
4388 TRANSFORM
4389
4390 SIDE EFFECTS:
4391
4392 A HColorBar structure is created. The colorbar INHERITS IDLgrMODEL.
4393 Thus, all IDLgrMODEL methods and keywords can also be used. It is
4394 the model that is selected in a selection event, since the SELECT_TARGET
4395 keyword is set for the model.
4396
4397 EXAMPLE:
4398
4399 To create a colorbar object and add it to a plot view object, type:
4400
4401 thisColorBarObject = Obj_New('HColorBar')
4402 plotView->Add, thisColorBarObject
4403 plotWindow->Draw, plotView
4404
4405 MODIFICATION HISTORY:
4406
4407 Written by David Fanning, from VColorBar code, 20 Sept 98. DWF.
4408 Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
4409 Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
4410 Fixed the same bug when getting the text using the TEXT keyword. :-( 16 Aug 2000. DWF.
4411 Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
4412 Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
4413 Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
4414 Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
4415 Removed TEXT keyword (which was never used) and improved documentation. 15 AUG 2001. DWF.
4416 Added ENABLE_FORMATTING keyword to title objects. 22 October 2001. DWF.
4417 Added a CLAMP method. 18 November 2001. DWF.
4418 Forgot to pass extra keywords along to the text widget. As a result, you couldn't
4419 format tick labels, etc. Fixed this. Any keywords appropriate for IDLgrTick objects
4420 are now available. 26 June 2002. DWF.
4421 Fixed a problem with POSITION keyword in SetProperty method. 23 May 2003. DWF.
4422 Fixed a problem with setting RANGE keyword in SetProperty method. 6 Sept 2003. DWF.
4423 Removed NORMALIZE from source code. 19 November 2005. DWF.
4424 Font sizes have changed. Now using a 12 point font. 6 May 2011. DWF.
4425 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
4426 </PRE><P>
4427 <STRONG>(See hcolorbar__define.pro)</STRONG><P>
4428 <HR>
4429
4430 <A NAME="HELP_VAR">
4431 <H2>HELP_VAR</H2></A>
4432 <A HREF="#HCOLORBAR">[Previous Routine]</A>
4433 <A HREF="#HISTOMATCH">[Next Routine]</A>
4434 <A HREF="#ROUTINELIST">[List of Routines]</A>
4435 <PRE>
4436 NAME:
4437 HELP_VAR
4438
4439 PURPOSE:
4440
4441 The purpose of this program is to display HELP on just
4442 the variables at the level in which HELP_VAR is called.
4443 It is similar to the HELP command, except that compiled
4444 functions and procedures are not displayed.
4445
4446 AUTHOR:
4447
4448 FANNING SOFTWARE CONSULTING
4449 David Fanning, Ph.D.
4450 1645 Sheely Drive
4451 Fort Collins, CO 80526 USA
4452 Phone: 970-221-0438
4453 E-mail: [email protected]
4454 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
4455
4456 CATEGORY:
4457
4458 Utilities.
4459
4460 CALLING SEQUENCE:
4461
4462 HELP_VAR
4463
4464 REQUIRED INPUTS:
4465
4466 None.
4467
4468 SIDE EFFECTS:
4469
4470 Memory is allocated for each variable, in turn, then deleted.
4471 Uses undefined and unsupported ROUTINE_NAMES function. May not
4472 work in all versions of IDL, including future versions.
4473
4474 EXAMPLE:
4475
4476
4477 PRO HELP_VAR_TEST
4478 a = 4.0
4479 b = Lindgen(11)
4480 HELP_VAR
4481 END
4482
4483 IDL> help_var
4484 A FLOAT = 4.00000
4485 B LONG = Array[11]
4486
4487 MODIFICATION HISTORY:
4488
4489 Written by David W. Fanning, 8 August 2003.
4490 </PRE><P>
4491 <STRONG>(See help_var.pro)</STRONG><P>
4492 <HR>
4493
4494 <A NAME="HISTOMATCH">
4495 <H2>HISTOMATCH</H2></A>
4496 <A HREF="#HELP_VAR">[Previous Routine]</A>
4497 <A HREF="#IMAGESELECT">[Next Routine]</A>
4498 <A HREF="#ROUTINELIST">[List of Routines]</A>
4499 <PRE>
4500 NAME:
4501 HistoMatch
4502
4503 PURPOSE:
4504
4505 This is a function for Histogram Matching, in which an image
4506 is manipulated in such a way that it's final histogram approximates
4507 the histogram of an input image or histogram. Histogram matching
4508 allows the user to specify the shape of the histogram of the final
4509 product.
4510
4511 AUTHOR:
4512
4513 FANNING SOFTWARE CONSULTING
4514 David Fanning, Ph.D.
4515 1645 Sheely Drive
4516 Fort Collins, CO 80526 USA
4517 Phone: 970-221-0438
4518 E-mail: [email protected]
4519 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
4520
4521 CATEGORY:
4522
4523 Image Processing
4524
4525 CALLING SEQUENCE:
4526
4527 output_image = HistoMatch(image, histogram_to_match)
4528
4529 INPUTS:
4530
4531 image - The input image to be manipulated. Assumed to be a 2D byte array.
4532
4533 histogram_to_match - Can be either a 1D long vector of 256 elements specifying
4534 the histogram to match, or a 2D byte array from which the histogram to
4535 match is calculated.
4536
4537 OUTPUTS:
4538
4539 output_image - The manipulated image adjusted to the histogram specifications.
4540
4541 INPUT KEYWORDS:
4542
4543 None.
4544
4545 OUTPUT KEYWORDS:
4546
4547 None.
4548
4549 DEPENDENCIES:
4550
4551 None.
4552
4553 METHOD:
4554
4555 Based on the Histogram Matching method on pages 94-102 of Digital
4556 Image Processing, 2nd Edition, Rafael C. Gonzalez and Richard E. Woods,
4557 ISBN 0-20-118075-8.
4558
4559 EXAMPLE:
4560
4561 There is an example program at the end of this file. It will require cgImage
4562 from the Coyote Library to run. You can also find an explanation of this program
4563 at http://www.idlcoyote.com/ip_tips/histomatch.html.
4564
4565 MODIFICATION HISTORY:
4566
4567 Written by David W. Fanning, January 2003.
4568 </PRE><P>
4569 <STRONG>(See histomatch.pro)</STRONG><P>
4570 <HR>
4571
4572 <A NAME="IMAGESELECT">
4573 <H2>IMAGESELECT</H2></A>
4574 <A HREF="#HISTOMATCH">[Previous Routine]</A>
4575 <A HREF="#IMAGE_BLEND">[Next Routine]</A>
4576 <A HREF="#ROUTINELIST">[List of Routines]</A>
4577 <PRE>
4578 NAME:
4579 IMAGESELECT
4580
4581 PURPOSE:
4582
4583 The purpose of this program is to allow the user to select a formatted
4584 image file for reading. The image data is returned as the result of the
4585 function. The program allows the user to see a thumbnail version of the
4586 image, along with information about the image, before selection. The
4587 program uses the file extention to determine what kind of image is to
4588 be read. The following image types are supported:
4589
4590 TYPE FILE EXTENSION
4591 BMP *.bmp
4592 DICOM *.dcm
4593 FITS *.fits, *.fts (requires NASA ASTRO library on IDL Path)
4594 GIF *.gif (IDL 6.2 and higher)
4595 JPEG *.jpg, *.jpeg, *.jpe
4596 JPEG2000 *.jpf, *.jpx, *.jp2, *.j2c, *.j2k
4597 PICT *.pict
4598 PNG *.png
4599 TIFF *.tif, *tiff
4600
4601 AUTHOR:
4602
4603 FANNING SOFTWARE CONSULTING
4604 David Fanning, Ph.D.
4605 1645 Sheely Drive
4606 Fort Collins, CO 80526 USA
4607 Phone: 970-221-0438
4608 E-mail: [email protected]
4609 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
4610
4611 CATEGORY:
4612
4613 General programming.
4614
4615 CALLING SEQUENCE:
4616
4617 image = ImageSelect()
4618
4619 INPUT PARAMETERS:
4620
4621 None. All input is via keywords.
4622
4623 INPUT KEYWORDS:
4624
4625 BMP -- Set this keyword to select BMP files.
4626
4627 DEMO -- If this keyword is set, the program changes directory to !DIR/examples/data.
4628
4629 DICOM -- Set this keyword to select DICOM files.
4630
4631 DIRECTORY -- The initial input directory name. The current directory by default.
4632
4633 EXCLUDE -- A list of filenames that should excluded from the file selection list.
4634
4635 FILENAME -- The initial filename. If the initial directory has image files of the
4636 correct type, the default is to display the first of these files. Otherwise, blank.
4637
4638 FILTER -- A string, representing the file filter. For example, '*.jpg'.
4639
4640 FITS -- Set the keyword to select FITS files. (Must have NASA Astro Library on path.)
4641
4642 FLIPIMAGE -- Set this keyword if you wish to flip the image from its current orientation. Setting
4643 this keyword reverses the Y dimension of the image.
4644
4645 GIF -- Set this keyword to select GIF files. (IDL versions before 5.4 and after 6.0, only.)
4646
4647 GROUP_LEADER -- Set this keyword to a widget identifier group leader. This keyword MUST be
4648 set when calling this program from another widget program to guarantee modal operation.
4649
4650 J2000 -- Set this keyword to select JPEG2000 files. (May also be set as J2K.) (IDL 6.1 or above.)
4651
4652 J2K -- Set this keyword to select JPEG2000 files. (May also be set as J2000.) (IDL 6.1 or above.)
4653
4654 JPEG -- Set this keyword to select JPEG files.
4655
4656 LISTXSIZE -- Set this keyword to the XSIZE of the list widget. Default is 30 or MAX(StrLen(filenames)), whichever is larger.
4657
4658 OFFSETS -- A two-element array containing the X and Y offsets of the program, from the upper left
4659 corner of the display. On dismissal of the program, if this is a named variable (passed into
4660 the program by reference), then it will contain the last offsets of the program. This is
4661 useful if you want to call ImageSelect again and have it positioned in exactly the same
4662 location it was before.
4663
4664 ONLY2D -- Set this keyword if you only want the user to be able to select 2D images. Note
4665 that the user will be able to browse all images, but the Accept button will only
4666 be sensitive for 2D images.
4667
4668 ONLY3D -- Set this keyword if you only want the user to be able to select 3D or true-color images.
4669 Note that the user will be able to browse all images, but the Accept button will only
4670 be sensitive for 3D or true-color images.
4671
4672 PICT -- Set this keyword to select PICT files.
4673
4674 PGM -- Set this keyword to select PGM files.
4675
4676 PPM -- Set this keyword to select PPM files.
4677
4678 PNG -- Set this keyword to select PNG files.
4679
4680 PREVIEWSIZE -- Set this keyword to the maximum size (in pixels) of the preview window. Default is 150.
4681
4682 SILENT -- Set this keyword to turn off Group_Leader educational message. Use only if you
4683 are sure you know what you are doing. :-)
4684
4685 TIFF -- Set this keyword to select TIFF files. (This is the default filter selection.)
4686
4687 TITLE -- Set this keyword to the text to display as the title of the main image selection window.
4688
4689 NOTE: Any extra keywords passed into the program will collected and passed along to the READ_XXX routines
4690 that actually do the image file reading. Using this keyword inheritance mechanism makes it impossible
4691 to trap misspelled or misused keywords. Please take care when using ANY keyword for this routine!
4692
4693 OUTPUT KEYWORDS:
4694
4695 CANCEL -- This keyword is set to 1 if the user exits the program in any way except hitting the ACCEPT button.
4696 The ACCEPT button will set this keyword to 0.
4697
4698 FHEADER -- Set this keyword to a named variable that will return the FITS header information for a FITS file.
4699
4700 FILEINFO -- This keyword returns information about the selected file. Obtained from the QUERY_**** functions.
4701
4702 GEOTIFF -- If the file is a GeoTIFF file, this keyword will return the GeoTIFF structure containing
4703 the files GeoTags.
4704
4705 OUTDIRECTORY -- The directory where the selected file is found.
4706
4707 OUTFILENAME -- The short filename of the selected file.
4708
4709 PALETTE -- The current color table palette returned as a 256-by-3 byte array.
4710
4711 COMMON BLOCKS:
4712
4713 None.
4714
4715 RESTRICTIONS:
4716
4717 Requires other programs from the Coyote Library.
4718
4719 Note: Keyword inheritance to collect undefined keywords that may be passed into the
4720 program for use in READ_XXX routines, make it impossible to trap keyword useage errors.
4721 Please take care when using keywords.
4722
4723 EXAMPLE:
4724
4725 To read JPEG files from the directory:
4726
4727 IDL> image = ImageSelect(/JPEG)
4728
4729 MODIFICATION HISTORY:
4730
4731 Written by: David W. Fanning, 18 Jan 2001.
4732 Added modification to read both 8-bit and 24-bit BMP files. 27 Jan 2001. DWF.
4733 Fixed a problem with calculating the new size of the draw widget. 5 April 2002. DWF.
4734 Fixed a problem with List Widgets not sizing correctly on UNIX machines. 10 Aug 2002. DWF.
4735 Fixed a problem with the initial file not being selected correctly when you changed
4736 the file type. 10 Aug 2002. DWF.
4737 Added a FLIPIMAGE keyword 10 Aug 2002. DWF.
4738 When user chooses to Flip Image, I now reverse the Y dimension of the image,
4739 rather than set the !Order system variable. 10 Aug 2002. DWF.
4740 Added OUTDIRECTORY and OUTFILENAME keywords. 18 Aug 2002. DWF.
4741 Fairly extensive changes in the way this program works and selects images.
4742 A new version of FSC_FileSelect is also required. Because of interactions
4743 with the operating system with image filters, the program has probably
4744 become more Windows-centric. The default is now to display all image
4745 files the program is capable of reading. 31 October 2002. DWF.
4746 Added ONLY2D keyword to allow the acceptance of 2D images only. 3 Nov 2002. DWF.
4747 Added ability to center itself on the display. 8 Nov 2002. DWF.
4748 Fixed a problem caused by reading old images with short color table vectors. 26 Nov 2002. DWF.
4749 Fixed a problem with specifying a fully-qualified filename. 26 Nov 2002. DWF.
4750 Now highlights the selected file in the directory. 26 Nov 2002. DWF.
4751 Improved error handling. 9 Dec 2002. DWF.
4752 Added PALETTE keyword and improved color operation on 8-bit displays. If the image file
4753 contains a color palette, that palette is now loaded when the image is read from the file.
4754 The current color palette can be obtained with the PALETTE keyword. 4 April 2003. DWF.
4755 Added ONLY3D keyword. 19 April 2003. DWF.
4756 Added ability to read PPM and PGM files. 24 November 2003. DWF.
4757 Added TITLE keyword. 1 December 2003. DWF.
4758 Added EXAMPLES keyword. 22 December 2005. DWF.
4759 Added GIF and JPEG2000 file types. Rearranged and cleaned up code. 3 January 2006. DWF.
4760 Added LISTXSIZE keyword. 3 January 2006. DWF.
4761 Added file type checkmark buttons. Program now compatible with IDL 5.6 and higher. 3 January 2006. DWF.
4762 Improved error handling with invalid file types. 5 January 2006. DWF.
4763 Added OFFSETS and EXCLUDE keywords. 3 March 2006 DWF.
4764 Modified the program to check for FITS unsigned integer data. 3 March 2006. DWF.
4765 Added ability to double-click image name in list to Accept. 10 March 2006. DWF.
4766 Added FHEADER keyword to return FITS header information. 3 April 2006. DWF.
4767 Fixed a problem in which the file type was not set if the user cancelled. 10 July 2006. DWF.
4768 Added a "fit" file extension for FITS images. 1 April 2008. DWF.
4769 Added a FILTER keyword. 1 April 2008. DWF.
4770 Updated for reading transparent images. 13 May 2009. DWF.
4771 Provided check for PNG images with more than 8 bits per channel. 5 August 2009. DWF.
4772 Fixed a problem in which the starting directory was changed on exit. 20 Nov 2010. DWF.
4773 Change EXAMPLES to more easily remembered DEMO keyword. 29 Nov 2010. DWF.
4774 Removed NOINTERPOLATION keywords in going from TVIMAGE to cgImage. 22 Feb 2011. DWF.
4775 Fixed a problem reading 2D Tiff files. 20 Sept 2012. DWF.
4776
4777 </PRE><P>
4778 <STRONG>(See imageselect.pro)</STRONG><P>
4779 <HR>
4780
4781 <A NAME="IMAGE_BLEND">
4782 <H2>IMAGE_BLEND</H2></A>
4783 <A HREF="#IMAGESELECT">[Previous Routine]</A>
4784 <A HREF="#IMAGE_DIMENSIONS">[Next Routine]</A>
4785 <A HREF="#ROUTINELIST">[List of Routines]</A>
4786 <PRE>
4787 NAME:
4788 IMAGE_BLEND
4789
4790 PURPOSE:
4791 The purpose of this program is to demonstrate how to
4792 use the alpha channel to blend one image into another.
4793 The specific purpose is to see a color image on top of
4794 a gray-scale image, with the gray-scale image showing
4795 through behind the color image.
4796
4797 AUTHOR:
4798 FANNING SOFTWARE CONSULTING
4799 David Fanning, Ph.D.
4800 1645 Sheely Drive
4801 Fort Collins, CO 80526 USA
4802 Phone: 970-221-0438
4803 E-mail: [email protected]
4804 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
4805
4806 CATEGORY:
4807
4808 Widgets, Object Graphics.
4809
4810 CALLING SEQUENCE:
4811
4812 Image_Blend
4813
4814 REQUIRED INPUTS:
4815
4816 None. The images "worldelv.dat" and "ctscan.dat" from the
4817 examples/data directory are used.
4818
4819 OPTIONAL INPUTS:
4820
4821 backgroundImage:: A 2D image variable that will be used for the background image.
4822 foregroundImage: A 2D image variable that will be used for the foreground image.
4823
4824 OPTIONAL KEYWORD PARAMETERS:
4825
4826 COLORTABLE: The number of a color table to use for the foreground image.
4827 Color table 3 (red temperature) is used as a default.
4828
4829 COMMON BLOCKS:
4830
4831 None.
4832
4833 SIDE EFFECTS:
4834
4835 None.
4836
4837 RESTRICTIONS:
4838
4839 None. The program XCOLORS is required from the Coyote library.
4840
4841 EXAMPLE:
4842
4843 Image_Blend, Colortable=5
4844
4845 MODIFICATION HISTORY:
4846
4847 Written by David Fanning, 30 March 99.
4848 Fixed bug where I redefined the image parameter. Duh... 1 April 99. DWF.
4849 Moved the program into the 21st century. :-) 21 March 2003. DWF.
4850 Added TIFF, GIF (if version supports it), and PS output. 27 December 2006. DWF.
4851 </PRE><P>
4852 <STRONG>(See image_blend.pro)</STRONG><P>
4853 <HR>
4854
4855 <A NAME="IMAGE_DIMENSIONS">
4856 <H2>IMAGE_DIMENSIONS</H2></A>
4857 <A HREF="#IMAGE_BLEND">[Previous Routine]</A>
4858 <A HREF="#INSIDE">[Next Routine]</A>
4859 <A HREF="#ROUTINELIST">[List of Routines]</A>
4860 <PRE>
4861 The purpose of this function is to return the various dimensions of the image,
4862 and also to extract relevant image information via output keywords. The
4863 function works only with 2D and 3D (24-bit) images, with or without alpha
4864 channels.
4865
4866 :Categories:
4867 Utilities
4868
4869 :Returns:
4870 A vector containing the size of each dimension of the image. It is equivalent
4871 to calling the SIZE function with the DIMENSIONS keyword set.
4872
4873 :Params:
4874 image: in, optional, type=various
4875 The image variable from which information is to be obtained.
4876
4877 :Keywords:
4878 alphachannel: out, optional, type=boolean
4879 This keyword is set to 1 if there is an alpha channel in the image. Otherwise,
4880 the keyword is set to 0.
4881 trueindex: out, optional, type=integer
4882 The position of the "true color" index in the return value. Is -1 for 2D images.
4883 xindex: out, optional, type=integer
4884 The index (position) of the X dimension in the return value.
4885 xsize: out, optional, type=integer
4886 The X size of the image.
4887 yindex: out, optional, type=integer
4888 The index (position) of the Y dimension in the return value.
4889 ysize: out, optional, type=integer
4890 The Y size of the image.
4891
4892 :Examples:
4893 To load open a window of the appropriate size and display a 24-bit image::
4894
4895 dims = Image_Dimensions(image24, XSize=xsize, YSize=ysize, TrueIndex=trueindex)
4896 Window, XSIZE=xsize, YSIZE=ysize
4897 TV, image24, TRUE=trueindex
4898
4899 :Author:
4900 FANNING SOFTWARE CONSULTING::
4901 David W. Fanning
4902 1645 Sheely Drive
4903 Fort Collins, CO 80526 USA
4904 Phone: 970-221-0438
4905 E-mail: [email protected]
4906 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
4907
4908 :History:
4909 Modification History::
4910 Written by: David W. Fanning, 5 March 2003.
4911 Added support for alpha channel images, include ALPHACHANNEL keyword. 13 May 2009. DWF.
4912
4913 :Copyright:
4914 Copyright (c) 2003-2011, Fanning Software Consulting, Inc.
4915 </PRE><P>
4916 <STRONG>(See image_dimensions.pro)</STRONG><P>
4917 <HR>
4918
4919 <A NAME="INSIDE">
4920 <H2>INSIDE</H2></A>
4921 <A HREF="#IMAGE_DIMENSIONS">[Previous Routine]</A>
4922 <A HREF="#JD2TIME">[Next Routine]</A>
4923 <A HREF="#ROUTINELIST">[List of Routines]</A>
4924 <PRE>
4925 NAME:
4926 INSIDE
4927
4928 PURPOSE:
4929
4930 The purpose of this function is to indicate whether a specified
4931 2D point is inside (returns a 1) a specified 2D polygon or outside
4932 (returns a 0).
4933
4934 AUTHOR:
4935
4936 FANNING SOFTWARE CONSULTING
4937 David Fanning, Ph.D.
4938 1645 Sheely Drive
4939 Fort Collins, CO 80526 USA
4940 Phone: 970-221-0438
4941 E-mail: [email protected]
4942 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
4943
4944 CATEGORY:
4945
4946 Utility.
4947
4948 CALLING SEQUENCE:
4949
4950 result = INSIDE(x, y, xpts, ypts)
4951
4952 INPUTS:
4953
4954 x: A scalar or vector of the x coordinates of the 2D point(s) to check.
4955 y: A scalar or vector of the y coordinates of the 2D point(s) to check.
4956 xpts: The x coordinates of the 2D polygon.
4957 ypts: The y coordinates of the 2D polygon.
4958
4959 OUTPUTS:
4960
4961 result: A scalar or vector set to 1 if the point is inside the polygon and to
4962 0 if the point is outside the polygon.
4963
4964 KEYWORDS:
4965
4966 INDEX: An output keyword. If set to a named variable, will return the indices
4967 of the X and Y points that are inside the polygon.
4968
4969 ALGORITHM:
4970
4971 Based on discussions on the IDL newsgroup (comp.lang.idl-pvwave) and
4972 discussed here:
4973
4974 http://www.idlcoyote.com/tips/point_in_polygon.html
4975
4976 Primarily the work of B�rd Krane and William Connelly.
4977
4978 MODIFICATION HISTORY:
4979
4980 Written by: David W. Fanning, 4 September 2003.
4981 Vectorized the function in accord with William Connelly's suggestions 24 July 2005. DWF.
4982 </PRE><P>
4983 <STRONG>(See inside.pro)</STRONG><P>
4984 <HR>
4985
4986 <A NAME="JD2TIME">
4987 <H2>JD2TIME</H2></A>
4988 <A HREF="#INSIDE">[Previous Routine]</A>
4989 <A HREF="#LEFTJUSTIFY">[Next Routine]</A>
4990 <A HREF="#ROUTINELIST">[List of Routines]</A>
4991 <PRE>
4992 The purpose of this function is to convert a Julian day number into
4993 a time string of the form "16 Mar 2009".
4994
4995 :Categories:
4996 Utilities
4997
4998 :Returns:
4999 A scalar or vector of time strings of the form "16 Mar 2009 15:34:26".
5000
5001 :Params:
5002 jdnumber: in, optional, type=integer
5003 A Julian day number or array of Julian day numbers. If absent,
5004 today's current Julian day number.
5005 jdyear: in, optional, type=integer
5006 The year for which the Julian day number applies. If absent, the current year.
5007
5008 :Keywords:
5009 day: out, optional, type=integer
5010 The day of the month as an integer.
5011 month: out, optional, type=integer
5012 The month as an integer.
5013 year: out, optional, type=integer
5014 The year as an integer.
5015
5016 :Examples:
5017 Used like the IDL AXIS command::
5018 IDL> cgPlot, cgDemoData(1), YStyle=8, Position=[0.1, 0.1, 0.85, 0.9], /Window
5019 IDL> cgAxis, /YAxis, Color='red', YRange=[-500, 500], /Save, /Window
5020
5021 :Author:
5022 FANNING SOFTWARE CONSULTING::
5023 David W. Fanning
5024 1645 Sheely Drive
5025 Fort Collins, CO 80526 USA
5026 Phone: 970-221-0438
5027 E-mail: [email protected]
5028 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5029
5030 :History:
5031 Change History::
5032 Written by: David W. Fanning, 25 June 2009.
5033 Added DAY, MONTH, and YEAR keywords. 18 Sept 2012. DWF.
5034
5035 :Copyright:
5036 Copyright (c) 2009-2012, Fanning Software Consulting, Inc.
5037 </PRE><P>
5038 <STRONG>(See jd2time.pro)</STRONG><P>
5039 <HR>
5040
5041 <A NAME="LEFTJUSTIFY">
5042 <H2>LEFTJUSTIFY</H2></A>
5043 <A HREF="#JD2TIME">[Previous Routine]</A>
5044 <A HREF="#LINKEDLIST">[Next Routine]</A>
5045 <A HREF="#ROUTINELIST">[List of Routines]</A>
5046 <PRE>
5047 NAME:
5048 LEFTJUSTIFY
5049
5050 PURPOSE:
5051
5052 This is a utility routine to create a string that is left-justified with
5053 respect to a string width.
5054
5055 AUTHOR:
5056
5057 FANNING SOFTWARE CONSULTING
5058 David Fanning, Ph.D.
5059 1645 Sheely Drive
5060 Fort Collins, CO 80526 USA
5061 Phone: 970-221-0438
5062 E-mail: [email protected]
5063 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5064
5065 CATEGORY:
5066
5067 Utilities
5068
5069 CALLING SEQUENCE:
5070
5071 justifiedString = LeftJustify(string, width)
5072
5073 AUGUMENTS:
5074
5075 string: The string that is to be left-justified. If not supplied, a null
5076 string is returned and no error is issued.
5077
5078 width: The final width of the left-justified string. The width must be
5079 longer than the length of the string or an error results. Default: 50.
5080
5081 KEYWORDS:
5082
5083 None.
5084
5085 RETURN VALUE:
5086
5087 justifiedString: A string of WIDTH, with the string left-justified and the rest of the string
5088 filled with blank characters.
5089
5090 MODIFICATION HISTORY:
5091
5092 Written by: David W. Fanning, 26 January 2009.
5093
5094 </PRE><P>
5095 <STRONG>(See leftjustify.pro)</STRONG><P>
5096 <HR>
5097
5098 <A NAME="LINKEDLIST">
5099 <H2>LINKEDLIST</H2></A>
5100 <A HREF="#LEFTJUSTIFY">[Previous Routine]</A>
5101 <A HREF="#LIST_SELECTOR">[Next Routine]</A>
5102 <A HREF="#ROUTINELIST">[List of Routines]</A>
5103 <PRE>
5104 NAME:
5105 LINKEDLIST
5106
5107 FILENAME:
5108 linkedlist__define.pro
5109
5110 PURPOSE:
5111
5112 The purpose of this program is to implement a list that
5113 is linked in both the forward and backward directions. There
5114 is no restriction as to what can be stored in a linked list
5115 node. The linked list is implemented as an object.
5116
5117 AUTHOR:
5118
5119 FANNING SOFTWARE CONSULTING
5120 David Fanning, Ph.D.
5121 1645 Sheely Drive
5122 Fort Collins, CO 80526 USA
5123 Phone: 970-221-0438
5124 E-mail: [email protected]
5125 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
5126
5127 CATEGORY:
5128
5129 General programming.
5130
5131 CALLING SEQUENCE:
5132
5133 mylist = Obj_New('LINKEDLIST', item)
5134
5135 OPTIONAL INPUTS:
5136
5137 item: The first item added to the list. Items can be any
5138 valid IDL variable type.
5139
5140 COMMON BLOCKS:
5141
5142 Are you kidding?!
5143
5144 RESTRICTIONS:
5145
5146 Be sure to destroy the LINKEDLIST object when you are finished
5147 with it: Obj_Destroy, mylist
5148
5149 Node index numbers start at 0 and go to n-1, where n is the
5150 number of items in the list.
5151
5152 PUBLIC METHODS:
5153
5154 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5155
5156 PRO LINKEDLIST::ADD, item, index, $
5157 AFTER=after, $
5158 BEFORE=before, $
5159 ERROR=error, $
5160 NO_COPY=no_copy, $
5161 REPLACE=replace
5162
5163
5164 The ADD method adds a data item to the list.
5165
5166 Parameters:
5167
5168 item: The data item to be added to the list. Required.
5169
5170 index: The location in the list where the data item is
5171 to be added. If neither the AFTER or BEFORE keyword is
5172 set, the item is added AFTER the item at the index location.
5173 If index is missing, the index points to the last item in
5174 the list. Optional.
5175
5176 Keywords:
5177
5178 AFTER: If this keyword is set, the item is added after the
5179 item at the current index.
5180
5181 BEFORE: If this keyword is set, the item is added before the
5182 item at the current index.
5183
5184 ERROR: On return, if this is not a null string, an error occurred
5185 and this value is set equal to the error message.
5186
5187 NO_COPY: If set, the item is transferred to the internal pointer using
5188 a no copy method. This will cause the item variable to become undefined.
5189
5190 REPLACE: If this keyword is set, the item will replace the current item at
5191 the index location.
5192
5193 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5194
5195 PRO LINKEDLIST::DELETE, index, ALL=all, DESTROY=destroy, ERROR=error
5196
5197 The DELETE method deletes an item from the list.
5198
5199 Parameters:
5200
5201 index: The location in the list where the data item is
5202 to be delete. If index is missing, the index points to
5203 the last item in the list. Optional.
5204
5205 Keywords:
5206
5207 ALL: If this keyword is set, all items in the list are deleted.
5208
5209 DESTROY: If the item at the node is an object or pointer, the
5210 item will be destroyed before the node is deleted. This keyword
5211 is turned on (set to 1) by default. Set to 0 to prevent destruction.
5212
5213 ERROR: On return, if this is not a null string, an error occurred
5214 and this value is set equal to the error message.
5215 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5216
5217 FUNCTION LINKEDLIST::GET_COUNT
5218
5219 The GET_COUNT method returns the number of items in the list.
5220
5221 Return Value: The number of items stored in the linked list.
5222
5223 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5224
5225
5226 FUNCTION LINKEDLIST::GET_ITEM, index, $
5227 ALL=all, $ ; This ASSUMES all items stored are the same type!!!
5228 Dereference=dereference, $ ; Obsolete. Ignored. Always returns item.
5229 ItemPtr=itemPtr, $ ; The pointer to the item, if needed. Output.
5230 NO_COPY=no_copy, $ ; Copy from location with NO_COPY.
5231 ERROR=errorMsg ; The error message. Null string if no error.
5232
5233
5234 Parameters:
5235
5236 index: The location in the list from which the data item is
5237 to be retrieved. If not present, the last item in the list
5238 is retrieved. Optional.
5239
5240 Keywords:
5241
5242 DEREFERENCE: This keyword obsolete and only provided for backward compatibility.
5243
5244 ALL: Set this keyword to return an n-element array containing all the list
5245 items. This requires that all list items be of the same type, and
5246 if they are arrays, they have 7 dimensions or fewer. If index is passed,
5247 it is ignored.
5248
5249 ITEMPTR: The pointer to the data item.
5250
5251 NO_COPY: If this keyword is set, the item is transferred from the data
5252 pointer using a NO_COPY method. This will undefine the item at that
5253 indexed locaton.
5254
5255 ERROR: On return, if this is not a null string, an error occurred
5256 and this value is set equal to the error message.
5257
5258 Return Value: The data item at this index on the list.
5259 If ALL is set, then an array containing all the data items is returned.
5260
5261 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5262
5263 FUNCTION LINKEDLIST::GET_NODE, index, ERROR=error
5264
5265 The GET_NODE method returns a pointer to the specified node
5266 from the list.
5267
5268 Parameters:
5269
5270 index: The location in the list from which the data node is
5271 to be retrieved. If not present, the last node in the list
5272 is retrieved. The node is a structure with three fields:
5273 Previous is a pointer to the previous node in the list.
5274 Next is a pointer to the next node in the list. A null pointer
5275 in the previous field indicates the first node on the list. A
5276 null pointer in the next field indicates the last node on the
5277 list. The item field is a pointer to the item stored in the
5278 node. Optional.
5279
5280 ERROR: On return, if this is not a null string, an error occurred
5281 and this value is set equal to the error message.
5282
5283 Return Value: A pointer to the specified node structure in
5284 the linked list.
5285
5286 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5287
5288 PRO LINKEDLIST::HELP, PRINT=print
5289
5290 The HELP method performs a HELP command on each item
5291 in the linked list.
5292
5293 Keywords:
5294
5295 PRINT: If this keyword is set, the PRINT command is used
5296 instead of the HELP command on the items in the list.
5297
5298 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5299
5300 PRO LINKEDLIST::MOVE_NODE, nodeIndex, location, BEFORE=before, ERROR=error
5301
5302 The MOVE_NODE method moves a list node from one location to another.
5303
5304 Parameters:
5305
5306 nodeIndex: The location in the list of the node you are moving.
5307 Required.
5308
5309 location: The location (index) you are moving the node to. If
5310 location is missing, the location points to the node at the
5311 end of the list.
5312
5313 Keywords:
5314
5315 BEFORE: If this keyword is set, the node is added to the
5316 list before the location node. Otherwise, it is added after
5317 the location node.
5318
5319 ERROR: On return, if this is not a null string, an error occurred
5320 and this value is set equal to the error message.
5321
5322 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5323 PRO LINKEDLIST::REPLACE_ITEM, newItem, index, ERROR=error
5324
5325 Use this method to replace any item in the list with any other value.
5326 This allows the caller to change an item without stepping through the
5327 process of deleting an item then adding a new one.
5328
5329 Parameters:
5330 index: The location of the node you are replacing
5331
5332 newItem: Any value of any data type.
5333
5334 ERROR: On return, if this is not a null string, an error occurred
5335 and this value is set equal to the error message.
5336
5337 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5338 FUNCTION LINKEDLIST::HAVE_ITEM, index, ERROR=error
5339
5340 Use this method to check to see if an item exits at a particular location
5341 on the list. Returns a 1 if the item is there, otherwise a 0.
5342
5343 Parameters:
5344 index: The location of the node you are replacing
5345
5346 ERROR: On return, if this is not a null string, an error occurred
5347 and this value is set equal to the error message.
5348
5349 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
5350
5351
5352 EXAMPLE:
5353
5354 mylist = Obj_New("LINKEDLIST", 5)
5355 mylist->Add, 10
5356 mylist->Add, 7, 1, /Before
5357 mylist->Add, 12
5358 print, mylist->Get_Item(/All)
5359 mylist->Add, 'Bob', 2, /Replace
5360 mylist->Help
5361 mylist->Delete, 0
5362 mylist->Help, /Print
5363
5364 MODIFICATION HISTORY:
5365 Written by: David Fanning, 25 August 98.
5366 25 August 99. Fixed several errors in various methods dealing with
5367 moving nodes from one place to another. DWF.
5368 13 June 2001. DWF. Added DEREFERENCE to the GET_ITEM method to
5369 return the item itself, instead of the pointer to the item.
5370 27 June 2001 Added REPLACE_ITEM method. Ben Tupper.
5371 7 April 2003. Added DESTROY keyword to DELETE method so that objects
5372 and pointers could be cleaned up properly when they are deleted
5373 from the linked list. DWF.
5374 9 April 2003. Fixed a problem that occurs when deleting the last node. DWF.
5375 3 Feb 2004. Make sure loop index vars are long. Jeff Guerber
5376 30 Jun 2004. Added /ALL to GET_ITEM function. Henry Throop, SWRI.
5377 23 Nov 2004. Fixed GET_ITEM, /ALL to accomodate structures and empty
5378 lists. Henry Throop.
5379 21 February 2011. A complete refurbishing to incorporate changes and to fix bugs
5380 I found in the SolarSoft version of this code. I've tried to make this compatible
5381 with the version distributed with SolarSoft to reduce problems caused by two versions
5382 of the software with the same name.
5383 9 December 2011. Fixed a problem with the ALL keyword on the Get_Item method. DWF.
5384 </PRE><P>
5385 <STRONG>(See linkedlist__define.pro)</STRONG><P>
5386 <HR>
5387
5388 <A NAME="LIST_SELECTOR">
5389 <H2>LIST_SELECTOR</H2></A>
5390 <A HREF="#LINKEDLIST">[Previous Routine]</A>
5391 <A HREF="#LOGSCL">[Next Routine]</A>
5392 <A HREF="#ROUTINELIST">[List of Routines]</A>
5393 <PRE>
5394 NAME:
5395 LIST_SELECTOR
5396
5397 PURPOSE:
5398
5399 The purpose of this function is to implement a pop-up dialog widget
5400 for the purpose of selecting "names". Names can be names of variables,
5401 names of files, etc. Any string array can be used.
5402
5403 CALLING SEQUENCE:
5404
5405 selectedNames = List_Selector(theNames)
5406
5407 ARGUMENTS:
5408
5409 theNames: A string array of potential "names" that can be selected.
5410
5411 KEYWORDS:
5412
5413 ALL: Set this keyword if you wish all the names to be selected
5414 initially.
5415
5416 CANCEL: An output keyword set to 1 if the user cancels or quits the
5417 program without hitting the Accept button. Set to 0 if a proper
5418 selection was made and the use hits the Accept button.
5419
5420 COUNT: An output keyword containing the number of elements in the return array.
5421
5422 GROUP_LEADER: The widget identifier of a widget who will be the group leader
5423 for this dialog. Passing a group leader is the *only* way to
5424 assure the dialog will be a MODAL dialog (as opposed to a blocking
5425 dialog). A GROUP_LEADER is required if you will be using this
5426 function in an IDL Virtual Machine application.
5427
5428 LABEL: A string that will be placed on a label above the selections.
5429 If not used, no label is used in the program.
5430
5431 LIST_COUNTER: If this keyword is set, a number is associated and displayed with
5432 each list item, starting with the number 1.
5433
5434 TITLE: A string that is used for the title of the dialog window. If
5435 undefined, then "Selection Widget" is used.
5436
5437 SELECTED_INDICES: An output vector of the selected indices from theNames array.
5438
5439 RETURN VALUE:
5440
5441 selectedNames: Typically, an array of selected names. If there is only one item
5442 in the selection, the variable will be a scalar string.
5443
5444 EXAMPLE:
5445
5446 See the List_Selector_Test procedure below. I use the program to allow the
5447 user to select the names of scientific data sets in an HDF file for further
5448 reading and processing.
5449
5450 MODIFICATION HISTORY:
5451
5452 Written by David W. Fanning, 11 January 2009, based on Name_Selector program.
5453 Added "Accept on Double-Click" functionality. 14 January 2009. DWF.
5454 Added LIST_COUNTER keyword. 25 May 2009. DWF.
5455 Well, basically a RE-DO of yesterday's work, although done correctly today. 26 May 2009. DWF.
5456 Fixed a problem when the user double-clicks an item in the list. 8 August 2009. DWF.
5457 Double clicks are a problem with UNIX machines because <CR> sets event.clicks = 2
5458 prematurely. Removed double-click functionality from all but Windows machines. 9 Feb 2012. DWF.
5459
5460 </PRE><P>
5461 <STRONG>(See list_selector.pro)</STRONG><P>
5462 <HR>
5463
5464 <A NAME="LOGSCL">
5465 <H2>LOGSCL</H2></A>
5466 <A HREF="#LIST_SELECTOR">[Previous Routine]</A>
5467 <A HREF="#MAXMIN">[Next Routine]</A>
5468 <A HREF="#ROUTINELIST">[List of Routines]</A>
5469 <PRE>
5470 NAME:
5471 LOGSCL
5472
5473 PURPOSE:
5474
5475 This is a utility routine to perform a log intensity transformation
5476 on an image. For exponent values greater than 1.0, the upper and
5477 lower values of the image are compressed and centered on the mean.
5478 Larger exponent values provide steeper compression. For exponent values
5479 less than 1.0, the compression is similar to gamma compression. (See
5480 IMGSCL.) See pages 68-70 in _Digital Image Processing with MATLAB_
5481 by Gonzales, Wood, and Eddins. The function is used to improve contrast
5482 in images.
5483
5484 AUTHOR:
5485
5486 FANNING SOFTWARE CONSULTING
5487 David Fanning, Ph.D.
5488 1645 Sheely Drive
5489 Fort Collins, CO 80526 USA
5490 Phone: 970-221-0438
5491 E-mail: [email protected]
5492 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5493
5494 CATEGORY:
5495
5496 Utilities
5497
5498 CALLING SEQUENCE:
5499
5500 outputImage = LOGSCL(image)
5501
5502 ARGUMENTS:
5503
5504 image: The image to be scaled. Written for 2D images, but arrays
5505 of any size are treated alike.
5506
5507 KEYWORDS:
5508
5509 EXPONENT: The exponent in a log transformation. By default, 4.0.
5510
5511 MEAN: Values on either side of the mean will be compressed by the log.
5512 The value is a normalized value between 0.0 and 1.0. By default, 0.5.
5513
5514 NEGATIVE: If set, the "negative" of the result is returned.
5515
5516 MAX: Any value in the input image greater than this value is
5517 set to this value before scaling.
5518
5519 MIN: Any value in the input image less than this value is
5520 set to this value before scaling.
5521
5522 OMAX: The output image is scaled between OMIN and OMAX. The
5523 default value is 255.
5524
5525 OMIN: The output image is scaled between OMIN and OMAX. The
5526 default value is 0.
5527 RETURN VALUE:
5528
5529 outputImage: The output, scaled into the range OMIN to OMAX. A byte array.
5530
5531 COMMON BLOCKS:
5532 None.
5533
5534 EXAMPLES:
5535
5536 cgLoadCT, 0 ; Gray-scale colors.
5537 image = cgDemoData(22) ; Load image.
5538 cgImage, image ; No contrast.
5539 cgImage, LogScl(image) ; Improved contrast.
5540 cgImage, LogScl(image, Exponent=10, Mean=0.65) ; Even more contrast.
5541 cgImage, LogScl(image, /Negative, Exponent=5) ; A negative image.
5542
5543 RESTRICTIONS:
5544
5545 Requires cgScaleVector from the Coyote Library:
5546
5547 http://www.idlcoyote.com/programs/cgScaleVector.pro
5548
5549 MODIFICATION HISTORY:
5550
5551 Written by: David W. Fanning, 20 February 2006.
5552 Fixed a problem with output scaling. 1 July 2009. DWF (with input from Bo Milvang-Jensen).
5553 </PRE><P>
5554 <STRONG>(See logscl.pro)</STRONG><P>
5555 <HR>
5556
5557 <A NAME="MAXMIN">
5558 <H2>MAXMIN</H2></A>
5559 <A HREF="#LOGSCL">[Previous Routine]</A>
5560 <A HREF="#MAXWINDOWSIZE">[Next Routine]</A>
5561 <A HREF="#ROUTINELIST">[List of Routines]</A>
5562 <PRE>
5563 :Description:
5564 Prints the maximum and minimum of an IDL variable.
5565
5566 :Categories:
5567 Utility
5568
5569 :Params:
5570 variable: in, required, type=any
5571 The variable whose minimum and maximum you wish to know.
5572
5573 :Keywords:
5574 NAN: in, optional, type=boolean
5575 Set this keyword to ignore NANs in the variable. Default: 0.
5576 TEXT: in, optional, type=string
5577 Prepend this string to the output of MinMax. Default: "MinMax: ".
5578
5579 :Examples:
5580 The MaxMin routine gives the range of the variable::
5581 IDL> a = Findgen(11)
5582 IDL> MaxMin, a, TEXT='Variable A:'
5583 Variable A: 11 0
5584
5585 :Author:
5586 FANNING SOFTWARE CONSULTING::
5587 David W. Fanning
5588 1645 Sheely Drive
5589 Fort Collins, CO 80526 USA
5590 Phone: 970-221-0438
5591 E-mail: [email protected]
5592 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5593
5594 :History:
5595 Change History::
5596 Written, 20 Sept 2010.
5597 Changed name of program from MinMax to MaxMin to avoid conflict with
5598 MinMax program in NASA Astronomy Library. 1 Nov 2010. DWF.
5599
5600 :Copyright:
5601 Copyright (c) 2010, Fanning Software Consulting, Inc.
5602 </PRE><P>
5603 <STRONG>(See maxmin.pro)</STRONG><P>
5604 <HR>
5605
5606 <A NAME="MAXWINDOWSIZE">
5607 <H2>MAXWINDOWSIZE</H2></A>
5608 <A HREF="#MAXMIN">[Previous Routine]</A>
5609 <A HREF="#NAME_SELECTOR">[Next Routine]</A>
5610 <A HREF="#ROUTINELIST">[List of Routines]</A>
5611 <PRE>
5612 :Description:
5613 Returns the resolution of the largest unobstructed graphics window that can be
5614 created on this particular graphics device. Works properly for Windows and UNIX
5615 computers, excluding Macintosh computers. There is no known way to find the resolution
5616 of the largest unobstructed graphics window on a Macintosh computer, so a fudge factor
5617 of 22 pixels is used to account for the Macintosh "dock".
5618
5619 :Categories:
5620 Utility
5621
5622 :Params:
5623 none:
5624
5625 :Keywords:
5626 monitor_resolution: out, optional, type=long
5627 Set this keyword to a named variable to return the resolution of the
5628 primary display monitor.
5629
5630 :Examples:
5631 To create a window of maximum size::
5632 maxsize = MaxWindowSize()
5633 Window, XSize=maxsize[0], YSize=maxsize[1], /Free
5634
5635 :Author:
5636 FANNING SOFTWARE CONSULTING::
5637 David W. Fanning
5638 1645 Sheely Drive
5639 Fort Collins, CO 80526 USA
5640 Phone: 970-221-0438
5641 E-mail: [email protected]
5642 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5643
5644 :History:
5645 Change History::
5646 Written, 26 October 2010. DWF.
5647 Misunderstood Macintosh result. Now Mac treated like UNIX. 27 Oct 2010. DWF.
5648 No known method for Macintosh computers. Resorting to a fudge factor
5649 of 22 pixels to account for the Macintosh dock. 27 Oct 2010. DWF.
5650 Code is total reversed for UNIX and Macintosh computers! Fixed. 16 Dec 2011. DWF.
5651 Modified to only use IDLsysMonitorInfo for IDL 6.3 and higher. 23 Feb 2012. DWF.
5652
5653 :Copyright:
5654 Copyright (c) 2010, Fanning Software Consulting, Inc.
5655 </PRE><P>
5656 <STRONG>(See maxwindowsize.pro)</STRONG><P>
5657 <HR>
5658
5659 <A NAME="NAME_SELECTOR">
5660 <H2>NAME_SELECTOR</H2></A>
5661 <A HREF="#MAXWINDOWSIZE">[Previous Routine]</A>
5662 <A HREF="#NCDF_ATTRIBUTE">[Next Routine]</A>
5663 <A HREF="#ROUTINELIST">[List of Routines]</A>
5664 <PRE>
5665 NAME:
5666 NAME_SELECTOR
5667
5668 PURPOSE:
5669
5670 The purpose of this function is to implement a pop-up dialog widget
5671 for the purpose of selecting "names". Names can be names of variables,
5672 names of files, etc. Any string array can be used.
5673
5674 CALLING SEQUENCE:
5675
5676 selectedNames = Name_Selector(theNames)
5677
5678 ARGUMENTS:
5679
5680 theNames: A string array of potential "names" that can be selected.
5681
5682 KEYWORDS:
5683
5684 ALL: Set this keyword if you wish all the names to be selected
5685 initially.
5686
5687 CANCEL: An output keyword set to 1 if the user cancels or quits the
5688 program without hitting the Accept button. Set to 0 if a proper
5689 selection was made and the use hits the Accept button.
5690
5691 COUNT: An output keyword containing the number of elements in the return array.
5692
5693 GROUP_LEADER: The widget identifier of a widget who will be the group leader
5694 for this dialog. Passing a group leader is the *only* way to
5695 assure the dialog will be a MODAL dialog (as opposed to a blocking
5696 dialog). A GROUP_LEADER is required if you will be using this
5697 function in an IDL Virtual Machine application.
5698
5699 LABEL: A string that will be placed on a label above the selections.
5700 If not used, no label is used in the program.
5701
5702 NUMCOLS: The number of columns to organize the string array in. The default
5703 is to use one column per approximately 20 strings.
5704
5705 TITLE: A string that is used for the title of the dialog window. If
5706 undefined, then "Selection Widget" is used.
5707
5708 RETURN VALUE:
5709
5710 selectedNames: Typically, an array of selected names. If there is only one item
5711 in the selection, the variable will be a scalar string.
5712
5713 EXAMPLE:
5714
5715 See the Name_Selector_Test procedure below. I use the program to allow the
5716 user to select the names of scientific data sets in an HDF file for further
5717 reading and processing.
5718
5719 MODIFICATION HISTORY:
5720
5721 Written by David W. Fanning, 21 December 2008.
5722 Added a COUNT keyword. DWF. 6 January 2009.
5723
5724 </PRE><P>
5725 <STRONG>(See name_selector.pro)</STRONG><P>
5726 <HR>
5727
5728 <A NAME="NCDF_ATTRIBUTE">
5729 <H2>NCDF_ATTRIBUTE</H2></A>
5730 <A HREF="#NAME_SELECTOR">[Previous Routine]</A>
5731 <A HREF="#NCDF_BROWSER">[Next Routine]</A>
5732 <A HREF="#ROUTINELIST">[List of Routines]</A>
5733 <PRE>
5734 NAME:
5735 NCDF_ATTRIBUTE
5736
5737 PURPOSE:
5738
5739 The pupose of this NCDF_Attribute object is to store information about
5740 a netCDF global or variable attribute. The object is principally used
5741 as a utility routine for the NCDF_FILE object. Given the attribute name,
5742 the object will acquire additional information about the attribute from
5743 the netCDF file containing the attribute.
5744
5745 AUTHOR:
5746
5747 FANNING SOFTWARE CONSULTING
5748 David Fanning, Ph.D.
5749 1645 Sheely Drive
5750 Fort Collins, CO 80526 USA
5751 Phone: 970-221-0438
5752 E-mail: [email protected]
5753 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5754
5755 CATEGORY:
5756 File I/O
5757
5758 CALLING SEQUENCE:
5759
5760 IDL> attrObj = Obj_New('NCDF_ATTRIBUTE', attrName, parent, VARNAME=varName)
5761
5762 ARGUMENTS:
5763
5764 attrName: The case sensitive name of a netCDF attribute that is stored in the
5765 netCDF file. (Input and required.)
5766
5767 parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
5768 object reference of the file that contains this attribute. (Input and required.)
5769
5770 KEYWORD PARAMETERS:
5771
5772 varName: If this is a variable attribute, this is the case sensitive name of the
5773 variable that the attribute is attached to. (Input and required for variable
5774 attributes.) Note that a variable object reference may be used in place of the
5775 variable name.
5776
5777 METHODS:
5778
5779 The following methods are available. Each is documented in front of the method.
5780
5781 attrName = attrObject -> GetName()
5782 propertyValue = attrObject -> GetProperty(attrProperty)
5783 attrValue = attrObject -> GetValue()
5784 attrObject -> ParseAttribute
5785
5786
5787 MODIFICATION HISTORY:
5788 Written by: David W. Fanning, 3 Feb 2010.
5789 </PRE><P>
5790 <STRONG>(See ncdf_attribute__define.pro)</STRONG><P>
5791 <HR>
5792
5793 <A NAME="NCDF_BROWSER">
5794 <H2>NCDF_BROWSER</H2></A>
5795 <A HREF="#NCDF_ATTRIBUTE">[Previous Routine]</A>
5796 <A HREF="#NCDF_CASTDATATYPE">[Next Routine]</A>
5797 <A HREF="#ROUTINELIST">[List of Routines]</A>
5798 <PRE>
5799 NAME:
5800 NCDF_BROWSER
5801
5802 PURPOSE:
5803
5804 This program is designed to make it easier to browse and read the
5805 data and metadata in netCDF and HDF files. The user can browse files,
5806 and read the data and metadata into main-level IDL variables. New netCDF
5807 and HDF files can be opened at any time. The user interacts with the
5808 program via a browser window (GUI). This program is a wrapper for the
5809 NCDF_DATA object (ncdf_data__define.pro), which must also be downloaded.
5810
5811 Note that only HDF files with scientific datasets (SD) can be read currently.
5812 There is no support for VDATA objects or other objects sometimes found in HDF
5813 files. Also note that when variables are returned from HDF files, they are returned
5814 in a calibrated form, if calibration information about the variable is present in the
5815 file. Calibration information is presented as an extra variable attribute in the
5816 browser.
5817
5818 calibratedData = calData.cal * (uncalibratedData - calData.offset)
5819
5820 AUTHOR:
5821
5822 FANNING SOFTWARE CONSULTING
5823 David Fanning, Ph.D.
5824 1645 Sheely Drive
5825 Fort Collins, CO 80526 USA
5826 Phone: 970-221-0438
5827 E-mail: [email protected]
5828 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5829
5830 CATEGORY:
5831
5832 File I/O
5833
5834 CALLING SEQUENCE:
5835
5836 IDL> NCDF_Browser, filename
5837
5838 Arguments:
5839
5840 filename: The name of a netCDF and HDF file to open and browse.
5841
5842 KEYWORD PARAMETERS:
5843
5844 EXTENSION: In general, netCDF and HDF files use *.nc, *.ncf, *.ncdf and *.hdf file extensions to
5845 identify themselves as netCDF and HDF files. Some users have their own file extensions.
5846 You can use this keyword to identify the file extension you wish to use. If
5847 set here, it will be used as the file filter in place of the normal file
5848 extensions in DIALOG_PICKFILE.
5849
5850 obj = ('NCDF_DATA', file, EXTENSION='*.bin')
5851
5852 NO_NEW_FILE: If this keyword is set, then the button that allows a new file to be open
5853 on the browser is not created.
5854
5855 NO_READ_ON_PARSE: Normally, when a file is opened it is parsed for information.
5856 One piece of information is the minimum and maximum values of the variables.
5857 This requires actually reading the variables. This can slow things down
5858 considerably is the variable is large. Setting this keyword will suppress
5859 the reading of the variables during the parsing of the data file, with the
5860 result that no minimum or maximum values will be reported.
5861
5862 TITLE: Set this keyword to a string that is on the title bar of the browser.
5863
5864 XOFFSET: Set this keyword to the X offset in pixels of the top-left corner of the browser.
5865
5866 YOFFSET: Set this keyword to the Y offset in pixels of the top-left corner of the browser.
5867
5868 NOTES:
5869
5870 This program is only a (useful) front-end for a more flexible
5871 object program of class NCDF_DATA. In this front end, the NCDF_DATA
5872 object is created and then destroyed when the GUI is destroyed.
5873 The NCDF_DATA object can be used to read netCDF data in a non-interactive
5874 way, if you prefer not to use a GUI to interact with the data file.
5875
5876 MODIFICATION HISTORY:
5877 Written by: David W. Fanning, 03 Feb 2008. Used ideas from many
5878 people, including Chris Torrence, Ken Bowman, Liam Gumely,
5879 Andrew Slater, and Paul van Delst.
5880 Added Extension keyword. DWF. 04 Feb 2008.
5881 Added error handling and protection for NCDF variables that have a dimension of length zero. 22 April 2009. DWF.
5882 Added NO_READ_ON_PARSE keyword. 22 April 2009. DWF.
5883 Now convert NCDF CHAR type variables to strings on output. 22 April 2009. DWF
5884 Made the default value of NO_READ_ON_PARSE set to 1. 25 June 2009. DWF.
5885 Added NO_NEW_FILE keyword to suppress the Open File button. 3 February 2010. DWF.
5886 Added TITLE, XOFFSET, and YOFFSET keywords. 5 February 2010. DWF.
5887 Fixed a problem with memory leakage when the input file cannot be read. 1 May 2010. DWF.
5888 </PRE><P>
5889 <STRONG>(See ncdf_browser.pro)</STRONG><P>
5890 <HR>
5891
5892 <A NAME="NCDF_CASTDATATYPE">
5893 <H2>NCDF_CASTDATATYPE</H2></A>
5894 <A HREF="#NCDF_BROWSER">[Previous Routine]</A>
5895 <A HREF="#NCDF_CONTAINER">[Next Routine]</A>
5896 <A HREF="#ROUTINELIST">[List of Routines]</A>
5897 <PRE>
5898 NAME:
5899 NCDF_CastDataType
5900
5901 PURPOSE:
5902
5903 This is a utility routine to turn IDL data types into the equivalent
5904 netCDF data type. In other words, change 'STRING' to 'CHAR' and so on.
5905
5906 AUTHOR:
5907
5908 FANNING SOFTWARE CONSULTING
5909 David Fanning, Ph.D.
5910 1645 Sheely Drive
5911 Fort Collins, CO 80526 USA
5912 Phone: 970-221-0438
5913 E-mail: [email protected]
5914 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5915
5916 CATEGORY:
5917
5918 Utilities
5919
5920 CALLING SEQUENCE:
5921
5922 ncdf_datatype = NCDF_CastDataType(variable)
5923
5924 ARGUMENTS:
5925
5926 variable: The IDL variable for which you want a netCDF data type.
5927 Or, if the TYPE keyword is set, the variable type index you wish
5928 to convert. Or, if the TNAME keyword is set, the variable type
5929 name you wish to convert.
5930
5931 KEYWORDS:
5932
5933 TYPE: If set, the positional argument is an IDL variable type of
5934 the sort returned by the SIZE function with the TYPE keyword set.
5935
5936 type = Size(variable, /TYPE)
5937
5938 TNAME: If set, the positional argument is an IDL variable type of
5939 the sort returned by the SIZE function with the TNAME keyword set.
5940
5941 type = Size(variable, /TNAME)
5942
5943 RETURN VALUE:
5944
5945 ncdf_datatype: The netCDF data type of the variable. Possible values are
5946 'BYTE', 'CHAR', 'SHORT', 'LONG', 'FLOAT' and 'DOUBLE'.
5947
5948 NOTES:
5949
5950 The program is designed to work with the NCDF_FILE object and related programs.
5951
5952 MODIFICATION HISTORY:
5953
5954 Written by: David W. Fanning, 3 February 2010.
5955 Made a UINT data type be cast to LONG, rather than SHORT. 29 April 2010. DWF.
5956 Added TYPE and TNAME keywords. 5 May 2010. DWF.
5957 </PRE><P>
5958 <STRONG>(See ncdf_castdatatype.pro)</STRONG><P>
5959 <HR>
5960
5961 <A NAME="NCDF_CONTAINER">
5962 <H2>NCDF_CONTAINER</H2></A>
5963 <A HREF="#NCDF_CASTDATATYPE">[Previous Routine]</A>
5964 <A HREF="#NCDF_DATA__DEFINE">[Next Routine]</A>
5965 <A HREF="#ROUTINELIST">[List of Routines]</A>
5966 <PRE>
5967 NAME:
5968 NCDF_Container
5969
5970 PURPOSE:
5971
5972 This is a beefed-up IDL_CONTAINER object written as a utility object
5973 for the NCDF_FILE object and related objects. In particular, two new
5974 container methods have been added. The FindByID method searches container
5975 objects by object ID, and the FindByName method searches container object
5976 by object name. If found, the object reference is returned. This object
5977 is a subclassed IDL_CONTAINER object and uses the IDL_CONTAINER
5978 initialization routine.
5979
5980 AUTHOR:
5981
5982 FANNING SOFTWARE CONSULTING
5983 David Fanning, Ph.D.
5984 1645 Sheely Drive
5985 Fort Collins, CO 80526 USA
5986 Phone: 970-221-0438
5987 E-mail: [email protected]
5988 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
5989
5990 CATEGORY:
5991
5992 Utilities
5993
5994 CALLING SEQUENCE:
5995
5996 ncdf_container = NCDF_Container()
5997
5998 ARGUMENTS:
5999
6000 Those used in the IDL_CONTAINER method.
6001
6002 RETURN VALUE:
6003
6004 A sub-classed IDL_Container object.
6005
6006 NOTES:
6007
6008 The program is designed to work with the NCDF_FILE object and related programs.
6009
6010 MODIFICATION HISTORY:
6011
6012 Written by: David W. Fanning, 3 February 2010.
6013 </PRE><P>
6014 <STRONG>(See ncdf_container__define.pro)</STRONG><P>
6015 <HR>
6016
6017 <A NAME="NCDF_DATA__DEFINE">
6018 <H2>NCDF_DATA__DEFINE</H2></A>
6019 <A HREF="#NCDF_CONTAINER">[Previous Routine]</A>
6020 <A HREF="#NCDF_DIMENSION">[Next Routine]</A>
6021 <A HREF="#ROUTINELIST">[List of Routines]</A>
6022 <PRE>
6023 NAME:
6024 NCDF_DATA__DEFINE
6025
6026 PURPOSE:
6027
6028 This program is designed to make it easier to browse and read the
6029 data and metadata in netCDF and HDF files. The user can browse files,
6030 and read the data and metadata into main-level IDL variables. New netCDF
6031 and HDF files can be opened at any time. The user interacts with the
6032 program via a browser window (GUI) or directly through the methods of
6033 the object. The program implements an IDL object.
6034
6035 Note that only HDF files with scientific datasets (SD) can be read currently.
6036 There is no support for VDATA objects or other objects sometimes found in HDF
6037 files. Also note that when variables are returned from HDF files, they are returned
6038 in a calibrated form, if calibration information about the variable is present in the
6039 file. Calibration information is presented as an extra variable attribute in the
6040 browser.
6041
6042 calibratedData = calData.cal * (uncalibratedData - calData.offset)
6043
6044 AUTHOR:
6045
6046 FANNING SOFTWARE CONSULTING
6047 David Fanning, Ph.D.
6048 1645 Sheely Drive
6049 Fort Collins, CO 80526 USA
6050 Phone: 970-221-0438
6051 E-mail: [email protected]
6052 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
6053
6054 CATEGORY:
6055 File I/O
6056
6057 CALLING SEQUENCE:
6058
6059 IDL> nCDFObject = Obj_New('NCDF_DATA', filename)
6060
6061 ARGUMENTS:
6062
6063 filename: The name of a netCDF or HDF file to open and browse.
6064
6065 KEYWORD PARAMETERS:
6066
6067 BROWSE: If this keyword is set, the Browse Window is invoked as soon
6068 as the object is initiated.
6069
6070 DESTROY_FROM_BROWSER: As with all objects, this object is persistent until
6071 it is destroyed. However, with this keyword set, the object will
6072 be destroyed when the user closes the Browse Window.
6073
6074 EXTENSION: In general, netCDF and HDF files use *.nc, *.ncf, *.ncdf of *.hdf file extensions to
6075 identify themselves as netCDF or HDF files. Some users have their own file extensions.
6076 You can use this keyword to identify the file extension you wish to use. If
6077 set here, it will be used as the file filter in place of the normal file
6078 extensions in DIALOG_PICKFILE.
6079
6080 obj = ('NCDF_DATA', file, EXTENSION='*.bin')
6081
6082 NO_READ_ON_PARSE: Normally, when a file is opened it is parsed for information.
6083 One piece of information is the minimum and maximum values of the variables.
6084 This requires actually reading the variables. This can slow things down
6085 considerably is the variable is large. Setting this keyword will suppress
6086 the reading of the variables during the parsing of the data file, with the
6087 result that no minimum or maximum values will be reported.
6088
6089 NOTES:
6090
6091 This program is designed to be flexible in how it is used, so it
6092 can be used in both interactive and non-interactive (called directly)
6093 ways. A less flexible way of interacting with the program is via the
6094 NCDF_BROWSER program, which is a front-end to this object.
6095
6096 The netCDF and HDF file formats are thought to be "standards". And to
6097 a large extent, they are. But files are not always created to standards,
6098 and both netCDF and HDF files can be quirky. If you look carefully at the
6099 code you will see places where I work around quirks in the files I typically
6100 use on a daily basis. If you find you can't read a particular file, let me know
6101 about it. I may be able to improve the program in such as way that it can be read.
6102
6103 This program is not meant to be the be-all and end-all of programs. Rather, it is
6104 a tool I use, and improve upon whenever necessary, in my own work with netCDF and HDF
6105 files. It will get better for all of us if you report problems to me directly.
6106
6107 METHODS:
6108
6109 The following methods can be used directly.
6110
6111 ncdfObject -> Browse ; Use GUI to browse file data and metadata.
6112 ncdfObject -> OpenFile, filename ; Opens a new netCDF or HDF file.
6113 globalAttr = ncdfObject -> ReadGlobalAttr() ; Return a structure containing global attributes.
6114 attribute = ncdfObject -> ReadAttribute(attrname); Return an attribute, identified by name.
6115 dim = ncdfObject -> ReadDimension(dimName) ; Return a dimension, identified by name.
6116 variable = ncdfObject -> ReadVariable(varname) ; Return a variable, identified by name.
6117 varstruct = ncdfObject -> ReadVariableWithAttr(varname) ; Return a variable, identified by
6118 ; name, along with its attributes.
6119 allData = ncdfObject -> ReadFile(filename) ; Read all the data in the file, into structures.
6120
6121 EXAMPLE:
6122
6123 IDL> filename = 'example.nc'
6124 IDL> ncdfObj = Obj_New('NCDF_DATA', filename)
6125 IDL> ncdfObj -> Browse
6126 IDL> Obj_Destroy, ncdfObj
6127
6128 MODIFICATION HISTORY:
6129 Written by: David W. Fanning, 03 Feb 2008. Used ideas from many
6130 people, including Chris Torrence, Ken Bowman, Liam Gumely,
6131 Andrew Slater, and Paul van Delst.
6132 Added EXTENSION keyword, resizeable TLB, and ability to download
6133 individual global attibutes. DWF. 04 Feb 2008.
6134 Added ReadDimension and ReadVariableWithAttr methods. DWF. 05 Feb 2008.
6135 Ill-formed attribute names giving me fits. Now doing checks with IDL_VALIDNAME
6136 before creating structures. 06 February 2008. DWF.
6137 Same problem. Wide use of IDL_VALIDNAME everywhere it seems wise. 06 Feb 2008. DWF.
6138 Added functionality to read a variable with its attributes from the browser interface,
6139 and fixed a problem with reading CHAR values. 2 March 2008. DWF.
6140 Fixed a problem with changing variable name when reading variable plus attributes. 6 March 2008. DWF.
6141 Fixed a problem with not setting GLOBAL keyword when inquiring about global attribute. 6 March 2008. DWF.
6142 Made sure file was parsed before attempting to read variables and attributes to avoid errors. 7 March 2008. DWF.
6143 Small bug with variable attributes fixed. 18 Dec 2008. DWF.
6144 Added ability to read HDF files containing Scientific Datasets (SD). 21 February 2009. DWF.
6145 Added error handling and protection for NCDF variables that have a dimension of length zero. 22 April 2009. DWF.
6146 Added NO_READ_ON_PARSE keyword. 22 April 2009. DWF.
6147 Now convert NCDF CHAR type variables to strings on output. 22 April 2009. DWF
6148 Fixed a problem with the directory being correct when file name passed in. 11 May 2009. DWF.
6149 Added COUNT, OFFSET, and STRIDE keywords to ReadVariable method. 25 June 2009. DWF.
6150 When reading a netCDF variable by itself (without it's attributes), the program now looks for
6151 a SCALE_FACTOR and ADD_OFFSET attribute, and if found will apply this to the variable before
6152 it is returned to the user. 24 August 2009. DWF.
6153 Added the methods GetAttrNames, GetVarNames, GetVarAttrNames, and ReadVarAttr to retrieve specfic
6154 information from the data files. 16 November 2009. DWF.
6155 Modified the ReadVariableWithAttr method to include the number of dimensions (in the NDIMS field,
6156 and the dimensions (in the DIMS field) in the return structure. For HDF files, the DIMS field
6157 is a vector of the dimensions of the variable. For netCDF files, the DIMS field is a vector
6158 of dimension IDs for the dimensions of the variable. 27 Nov 2009. DWF.
6159 Andy Meigs alerted me to a problem creating a structure when the ncdf variable name
6160 is ill-formed according to IDL structure tag name rules. Fixed in the ReadFile method.
6161 30 November 2009. DWF.
6162 Added NO_NEW_FILE keyword to the BROWSE method. This keyword will suppress the OPEN FILE
6163 button on the browse interface. 3 Feb 2010. DWF.
6164 Made the default browser size a bit larger to accomodate longer variable names. 3 Feb 2010. DWF.
6165 Add a check for HDF/netCDF file type in the INIT method to better accommodate reading data
6166 from the file without first parsing the file. 16 March 2010. DWF.
6167 Changed the ReadVariable for netCDF files to now check for missing data, using either the
6168 depreciated missing_value attribute or the compliant _FillValue attribute. Missing data
6169 is now identified via new output keywords MISSINGINDICES and FILLVALUE, and missing data
6170 is not scaled or offset, if these operations are applied to the data prior to return.
6171 21 March 2010. DWF. Problem with these changes, fixed 23 March 2010. DWF.
6172 Fixed a problem with memory leakage when the input file cannot be read. 1 May 2010. DWF.
6173 Fixed a problem with memory leakage from created structures. 1 May 2010. DWF.
6174 Have done some work on parsing HDF-EOS swath files, but currently unused in code. 15 May 2010. DWF.
6175 Modified the ReadVariable method to check for 0 length dimensions when reading variables
6176 from HDF files. 21 July 2010. DWF.
6177 Modified the global attribute structure so that the "filename" field, which holds the
6178 name of the netCDF of HDF file is now named "ncdf_filename" or "hdf_filename". This
6179 will avoid conflicts with global attributes with "filename". 20 January 2011. DWF.
6180 Typo in the section reading calibration data fixed. 12 March 2013. DWF.
6181 </PRE><P>
6182 <STRONG>(See ncdf_data__define.pro)</STRONG><P>
6183 <HR>
6184
6185 <A NAME="NCDF_DIMENSION">
6186 <H2>NCDF_DIMENSION</H2></A>
6187 <A HREF="#NCDF_DATA__DEFINE">[Previous Routine]</A>
6188 <A HREF="#NCDF_FILE">[Next Routine]</A>
6189 <A HREF="#ROUTINELIST">[List of Routines]</A>
6190 <PRE>
6191 NAME:
6192 NCDF_DIMENSION
6193
6194 PURPOSE:
6195
6196 The pupose of this NCDF_Dimension object is to store information about
6197 a netCDF dimension. The object is principally used as a utility routine
6198 for the NCDF_FILE object. Given the dimension name, the object will
6199 acquire additional information about the dimension from the netCDF file
6200 containing the dimension.
6201
6202 AUTHOR:
6203
6204 FANNING SOFTWARE CONSULTING
6205 David Fanning, Ph.D.
6206 1645 Sheely Drive
6207 Fort Collins, CO 80526 USA
6208 Phone: 970-221-0438
6209 E-mail: [email protected]
6210 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
6211
6212 CATEGORY:
6213 File I/O
6214
6215 CALLING SEQUENCE:
6216
6217 IDL> dimObj = Obj_New('NCDF_DIMENSION', dimName, parent)
6218
6219 ARGUMENTS:
6220
6221 dimName: The case sensitive name of a netCDF dimension that is stored in the
6222 netCDF file. (Input and required.)
6223
6224 parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
6225 object reference of the file that contains this attribute. (Input and required.)
6226
6227 KEYWORD PARAMETERS:
6228
6229 None.
6230
6231 METHODS:
6232
6233 The following methods are available. Each is documented in front of the method.
6234
6235 dimName = dimObject -> GetID()
6236 dimName = dimObject -> GetName()
6237 dimName = dimObject -> GetSize()
6238 propertyValue = dimObject -> GetProperty(dimProperty)
6239 dimValue = dimObject -> GetValue()
6240 dimName = dimObject -> GetUnlimited()
6241 dimObject -> ParseAttribute
6242
6243
6244 MODIFICATION HISTORY:
6245 Written by: David W. Fanning, 3 Feb 2010.
6246 </PRE><P>
6247 <STRONG>(See ncdf_dimension__define.pro)</STRONG><P>
6248 <HR>
6249
6250 <A NAME="NCDF_FILE">
6251 <H2>NCDF_FILE</H2></A>
6252 <A HREF="#NCDF_DIMENSION">[Previous Routine]</A>
6253 <A HREF="#NCDF_FILE_EXAMPLES">[Next Routine]</A>
6254 <A HREF="#ROUTINELIST">[List of Routines]</A>
6255 <PRE>
6256 NAME:
6257 NCDF_FILE
6258
6259 PURPOSE:
6260
6261 The pupose of this NCDF_File object is three-fold. (1) Allow the user to easily
6262 determine what information is inside a netCDF file and allow easy access
6263 to such information. (2) Allow the user to easily create a netCDF file from
6264 scratch. (3) Allow the user to easily copy information from one netCDF
6265 file to another.
6266
6267 AUTHOR:
6268
6269 FANNING SOFTWARE CONSULTING
6270 David Fanning, Ph.D.
6271 1645 Sheely Drive
6272 Fort Collins, CO 80526 USA
6273 Phone: 970-221-0438
6274 E-mail: [email protected]
6275 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
6276
6277 CATEGORY:
6278 File I/O
6279
6280 CALLING SEQUENCE:
6281
6282 IDL> nCDFObject = Obj_New('NCDF_FILE', filename)
6283
6284 ARGUMENTS:
6285
6286 filename: The name of a netCDF file to read, write to, or browse.
6287
6288 KEYWORD PARAMETERS:
6289
6290 ALERT: Set this keyword if you wish to have alert from the object's error logger.
6291 Input. Default is 1.
6292
6293 BROWSE: If this keyword is set, the Browse Window is invoked as soon
6294 as the object is initiated. Input. Default is 0.
6295
6296 CLOBBER: Set this keyword if you are opening a netCDF file that already exists and
6297 you want to overwrite the existing file. Input. Default is 0.
6298
6299 CREATE: Set this keyword if you wish to create a new netCDF file to write
6300 into. Input. Default is 0, which means the file will be opened as
6301 "read-only".
6302
6303 DELETE_ON_DESTROY: Set this keyword if you wish to delete the error log file when
6304 the ErrorLogger object is destroyed. This will only happen if the ErrorLogger
6305 object is not in an error state. Input. Default is 1.
6306
6307 MODIFY: Set this keyword if you wish to modify (write to) a file you are opening.
6308 If not set, the file will be opened as "read-only".
6309
6310
6311 METHODS:
6312
6313 The following methods are available. Each is documented in front of the method.
6314
6315 ncdfObject -> Browse
6316 ncdfObject -> CopyVarAttrTo, varName, attrName, destObj
6317 ncdfObject -> CopyVarDataTo, varName, destObj, COUNT=count, OFFSET=offset, STRIDE=stride
6318 ncdfObject -> CopyVarDefTo, varName, destObj
6319 ncdfObject -> CopyGlobalAttrTo, attrName, destObj
6320 ncdfObject -> CopyDimTo, dimName, destObj
6321 dimNames = ncdfObject -> GetDimNames(COUNT=dimCount)
6322 dimValue = ncdfObject -> GetDimValue(dimName)
6323 fileID = ncdfObject -> GetFileID()
6324 globalAttrNames = ncdfObject -> GetGlobalAttrNames(COUNT=attrCount)
6325 attrValue = ncdfObject -> GetGlobalAttrValue(attrName, DATATYPE=datatype)
6326 ncdfObject -> GetProperty, ....
6327 property = ncdfObject -> GetProperty(thisProperty)
6328 varAttrNames = ncdfObject -> GetVarAttrNames(varName, COUNT=attrCount)
6329 varAttrValue = ncdfObject -> GetVarAttrValue(varName, varAttrName, COUNT=attrCount)
6330 varNames = ncdfObject -> GetVarNames(COUNT=varCount)
6331 varData = ncdfObject -> GetVarData(varName, COUNT=count, OFFSET=offset, STRIDE=stride)
6332 answer = ncdfObject -> HasGlobalAttr(attrName, OBJECT=object)
6333 answer = ncdfObject -> HasDim(dimName, OBJECT=object)
6334 answer = ncdfObject -> HasVar(varName, OBJECT=object)
6335 answer = ncdfObject -> HasVarAttr(varName, attrName, OBJECT=object)
6336 ncdfObject -> PrintFileInfo
6337 ncdfObject -> ParseFile
6338 ncdfObject -> SetMode, DEFINE=define, DATA=data
6339 ncdfObject -> WriteVarData, varName, data, COUNT=count, OFFSET=offset, STRIDE=stride
6340 ncdfObject -> WriteVarDef, varName, dimNames, DATATYPE=datatype, VAROBJ=varObj
6341 ncdfObject -> WriteDim, dimName, dimSize, UNLIMITED=unlimited
6342 ncdfObject -> WriteGlobalAttr, attrName, attrValue, DATATYPE=datatype
6343 ncdfObject -> WriteVarAttr, attrName, attrValue, varObj, DATATYPE=datatype
6344
6345 NOTES:
6346
6347 Note that all variable, attribute, and dimension names in a netCDF file are CASE SENSITIIVE!!
6348 Thus, it is a good idea to use the methods provided in this object to obtain and examine
6349 information in the file, as these names are handled in a case sensitive manner.
6350
6351 Whenever you are creating a new netCDF file, you should try to create the file in
6352 the following way.
6353 1. Create your global attributes.
6354 2. Create the dimensions you will be using to describe the variables.
6355 3. Define the variables. To do this correctly, dimensions MUST be defined.
6356 4. Define variable attributes.
6357 5. Load your variables with data.
6358
6359 Note that the data type of the _FillValue variable attribute MUST match the
6360 data type of the variable data. Otherwise, you will have MANY problems! This
6361 is a common source of error.
6362
6363 Note that in almost all cases where you see the names "varName", "dimName", or
6364 "attrName" used as input variables, you can substitute the proper object
6365 reference in place of the actual name. In other words, you could get the value
6366 of a variable attribute by doing something like this:
6367
6368 check = ncdfObject -> HasAttr('history', OBJECT=attrObj)
6369 IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue(attrObj)
6370
6371 as opposed to this:
6372
6373 IF check THEN attrValue = ncdfObject -> GetGlobalAttrValue('history')
6374 EXAMPLE:
6375
6376 IDL> filename = 'example.nc'
6377 IDL> ncdfObj = Obj_New('NCDF_FILE', filename)
6378 IDL> ncdfObj -> Browse
6379 IDL> Obj_Destroy, ncdfObj
6380
6381 MODIFICATION HISTORY:
6382 Written by: David W. Fanning, 3 Feb 2010, using (stealing, really) plenty of ideas
6383 from Mark Hadfield's Motley Library. Mark's mghncfile object is terrific, but it
6384 had a number of limitations for my particular application, which I have attemped
6385 to correct in my version of the software. But I wouldn't have even attempted this
6386 had Mark not blazed the trail and Matt Savoie not insisted that I look at Mark's
6387 wonderful library.
6388 Changes in the way dimensions with a zero length are handled. 11 Feb 2010, DWF.
6389 Added GetVarInfo method. 20 March 2010. DWF.
6390 Added MISSINGINIDCES and FILLVALUE output keywords to GetVarData method. 20 March 2010. DWF.
6391 Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to GetVarData method
6392 so that these values can be obtained with the data. 29 Apr 2010. DWF.
6393 I changed "missingValue" to "fillValue" some time ago, but I missed one in
6394 the GetVarData method. Fixed. 7 June 2010. DWF.
6395 Used the undefine procedure OBJ_DELETE, rather than OBJ_DESTROY. Sheesh! 18 June 2010. DWF.
6396 Added NETCDF4_FORMAT keyword. 13 Feb 2012. DWF.
6397 Added a bunch of new IDL 8.0 and 8.1 keyword to the WriteVarDef method to allow
6398 access to these keywords in NCDF_VarDef. Also modified the NETCDF4_FORMAT keyword
6399 to apply only in IDL versions 8.0 and higher. 21 Feb 2012. DWF.
6400 Small typo fixed in setting CHAR datatype for IDL 8.1 and higher. 22 May 2013. DWF.
6401 Typo (CONTINUOUS->CONTIGUOUS) fixed in WriteDefVar method. 30 July 2013. DWF.
6402 Modified CopyVarDefTo method to allow new NCDF4 keywords. 30 July 2013. DWF.
6403 Added DelGlobalAttr method to allow deletion of global attributes. 11 Jan 2014. DWF.
6404
6405 </PRE><P>
6406 <STRONG>(See ncdf_file__define.pro)</STRONG><P>
6407 <HR>
6408
6409 <A NAME="NCDF_FILE_EXAMPLES">
6410 <H2>NCDF_FILE_EXAMPLES</H2></A>
6411 <A HREF="#NCDF_FILE">[Previous Routine]</A>
6412 <A HREF="#NCDF_ISVALIDFILE">[Next Routine]</A>
6413 <A HREF="#ROUTINELIST">[List of Routines]</A>
6414 <PRE>
6415 NAME:
6416 NCDF_FILE_EXAMPLES
6417
6418 PURPOSE:
6419
6420 This is a utility routine demonstrates the several ways it is possible
6421 to use the NCDF_FILE object to create netCDF files, copy information
6422 from one netCDF file to another, and to read information from a netCDF
6423 file.
6424
6425 AUTHOR:
6426
6427 FANNING SOFTWARE CONSULTING
6428 David Fanning, Ph.D.
6429 1645 Sheely Drive
6430 Fort Collins, CO 80526 USA
6431 Phone: 970-221-0438
6432 E-mail: [email protected]
6433 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
6434
6435 CATEGORY:
6436
6437 Utilities
6438
6439 CALLING SEQUENCE:
6440
6441 NCDF_File_Examples
6442
6443 ARGUMENTS:
6444
6445 None.
6446
6447 KEYWORDS:
6448
6449 None.
6450
6451 MODIFICATION HISTORY:
6452
6453 Written by: David W. Fanning, 3 February 2010.
6454 Updated to use a time variable for the frame number. 29 Oct 2011.
6455 </PRE><P>
6456 <STRONG>(See ncdf_file_examples.pro)</STRONG><P>
6457 <HR>
6458
6459 <A NAME="NCDF_ISVALIDFILE">
6460 <H2>NCDF_ISVALIDFILE</H2></A>
6461 <A HREF="#NCDF_FILE_EXAMPLES">[Previous Routine]</A>
6462 <A HREF="#NCDF_VARIABLE">[Next Routine]</A>
6463 <A HREF="#ROUTINELIST">[List of Routines]</A>
6464 <PRE>
6465 NAME:
6466 NCDF_ISVALIDFILE
6467
6468 PURPOSE:
6469
6470 Utility routine to determine if a file is a valid netCDF file or not.
6471 Returns a 1 if the file is valid and a 0 otherwise.
6472
6473 AUTHOR:
6474
6475 FANNING SOFTWARE CONSULTING
6476 David Fanning, Ph.D.
6477 1645 Sheely Drive
6478 Fort Collins, CO 80526 USA
6479 Phone: 970-221-0438
6480 E-mail: [email protected]
6481 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
6482
6483 CATEGORY:
6484
6485 Utility.
6486
6487 CALLING SEQUENCE:
6488
6489 result = NCDF_IsValidFile(filename)
6490
6491 INPUTS:
6492
6493 filename: The name of a filename to open to see if it is a valid netCDF file.
6494
6495 RETURN VALUE:
6496
6497 result: A 1 if the file can be opened as a netCDF file. A 0 otherwise.
6498
6499 KEYWORDS:
6500
6501 None.
6502
6503 ALGORITHM:
6504
6505 Try to open the file. If you fail, it is not an netCDF file.
6506
6507 MODIFICATION HISTORY:
6508
6509 Written by: David W. Fanning, 21 February 2010.
6510 </PRE><P>
6511 <STRONG>(See ncdf_isvalidfile.pro)</STRONG><P>
6512 <HR>
6513
6514 <A NAME="NCDF_VARIABLE">
6515 <H2>NCDF_VARIABLE</H2></A>
6516 <A HREF="#NCDF_ISVALIDFILE">[Previous Routine]</A>
6517 <A HREF="#PICKCOLOR">[Next Routine]</A>
6518 <A HREF="#ROUTINELIST">[List of Routines]</A>
6519 <PRE>
6520 NAME:
6521 NCDF_VARIABLE
6522
6523 PURPOSE:
6524
6525 The pupose of this NCDF_Variable object is to store information about
6526 a netCDF variable. The object is principally used as a utility routine
6527 for the NCDF_FILE object. Given the variable name, the object will acquire
6528 additional information about the variable from the netCDF file containing
6529 the variable.
6530
6531 AUTHOR:
6532
6533 FANNING SOFTWARE CONSULTING
6534 David Fanning, Ph.D.
6535 1645 Sheely Drive
6536 Fort Collins, CO 80526 USA
6537 Phone: 970-221-0438
6538 E-mail: [email protected]
6539 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
6540
6541 CATEGORY:
6542
6543 File I/O
6544
6545 CALLING SEQUENCE:
6546
6547 IDL> varObj = Obj_New('NCDF_VARIABLE', varName, parent)
6548
6549 ARGUMENTS:
6550
6551 varName: The case sensitive name of a netCDF variable that is stored in the
6552 netCDF file. (Input and required.)
6553
6554 parent: The object reference (NCDF_FILE object) of the netCDF file. In other words, the
6555 object reference of the file that contains this attribute. (Input and required.)
6556
6557 KEYWORD PARAMETERS:
6558
6559 None.
6560
6561 METHODS:
6562
6563 The following methods are available. Each is documented in front of the method.
6564
6565 varObject -> AddAttr
6566 varAttrNames = varObject -> GetAttrNames()
6567 dimIDs = varObject -> GetDimIDs()
6568 dimNames = varObject -> GetDimNames()
6569 varAttrValue = varObject -> GetAttrValue()
6570 varID = varObject -> GetID()
6571 varName = varObject -> GetName()
6572 propertyValue = varObject -> GetProperty(attrProperty)
6573 varValue = varObject -> GetValue()
6574 varObject -> ParseVariable
6575
6576
6577 MODIFICATION HISTORY:
6578 Written by: David W. Fanning, 3 Feb 2010.
6579 Changes to the way dimensions of length 0 are handled. 11 Feb 2010. DWF.
6580 Added GetInfo method. 20 Mar 2010. DWF.
6581 Added MISSINGINDICES and FILLVALUE keywords to GetValue method to return the indices
6582 and the value of missing data. 20 Mar 2010. DWF.
6583 Modified the GetValue method so that if the data returned is scaled and/or offset
6584 then the "missing" data value is preserved, although its data type may change.
6585 In other words, the "missing" data is not scaled or offset. 20 Mar 2010. DWF.
6586 Added output keywords SCALE_FACTOR, ADD_OFFSET, and DATATYPE to the GetValue method
6587 so that these values can be returned to the caller at run-time. 29 April 2010. DWF.
6588 Modified AddAttr method to allow for additional data types in attributes, specifically
6589 INT data type. 3 June 2013. DWF.
6590 Had to modify AddAttr method again to allow compatibility with IDL versions below 8.1. 26 July 2013. DWF.
6591 </PRE><P>
6592 <STRONG>(See ncdf_variable__define.pro)</STRONG><P>
6593 <HR>
6594
6595 <A NAME="PICKCOLOR">
6596 <H2>PICKCOLOR</H2></A>
6597 <A HREF="#NCDF_VARIABLE">[Previous Routine]</A>
6598 <A HREF="#PRECIPMAP">[Next Routine]</A>
6599 <A HREF="#ROUTINELIST">[List of Routines]</A>
6600 <PRE>
6601 NAME:
6602 PICKCOLOR
6603
6604 PURPOSE:
6605
6606 A modal dialog widget allowing the user to select
6607 the RGB color triple specifying a color. The return
6608 value of the function is the color triple specifying the
6609 color or the "name" of the color if the NAME keyword is set.
6610
6611 AUTHOR:
6612 FANNING SOFTWARE CONSULTING:
6613 David Fanning, Ph.D.
6614 1645 Sheely Drive
6615 Fort Collins, CO 80526 USA
6616 Phone: 970-221-0438
6617 E-mail: [email protected]
6618 Coyote's Guide to IDL Programming: http://www.dfanning.com
6619
6620 CATEGORY:
6621
6622 Graphics, Color Specification. See related program cgCOLOR.
6623
6624 CALLING SEQUENCE:
6625
6626 color = PickColor(colorindex)
6627
6628 RETURN VALUE:
6629
6630 The return value of the function is a 1-by-3 array containing
6631 the values of the color triple that specifies the selected color.
6632 The color can be loaded, for example, in any color index:
6633
6634 color = PickColor(240)
6635 TVLCT, color, 240
6636
6637 The return value is the original color triple if the user
6638 selects the CANCEL button.
6639
6640 IF the NAMES keyword is set, the return value of the function is
6641 the "name" of the selected color. This would be appropriate for
6642 passing to the cgCOLOR program, for example.
6643
6644 OPTIONAL INPUT POSITIONAL PARAMETERS:
6645
6646 COLORINDEX: The color index of the color to be changed. If not
6647 specified the color index !D.Table_Size - 2 is used.
6648 The Current Color and the Color Sliders are set to the
6649 values of the color at this color index.
6650
6651 OPTIONAL INPUT KEYWORD PARAMETERS:
6652
6653 GROUP_LEADER: The group leader for this widget program. This
6654 keyword is required for MODAL operation. If not supplied
6655 the program is a BLOCKING widget. Be adviced, however, that
6656 the program will NOT work if called from a blocking widget
6657 program, unless a GROUP_LEADER is supplied.
6658
6659 NAMES: Set this keyword to return the "name" of the selected color
6660 rather than its color triple.
6661
6662 STARTINDEX: 88 pre-determined colors are loaded The STARTINDEX
6663 is the index in the color table where these 88 colors will
6664 be loaded. By default, it is !D.Table_Size - 89.
6665
6666 TITLE: The title on the program's top-level base. By default the
6667 title is "Pick a Color".
6668
6669 OPTIONAL INPUT KEYWORD PARAMETERS:
6670
6671 CANCEL: A keyword that is set to 1 if the CANCEL button is selected
6672 and to 0 otherwise.
6673
6674 COMMON BLOCKS:
6675
6676 None.
6677
6678 SIDE EFFECTS:
6679
6680 88 pre-determined colors are loaded in the color table.
6681 In addition, the color index at COLORINDEX is modified while
6682 the program is on the display. When the program exits, the
6683 entry color table is restored. Thus, on 8-bit displays there
6684 might be some color effects in graphics windows while PICKCOLOR
6685 is on the display. Changes in the color table are not noticable
6686 on 16-bit and 24-bit displays.
6687
6688 EXAMPLE:
6689
6690 To specify a color for a plot in color decomposition OFF mode:
6691
6692 Device, Decomposed=0
6693 !P.Color = !P.Color < (!D.Table_Size - 1)
6694 color = PickColor(!P.Color, Cancel=cancelled)
6695 IF NOT cancelled THEN BEGIN
6696 TVLCT, color, !P.Color
6697 Plot, data
6698 ENDIF
6699
6700 To specify a color for a plot in color decomposition ON mode:
6701
6702 Device, Decomposed=1
6703 color = PickColor(Cancel=cancelled)
6704 !P.Color = Color24(color)
6705 IF NOT cancelled THEN Plot, data
6706
6707 To obtain the name of the selected color to pass to GetColor:
6708
6709 selectedColor = PickColor(/Name)
6710 axisColor = cgColor(selectedColor, !D.Table_Size-4)
6711
6712 MODIFICATION HISTORY:
6713 Written by: David Fanning, 28 Oct 99.
6714 Added NAME keyword. 18 March 2000, DWF.
6715 Fixed a small bug when choosing a colorindex less than !D.Table_Size-17. 20 April 2000. DWF.
6716 Added actual color names to label when NAMES keyword selected. 12 May 2000. DWF.
6717 Modified to use 88 colors and cgCOLOR instead of 16 colors and GETCOLOR. 4 Dec 2000. DWF.
6718 Changed FSC_Color to cgColor everywhere. 16 Jan 2013. DWF.
6719 </PRE><P>
6720 <STRONG>(See pickcolor.pro)</STRONG><P>
6721 <HR>
6722
6723 <A NAME="PRECIPMAP">
6724 <H2>PRECIPMAP</H2></A>
6725 <A HREF="#PICKCOLOR">[Previous Routine]</A>
6726 <A HREF="#PRINTWINDOW">[Next Routine]</A>
6727 <A HREF="#ROUTINELIST">[List of Routines]</A>
6728 <PRE>
6729 NAME:
6730 PrecipMap
6731
6732 PURPOSE:
6733
6734 This is a program that demonstrates how to place an IDL map projection
6735 onto an image that is already in a map projection space. It uses a NOAA
6736 precipitation image that is in a polar stereographic map projection, and
6737 for which the latitudes and longitudes of its four corners are known.
6738
6739 For additional details, see http://www.idlcoyote.com/map_tips/precipmap.html.
6740
6741 AUTHOR:
6742
6743 FANNING SOFTWARE CONSULTING
6744 David Fanning, Ph.D.
6745 1645 Sheely Drive
6746 Fort Collins, CO 80526 USA
6747 Phone: 970-221-0438
6748 E-mail: [email protected]
6749 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
6750
6751 CATEGORY:
6752
6753 Map Projection
6754
6755 CALLING SEQUENCE:
6756
6757 IDL> PrecipMap, filename
6758
6759 INPUTS:
6760
6761 filename: The name of the precipitation file. For demo, download
6762 ST4.2005010112.24h.bin from http://www.idlcoyote.com/data/ST4.2005010112.24h.bin.
6763
6764 KEYWORDS:
6765
6766 DATA: Set this keyword to a named variable that on output will contain the scaled data.
6767
6768 PALETTE: Set this keyword to a named variable that on output will contain the color
6769 palette used to display the data.
6770
6771
6772 RESTRICTIONS:
6773
6774 Requires files from the Coyote Library:
6775
6776 http://www.idlcoyote.com/documents/programs.html
6777
6778 MODIFICATION HISTORY:
6779
6780 Written by David W. Fanning, 28 April 2006 from code and discussion supplied
6781 by James Kuyper in the IDL newsgroup.
6782 Renamed Colorbar procedure to cgColorbar to avoid conflict with IDL 8 Colorbar function.
6783 26 September 2010. DWF.
6784 Got the polar stereo map projection correct. 5 September 2011. DWF.
6785 Added DATA, MAP, and PALETTE output keywords and updated to use more modern Coyote
6786 Library mapping routines. 2 November 2012. DWF.
6787 </PRE><P>
6788 <STRONG>(See precipmap.pro)</STRONG><P>
6789 <HR>
6790
6791 <A NAME="PRINTWINDOW">
6792 <H2>PRINTWINDOW</H2></A>
6793 <A HREF="#PRECIPMAP">[Previous Routine]</A>
6794 <A HREF="#PSWINDOW">[Next Routine]</A>
6795 <A HREF="#ROUTINELIST">[List of Routines]</A>
6796 <PRE>
6797 NAME:
6798 PRINTWINDOW
6799
6800 This program sends the contents of the specified
6801 window to the default printer. The current window
6802 is used if a window index number is not provided.
6803
6804 AUTHOR:
6805
6806 FANNING SOFTWARE CONSULTING
6807 David Fanning, Ph.D.
6808 1645 Sheely Drive
6809 Fort Collins, CO 80526 USA
6810 Phone: 970-221-0438
6811 E-mail: [email protected]
6812 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
6813
6814 CATEGORY:
6815
6816 Graphics
6817
6818 CALLING SEQUENCE:
6819
6820 IDL> PrintWindow, wid
6821
6822 OPTIONAL POSITIONAL PARAMETERS:
6823
6824 WID The window index number of the window to send to the
6825 printer. !D.Window used by default.
6826
6827 KEYWORD PARAMETERS:
6828
6829 LANDSCAPE If this keyword is set, the output is in Landscape
6830 mode. Otherwise, Portrait mode is used.
6831
6832 PAGESIZE: Set this keyword to a string indicating the type
6833 of PostScript page size you want. Current values are "LETTER",
6834 "LEGAL", and "A4". Default is "LETTER".
6835
6836 RGB_ERROR: Some printers (particularly attached to LINUX machines) cannot
6837 load a 24-bit image. You get this error message:
6838
6839 %Can't set RGB color on an indexed destination.
6840
6841 If this happens to you, set this keyword and the 24-bit image will
6842 be made into a 2D image with color table vectors. Colors are not
6843 quaranteed to be accurate with this method, but in practice it is
6844 not usually too bad.
6845
6846 IDL> PrintWindow, /RGB_Error
6847
6848 MODIFICATION HISTORY:
6849
6850 Written by David W. Fanning based on previous PRINT_IT program. 29 July 2000.
6851 Added RGB_Error keyword. 2 Nov 2004. DWF.
6852 </PRE><P>
6853 <STRONG>(See printwindow.pro)</STRONG><P>
6854 <HR>
6855
6856 <A NAME="PSWINDOW">
6857 <H2>PSWINDOW</H2></A>
6858 <A HREF="#PRINTWINDOW">[Previous Routine]</A>
6859 <A HREF="#PS_BACKGROUND">[Next Routine]</A>
6860 <A HREF="#ROUTINELIST">[List of Routines]</A>
6861 <PRE>
6862 NAME:
6863 PSWINDOW
6864
6865 PURPOSE:
6866
6867 This function is used to calculate the size of a PostScript
6868 window that has the same aspect ratio (ratio of height to
6869 width) as the current display graphics window. It creates
6870 the largest possible PostScript output window with the
6871 desired aspect ratio. This assures that PostScript output
6872 looks similar, if not identical, to normal graphics output
6873 on the display.
6874
6875 AUTHOR:
6876
6877 FANNING SOFTWARE CONSULTING
6878 David Fanning, Ph.D.
6879 1645 Sheely Drive
6880 Fort Collins, CO 80526 USA
6881 Phone: 970-221-0438
6882 E-mail: [email protected]
6883 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
6884
6885 CATEGORY:
6886
6887 Graphics.
6888
6889 CALLING SEQUENCE:
6890
6891 pageInfo = PSWINDOW()
6892
6893 INPUTS:
6894
6895 None.
6896
6897 KEYWORD PARAMETERS:
6898
6899 ASPECTRATIO: Normally the aspect ratio is matched to the
6900 aspect ratio (ratio of height divided by width) of the current
6901 graphics window. However, this keyword can be used to select
6902 a particular aspect ratio for the PostScript window. This should
6903 be a floating point value.
6904
6905 CM: Normally the structure value that is returned from this
6906 function reports its values in inches. Setting this keyword
6907 causes the return values to be in units of centimeters.
6908
6909 EUROPEAN: This keyword is depreciated in favor of METRIC.
6910
6911 FUDGE: A quick way to set symetrical XFUDGE and YFUDGE factors.
6912 If this keyword is set to a value, XFUDGE and YFUDGE keywords are
6913 set to the same value. Fudge factors are used only with some
6914 printers and generally only when output is being sent to the
6915 PRINTER device. (See the description of the XFUDGE and YFUDGE
6916 keywords for additional information.)
6917
6918 LANDSCAPE: Normally, a landscape page is selected if the current
6919 graphics window is wider than it is tall. If you prefer a landscape
6920 aspect window on a Portrait page, set the LANDSCAPE keywword to 0.
6921 Setting this keyword to 1 will result in a landscape page no
6922 matter the size of the current graphics window.
6923
6924 MARGIN: The margin around the edges of the plot. The value must be
6925 a floating point value between 0.0 and 0.35. It is expressed in
6926 normalized coordinate units. The default margin is 0.05.
6927
6928 METRIC: If this keyword is set, the program defaults change
6929 so that the CM keyword is set to 1 and the PAGESIZE keyword is
6930 set to "A4".
6931
6932 PAGESIZE: Set this keyword to a string indicating the type
6933 of PostScript page size you want. Current values are "LETTER",
6934 "LEGAL", and "A4". Default is "LETTER".
6935
6936 PRINTER: Set this keyword if the output will be used to
6937 configure the PRINTER device, rather than the PS device.
6938 (In the PRINTER device, offsets are always calculated from
6939 the lower-left corner of the page and do not rotate in
6940 Landscape mode, as they do with the PS device.) Note that
6941 the PRINTER device is only able to accept these keywords
6942 in IDL 5.1 and higher.
6943
6944 XFUDGE: Printers calculate the offset point from the printable
6945 edge of the paper (sometimes), rather from the corner of the paper.
6946 For example, on my Lexmark printer, both X and Y offsets are
6947 calculated from a point 0.25 inches in from the edge. This keyword
6948 allows you to set a "fudge" factor that will be subtracted from
6949 the XOFFSET that is returned to the user. This allows you to create
6950 output that is centered on the page. The fudge factor should be in
6951 the same units as the returned size and offset values.
6952
6953 YFUDGE: Printers calculate the offset point from the printable
6954 edge of the paper (sometimes), rather from the corner of the paper.
6955 For example, on my Lexmark printer, both X and Y offsets are
6956 calculated from a point 0.25 inches in from the edge. This keyword
6957 allows you to set a "fudge" factor that will be subtracted from
6958 the YOFFSET that is returned to the user. This allows you to create
6959 output that is centered on the page. The fudge factor should be in
6960 the same units as the returned size and offset values.
6961
6962 OUTPUTS:
6963
6964 pageInfo: The output value is a named structure defined like
6965 this:
6966
6967 pageInfo = {PSWINDOW_STRUCT, XSIZE:0.0, YSIZE:0.0, $
6968 XOFSET:0.0, YOFFSET:0.0, INCHES:0, PORTRAIT:0, LANDSCAPE:0}
6969
6970 The units of the four size fields are inches unless the CM
6971 keyword is set.
6972
6973 The output can be used to immediately configure the PostScript
6974 or Printer device, like this:
6975
6976 Set_Plot, 'PS' ; or 'PRINTER'
6977 Device, _Extra=pageInfo
6978
6979 RESTRICTIONS:
6980
6981 The aspect ratio of the current graphics window is calculated
6982 like this:
6983
6984 aspectRatio = FLOAT(!D.Y_VSIZE) / !D.X_VSIZE
6985
6986 EXAMPLE:
6987
6988 To create a PostScript output window with the same aspect
6989 ratio as the curently active display window, type:
6990
6991 pageInfo = PSWINDOW()
6992 SET_PLOT, 'PS'
6993 DEVICE, _Extra=pageInfo
6994
6995 To configure the PRINTER device:
6996
6997 pageInfo = PSWINDOW(/Printer, Fudge=0.25)
6998 SET_PLOT, 'PRINTER'
6999 DEVICE, _Extra=pageInfo
7000
7001 MODIFICATION HISTORY:
7002
7003 Written by: David W. Fanning, November 1996.
7004 Fixed a bug in which the YOFFSET was calculated incorrectly
7005 in Landscape mode. 12 Feb 97.
7006 Took out a line of code that wasn't being used. 14 Mar 97.
7007 Added correct units keyword to return structure. 29 JUN 98. DWF
7008 Fixed a bug in how landscape offsets were calculated. 19 JUL 99. DWF.
7009 Fixed a bug in the way margins were used to conform to my
7010 original conception of the program. 19 JUL 99. DWF.
7011 Added Landscape and Portrait fields to the return structure. 19 JUL 99. DWF.
7012 Added PageSize keyword, changed MARGIN keyword, and completely
7013 rewrote most of the intenal code. 9 FEB 2000. DWF.
7014 Fixed a bug in how I calculated the aspect ratio. 1 MAR 2000. DWF.
7015 Added PRINTER keyword to return proper offset values for the
7016 PRINTER device, where the offset location is not rotated. 1 MAR 2000. DWF.
7017 Added PRINTER fudge factors to take into account that printer offsets are
7018 calculated from the printable area of the paper, rather than the corner
7019 of the paper. 8 AUG 2000. DWF.
7020 Changed the default margin to 0.05 from 0.15. 29 Nov 2004, DWF.
7021 Added EUROPEAN keyword and set LANDSCAPE mode if window wider than higher
7022 as the default if LANDSCAPE is not set. 13 Dec 2010. DWF.
7023 Added ASPECTRATIO keyword to allow user-specified window aspect ratio. 13 Dec 2010. DWF.
7024 Depreciated EUROPEAN keyword in favor of METRIC. 31 Jan 2011. DWF.
7025 Now setting LANDSCAPE=0 if aspect GT 1 and not set otherwise. 19 Feb 2013. DWF.
7026 </PRE><P>
7027 <STRONG>(See pswindow.pro)</STRONG><P>
7028 <HR>
7029
7030 <A NAME="PS_BACKGROUND">
7031 <H2>PS_BACKGROUND</H2></A>
7032 <A HREF="#PSWINDOW">[Previous Routine]</A>
7033 <A HREF="#RANDOMNUMBERGENERATOR">[Next Routine]</A>
7034 <A HREF="#ROUTINELIST">[List of Routines]</A>
7035 <PRE>
7036 :Description:
7037 Provides a device-independent way to set the background color in the PostScript device.
7038
7039 :Categories:
7040 Graphics, Utilities
7041
7042 :Params:
7043 color: in, required, type=string/integer, default='white'
7044 The color that is used for the PostScript background. A polygon of
7045 this color is written to the PostScript file and fills the PostScript
7046 "window".
7047
7048 :Examples:
7049 IDL> PS_Background, 'rose'
7050
7051 :Author:
7052 FANNING SOFTWARE CONSULTING::
7053 David W. Fanning
7054 1645 Sheely Drive
7055 Fort Collins, CO 80526 USA
7056 Phone: 970-221-0438
7057 E-mail: [email protected]
7058 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7059
7060 :History:
7061 Change History::
7062 Written, 17 November 2010. DWF.
7063 Modified to use gcColorFill so that color is done with decomposed color. 24 Dec 2010. DWF.
7064
7065 :Copyright:
7066 Copyright (c) 2010, Fanning Software Consulting, Inc.
7067 </PRE><P>
7068 <STRONG>(See ps_background.pro)</STRONG><P>
7069 <HR>
7070
7071 <A NAME="RANDOMNUMBERGENERATOR">
7072 <H2>RANDOMNUMBERGENERATOR</H2></A>
7073 <A HREF="#PS_BACKGROUND">[Previous Routine]</A>
7074 <A HREF="#RANGEOF">[Next Routine]</A>
7075 <A HREF="#ROUTINELIST">[List of Routines]</A>
7076 <PRE>
7077 NAME:
7078 RANDOMNUMBERGENERATOR
7079
7080 PURPOSE:
7081
7082 Allows the user to obtain a sequence of pseudo-random numbers. The
7083 object maintains the random number generator seed in such a way that
7084 subsequent calls to GetRandomNumbers will guarentee that you don't
7085 get the same random numbers each time you ask for random numbers.
7086
7087 AUTHOR:
7088
7089 FANNING SOFTWARE CONSULTING
7090 David Fanning, Ph.D.
7091 1645 Sheely Drive
7092 Fort Collins, CO 80526 USA
7093 Phone: 970-221-0438
7094 E-mail: [email protected]
7095 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7096
7097 CATEGORY:
7098
7099 Utilities
7100
7101 CALLING SEQUENCE:
7102
7103 Generate three random numbers.
7104
7105 IDL> rng = Obj_New('RandomNumberGenerator', initialSeed)
7106 IDL> numberOfNumbersNeeded = 3
7107 IDL> randomNumbers = rng -> GetRandomNumbers(numberOfNumbersNeeded)
7108 IDL> Print, randomNumbers
7109 0.80952855 0.35878432 0.52150406
7110
7111 Generate a sequence of 8 random digits.
7112 IDL> Print, rng -> GetRandomDigits(8)
7113 21855786
7114
7115 INPUT PARAMETERS FOR INIT METHOD:
7116
7117 initialSeed: The initial seed for the random number generator. If undefined
7118 or absent, the number of seconds after 1 January 1970 is used.
7119
7120 METHODS:
7121
7122 randomNumbers -> GetRandomNumbers(d1, d2, d3, d4 d5, d6, d7, d8)
7123 randomDigits = obj -> GetRandomDigits(numDigets)
7124 obj -> SetSeed, seed
7125
7126 MODIFICATION HISTORY:
7127
7128 Written by David W. Fanning, 13 November 2009.
7129 Added GetRandomDigits method. 7 February 2010. DWF.
7130 Incorrect cleanup of the seed pointer fixed in the CLEANUP procedure.
7131 25 February 2010, DWF.
7132 </PRE><P>
7133 <STRONG>(See randomnumbergenerator__define.pro)</STRONG><P>
7134 <HR>
7135
7136 <A NAME="RANGEOF">
7137 <H2>RANGEOF</H2></A>
7138 <A HREF="#RANDOMNUMBERGENERATOR">[Previous Routine]</A>
7139 <A HREF="#REPMAT">[Next Routine]</A>
7140 <A HREF="#ROUTINELIST">[List of Routines]</A>
7141 <PRE>
7142 NAME:
7143 RANGEOF
7144
7145 PURPOSE:
7146
7147 This function returns the range (i.e., the minimum and maximum value)
7148 of its argument.
7149
7150 AUTHOR:
7151
7152 FANNING SOFTWARE CONSULTING
7153 David Fanning, Ph.D.
7154 1645 Sheely Drive
7155 Fort Collins, CO 80526 USA
7156 Phone: 970-221-0438
7157 E-mail: [email protected]
7158 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
7159
7160 CATEGORY:
7161
7162 Utilities
7163
7164 CALLING SEQUENCE:
7165
7166 range = RangeOf(variable)
7167
7168 INPUTS:
7169
7170 variable: Any numeric IDL variable, except complex.
7171
7172 KEYWORD PARAMETERS:
7173
7174 None.
7175
7176 OUTPUTS:
7177
7178 range: A two-element vector containing the minimum and maximum value
7179 of the variable.
7180
7181 EXAMPLE:
7182
7183 x = RandomU(3L, 10) * 100
7184 Print, RangeOf(x)
7185 3.78892 98.4703
7186
7187 MODIFICATION HISTORY:
7188
7189 Written by: David W. Fanning, 15 February 2009.
7190 </PRE><P>
7191 <STRONG>(See rangeof.pro)</STRONG><P>
7192 <HR>
7193
7194 <A NAME="REPMAT">
7195 <H2>REPMAT</H2></A>
7196 <A HREF="#RANGEOF">[Previous Routine]</A>
7197 <A HREF="#RESOLVE_OBJECT">[Next Routine]</A>
7198 <A HREF="#ROUTINELIST">[List of Routines]</A>
7199 <PRE>
7200 NAME:
7201 REPMAT
7202
7203 PURPOSE:
7204
7205 This program replicates a matrix or array in the style of
7206 the MATLAB RebMat command. The matrix or array is "tiled"
7207 in some integer number of columns and rows.
7208
7209 AUTHOR:
7210
7211 FANNING SOFTWARE CONSULTING
7212 David Fanning, Ph.D.
7213 1645 Sheely Drive
7214 Fort Collins, CO 80526 USA
7215 Phone: 970-221-0438
7216 E-mail: [email protected]
7217 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7218
7219 CATEGORY:
7220
7221 Utilities
7222
7223 CALLING SEQUENCE:
7224
7225 tiledMatrix = RepMat(matrix, ncol, nrow)
7226
7227 AUGUMENTS:
7228
7229 matix: The matrix or array to be tiled.
7230
7231 ncol: The number of columns in the tile.
7232
7233 nrow: The number of rows in the tile.
7234
7235 RETURN_VALUE:
7236
7237 tiledMatrix: If (xdim,ydim) is the size of the original 2D matrix, then the
7238 output matrix is sized (ncol*xdim, nrow*ydim).
7239
7240 KEYWORDS:
7241
7242 None.
7243
7244 EXAMPLE:
7245
7246 IDL> matrix = Reform(Indgen(6) + 1, 3, 2)
7247 IDL> Print, matrix, FORMAT='(3I3)'
7248 1 2 3
7249 4 5 6
7250 IDL> Print, RepMat(matrix, 3, 2), FORMAT='(9I3)'
7251 1 2 3 1 2 3 1 2 3
7252 4 5 6 4 5 6 4 5 6
7253 1 2 3 1 2 3 1 2 3
7254 4 5 6 4 5 6 4 5 6
7255
7256 MODIFICATION HISTORY:
7257
7258 Written by David W. Fanning, 8 May 2009.
7259 Algorithm significantly improved by Ronn Kling, 4 August 2009.
7260 Added line to handle an input matrix with a trailing 1 dimension correctly. DJ 8 March 2011.
7261 </PRE><P>
7262 <STRONG>(See repmat.pro)</STRONG><P>
7263 <HR>
7264
7265 <A NAME="RESOLVE_OBJECT">
7266 <H2>RESOLVE_OBJECT</H2></A>
7267 <A HREF="#REPMAT">[Previous Routine]</A>
7268 <A HREF="#REVERSE_AXES">[Next Routine]</A>
7269 <A HREF="#ROUTINELIST">[List of Routines]</A>
7270 <PRE>
7271 NAME:
7272 RESOLVE_OBJECT
7273
7274 PURPOSE:
7275
7276 The purpose of this function is to resolve object methods in files that have the object
7277 methods in the same file as the object class definition module (i.e., object__define.pro).
7278 It is particularly useful in restoring object methods for objects that have been saved and
7279 are being restored. Restored objects often do not know about their methods unless an object
7280 of the same object class has been previously compiled in that IDL session.
7281
7282 AUTHOR:
7283
7284 FANNING SOFTWARE CONSULTING
7285 David Fanning, Ph.D.
7286 1645 Sheely Drive
7287 Fort Collins, CO 80526 USA
7288 Phone: 970-221-0438
7289 E-mail: [email protected]
7290 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
7291
7292 CATEGORY:
7293
7294 Utilities
7295
7296 CALLING SEQUENCE:
7297
7298 Resolve_Object, obj_or_class
7299
7300 ARGUMENTS:
7301
7302 obj_or_class: Either an IDL object or the class name of an IDL object. Required parameter.
7303
7304 KEYWORDRS:
7305
7306 ROUTINE_INFO: Not strictly used by the user of the program, but this provides a mechanism by which
7307 currently compiled routine names can be checked, so that object code is not being
7308 recompiled unnecessarily. It is actually used internally in the code in a sort of
7309 recursive approach to handling object superclasses.
7310
7311 INFORMATION:
7312
7313 A discussion of this routine, and of the problem the routine was written to address can
7314 be found here:
7315
7316 http://www.idlcoyote.com/tips/saved_objects.html
7317
7318 MODIFICATION HISTORY:
7319
7320 Written by: David W. Fanning, August 20, 2009, and based on code written by JD Smith and
7321 discussed in the article above.
7322 </PRE><P>
7323 <STRONG>(See resolve_object.pro)</STRONG><P>
7324 <HR>
7325
7326 <A NAME="REVERSE_AXES">
7327 <H2>REVERSE_AXES</H2></A>
7328 <A HREF="#RESOLVE_OBJECT">[Previous Routine]</A>
7329 <A HREF="#SAVETOMAIN">[Next Routine]</A>
7330 <A HREF="#ROUTINELIST">[List of Routines]</A>
7331 <PRE>
7332 NAME:
7333 REVERSE_AXES
7334
7335 PURPOSE:
7336
7337 The purpose of this program is to extend the SIMPLE_SURFACE
7338 program to demonstrate how to create reversible axes in
7339 object graphics.
7340
7341 AUTHOR:
7342
7343 FANNING SOFTWARE CONSULTING
7344 David Fanning, Ph.D.
7345 1645 Sheely Drive
7346 Fort Collins, CO 80526 USA
7347 Phone: 970-221-0438
7348 E-mail: [email protected]
7349 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7350
7351 CATEGORY:
7352
7353 Widgets, Object Graphics.
7354
7355 CALLING SEQUENCE:
7356
7357 REVERSE_AXES, data, x, y
7358
7359 REQUIRED INPUTS:
7360
7361 None. Fake data will be used if no data is supplied in call.
7362
7363 OPTIONAL INPUTS
7364
7365 data: A 2D array of surface data.
7366
7367 x: A vector of X data values.
7368
7369 y: A vector of Y data values.
7370
7371 OPTIONAL KEYWORD PARAMETERS:
7372
7373 EXACT: Set this keyword to get exact axis scaling.
7374
7375 _EXTRA: This keyword collects otherwise undefined keywords that are
7376 passed to the surface initialization routine.
7377
7378 GROUP_LEADER: The group leader for this program. When the group leader
7379 is destroyed, this program will be destroyed.
7380
7381 LANDSCAPE: Set this keyword if you are printing in landscape mode. The
7382 default is Portrait mode. The Landscape keyword on the PRINTER object
7383 is set, but not all printers will honor this keyword setting. If yours
7384 does not, set Landscape mode in the Printer Setup dialog.
7385
7386 VECTOR: Set this keyword if you want vector printing (as opposed to
7387 the default bitmap printing).
7388
7389 XTITLE: A string used as the X title of the plot.
7390
7391 YTITLE: A string used as the Y title of the plot.
7392
7393 ZTITLE: A string used as the Z title of the plot.
7394
7395 COMMON BLOCKS:
7396
7397 None.
7398
7399 EXAMPLE:
7400
7401 To use this program with your 2D data, type:
7402
7403 IDL> Reverse_Axes, data
7404
7405 MODIFICATION HISTORY:
7406
7407 Written by: David Fanning, October 2001.
7408 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
7409 </PRE><P>
7410 <STRONG>(See reverse_axes.pro)</STRONG><P>
7411 <HR>
7412
7413 <A NAME="SAVETOMAIN">
7414 <H2>SAVETOMAIN</H2></A>
7415 <A HREF="#REVERSE_AXES">[Previous Routine]</A>
7416 <A HREF="#SCALEMODIS">[Next Routine]</A>
7417 <A HREF="#ROUTINELIST">[List of Routines]</A>
7418 <PRE>
7419 NAME:
7420 SAVETOMAIN
7421
7422 PURPOSE:
7423
7424 This is used primarily in debugging mode to save a variable to
7425 the main IDL level for later inspection.
7426
7427 AUTHOR:
7428
7429 FANNING SOFTWARE CONSULTING
7430 David Fanning, Ph.D.
7431 1645 Sheely Drive
7432 Fort Collins, CO 80526 USA
7433 Phone: 970-221-0438
7434 E-mail: [email protected]
7435 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
7436
7437 CATEGORY:
7438
7439 Utilities
7440
7441 CALLING SEQUENCE:
7442
7443 SaveToMain, variable, nameOfVariable
7444
7445 ARGUMENTS:
7446
7447 variable: The variable you wish to save at the main IDL level.
7448
7449 nameOfVariable: The name of the variable at the main IDL level. If undefined,
7450 the variable will have the same name as the variable that was
7451 used as the variable argument.
7452
7453 KEYWORDRS:
7454
7455 None.
7456
7457 MODIFICATION HISTORY:
7458
7459 Written by: David W. Fanning, 2 July 2009.
7460 </PRE><P>
7461 <STRONG>(See savetomain.pro)</STRONG><P>
7462 <HR>
7463
7464 <A NAME="SCALEMODIS">
7465 <H2>SCALEMODIS</H2></A>
7466 <A HREF="#SAVETOMAIN">[Previous Routine]</A>
7467 <A HREF="#SCROLLWINDOW">[Next Routine]</A>
7468 <A HREF="#ROUTINELIST">[List of Routines]</A>
7469 <PRE>
7470 NAME:
7471 SCALEMODIS
7472
7473 PURPOSE:
7474
7475 MODIS corrected reflectance images often appear drab when initially processed
7476 and displayed on a computer using BYTSCL. In fact, the resulting true-color
7477 images look nothing like the images you can find on the MODIS Rapid Response
7478 web page (http://rapidfire.sci.gsfc.nasa.gov/gallery/). After poking around on
7479 the Internet for awhile, I discovered that the Rapid Response Team doesn't use
7480 BYTSCL to prepare the images. Rather, they selectively scale portions of the
7481 reflectance image, using a piecewise scaling with different slopes. This program
7482 implements this Rapid Response Team algorithm.
7483
7484 AUTHOR:
7485
7486 FANNING SOFTWARE CONSULTING
7487 David Fanning, Ph.D.
7488 1645 Sheely Drive
7489 Fort Collins, CO 80526 USA
7490 Phone: 970-221-0438
7491 E-mail: [email protected]
7492 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
7493
7494 CATEGORY:
7495
7496 Graphics
7497
7498 CALLING SEQUENCE:
7499
7500 scaledBand = ScaleModis(red, green, blue)
7501
7502 ARGUMENTS:
7503
7504 red: A two-dimensional array representing the corrected reflectance
7505 values of a MODIS image. This is a required parameter. If the
7506 green and blue parameters are also used, this parameter will
7507 represent the red band of a RGB 24-bit scaled image that is returned.
7508
7509 green: If the three parameters--red, green, and blue--are present, the returned
7510 array is a 24-bit true-color image, scaled appropriately. This parameter
7511 is used as the green band in such an image. The parameter is a two-dimensional
7512 array of corrected reflectance values.
7513
7514 blue: If the three parameters--red, green, and blue--are present, the returned
7515 array is a 24-bit true-color image, scaled appropriately. This parameter
7516 is used as the blue band in such an image. The parameter is a two-dimensional
7517 array of corrected reflectance values.
7518
7519 KEYWORD PARAMETERS:
7520
7521 RANGE: A two-dimensional array that the input bands are first scaled into, prior to
7522 the differential scaling using the MODIS Rapid Response algorithm. The default
7523 input range is [-0.01, 1.10]. These values will be used to set the MIN and MAX
7524 keywords for the BYTSCL command in the initial scaling of the input bands.
7525
7526 CLOUD: The MODIS Rapid Response team uses a slightly different scaling algorithm when
7527 the idea is to emphasize clouds in a MODIS scene. Set this keyword to use the
7528 alternate cloud scaling algorithm.
7529
7530 OUTPUTS:
7531
7532 scaledBand: If a single 2D array is passed as the argument, then scaledBand is the scaled
7533 2D output array. If all three arguments are passed to the program, then scaledBand
7534 is a scaled 24-bit image that represents a true-color or false color representation
7535 of the three input bands.
7536
7537 MODIFICATION HISTORY:
7538
7539 Written by: David W. Fanning, July 2009, using the IDL programs MODIS_FALSE_COLOR and
7540 and SCALE_IMAGE for inspiration. I found these programs on the Internet when poking
7541 around MODIS web pages. I suspect, but I am not sure, these programs were originally
7542 written by Liam Gumley.
7543 Minor changes to the ScaleIt function to be sure partitioning is done correctly. 5 Aug 2009. DWF.
7544 </PRE><P>
7545 <STRONG>(See scalemodis.pro)</STRONG><P>
7546 <HR>
7547
7548 <A NAME="SCROLLWINDOW">
7549 <H2>SCROLLWINDOW</H2></A>
7550 <A HREF="#SCALEMODIS">[Previous Routine]</A>
7551 <A HREF="#SDEVSCL">[Next Routine]</A>
7552 <A HREF="#ROUTINELIST">[List of Routines]</A>
7553 <PRE>
7554 NAME:
7555 SCROLLWINDOW
7556
7557 PURPOSE:
7558
7559 This procedure is more or less a drop-in replacement for the WINDOW
7560 command. The main difference is that if the requested window size
7561 is larger then the current display size, the window is created in a
7562 base widget with scroll bars so the user can scroll around
7563 the larger window. Use the WID keyword to pass in the window
7564 index number of the window you want to create (a small change
7565 from the WINDOW syntax). If the program can create a window with
7566 this window index number, it will. Otherwise, this keyword will
7567 return the window index number of the window that was actually
7568 created.
7569
7570 I use ScrollWindow to create windows that I can view both on
7571 my large monitor at work and on my smaller laptop monitor when
7572 I travel.
7573
7574 AUTHOR:
7575
7576 FANNING SOFTWARE CONSULTING
7577 David Fanning, Ph.D.
7578 1645 Sheely Drive
7579 Fort Collins, CO 80526 USA
7580 Phone: 970-221-0438
7581 E-mail: [email protected]
7582 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
7583
7584 CATEGORY:
7585
7586 Graphics
7587
7588 CALLING SEQUENCE:
7589
7590 ScrollWindow, xsize, ysize
7591
7592 ARGUMENTS:
7593
7594 xsize: The x size of the graphics window. By default, 640.
7595
7596 ysize: The y size of the graphics window. By default, 512.
7597
7598 KEYWORD PARAMETERS:
7599
7600 FREE: Get a window with a free or unused window index number.
7601 This is *always* done with a scrollable window. The window
7602 index number of the window is returned in the WID keyword.
7603
7604 PIXMAP: Set to create a pixmap window. In this case, no scrollable
7605 window is possible. A normal IDL graphics window is
7606 always created.
7607
7608 SIZEFRAC: Make the window this fraction of the screen dimensions.
7609 A number between 0.0 and 1.0
7610
7611 TITLE: The title string that is displayed on the window.
7612
7613 WID: The window index number. If supplied as an IDL variable,
7614 this can be both an input and an output keyword. If a
7615 window with this window index number can be created, it
7616 is. Otherwise, this varible upon exit from the program
7617 contains the window index number of the graphics window
7618 that was created.
7619
7620 XPOS: The x offset of the upper-left corner of the window.
7621
7622 XSIZE: The same as the xsize argument. Provided so ScrollWindow
7623 can be a drop-in replacement for the Window command.
7624
7625 YPOS: The y offset of the upper-left corner of the window.
7626
7627 YSIZE: The same as the ysize argument. Provided so ScrollWindow
7628 can be a drop-in replacement for the Window command.
7629
7630
7631
7632 EXAMPLE:
7633
7634 ScrollWindow, XSIZE=800, YSIZE=400 ; Produces normal IDL graphics window.
7635 ScrollWindow, XSIZE=1800, YSIZE=1200 ; Produces a scrollable graphics window.
7636
7637 MODIFICATION HISTORY:
7638
7639 Written by: David W. Fanning, 25 March 2009
7640 Added SIZEFRACTION keyword, Mats Löfdahl, 25 November 2012.
7641 </PRE><P>
7642 <STRONG>(See scrollwindow.pro)</STRONG><P>
7643 <HR>
7644
7645 <A NAME="SDEVSCL">
7646 <H2>SDEVSCL</H2></A>
7647 <A HREF="#SCROLLWINDOW">[Previous Routine]</A>
7648 <A HREF="#SELECT_OBJECTS">[Next Routine]</A>
7649 <A HREF="#ROUTINELIST">[List of Routines]</A>
7650 <PRE>
7651 This is a utility routine to perform standard deviation scaling
7652 on image arrays. The user defines a multiple of the standard
7653 deviation and this is used with the standard deviation of the
7654 pixels in the image to create a threshold for linear scaling.
7655 Use the EXCLUDE keyword to exclude a particular value from
7656 the standard deviation calculation.
7657
7658 :Categories:
7659 Utilities, Graphics
7660
7661 :Params:
7662 image: in, required, type=numeric
7663 The image array that is to be scaled.
7664
7665 :Keywords:
7666 exclude: in, optional, type=numeric
7667 Set this keyword to a value in the image array that is to be excluded from the
7668 standard deviation calculation. Normally, this would be the backgroud value of
7669 the image, if there is a background.
7670 multiplier: in, optional, type=float, default=2.0
7671 The standard deviation of the image pixels is computed and then
7672 multiplied by the multiplier factor to produce upper and lower
7673 thresholds for the linear scaling of the image by subtracting
7674 or adding this value to the mean value of the image. The image
7675 is linearly scaled between these two threshold values.
7676 negative: in, optional, type=boolean
7677 Set this keyword to return the "negative" or reverse of the image scaling.
7678 omax: in, optional, type=byte, default=255
7679 Normally, the image is scaled into the range of 0 to 255. Setting the
7680 OMIN and OMAX keywords can change this scaling.
7681 omin: in, optional, type=byte, default=0
7682 Normally, the image is scaled into the range of 0 to 255. Setting the
7683 OMIN and OMAX keywords can change this scaling.
7684 threshold: out, optional, type=float
7685 A two-element array that contains the minimum and maximum thresholds, respectively,
7686 that were calculated for the scaling.
7687
7688 :Examples:
7689 To display an image with standard deviation scaling::
7690 image = cgDemoData(5)
7691 cgDisplay, 256*3, 256
7692 !P.Multi = [0,3,1]
7693 cgImage, image
7694 cgImage, SDevScl(image)
7695 cgImage, SDevScl(image, Exclude=0)
7696 !P.Multi = 0
7697
7698 :Author:
7699 FANNING SOFTWARE CONSULTING::
7700 David W. Fanning
7701 1645 Sheely Drive
7702 Fort Collins, CO 80526 USA
7703 Phone: 970-221-0438
7704 E-mail: [email protected]
7705 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7706
7707 :History:
7708 Change History::
7709 Written by: David W. Fanning, 5 June 2012.
7710
7711 :Copyright:
7712 Copyright (c) 2012, Fanning Software Consulting, Inc.
7713 </PRE><P>
7714 <STRONG>(See sdevscl.pro)</STRONG><P>
7715 <HR>
7716
7717 <A NAME="SELECT_OBJECTS">
7718 <H2>SELECT_OBJECTS</H2></A>
7719 <A HREF="#SDEVSCL">[Previous Routine]</A>
7720 <A HREF="#SETDEFAULTVALUE">[Next Routine]</A>
7721 <A HREF="#ROUTINELIST">[List of Routines]</A>
7722 <PRE>
7723 NAME:
7724 SELECT_OBJECTS
7725
7726 PURPOSE:
7727 The purpose of this program is to demonstrate how to select
7728 and move objects in an object graphics window. Once the objects
7729 appear in the window, use your mouse to select the objects and
7730 move them in the window. The window is resizeable.
7731
7732 AUTHOR:
7733 FANNING SOFTWARE CONSULTING
7734 David Fanning, Ph.D.
7735 1645 Sheely Drive
7736 Fort Collins, CO 80526 USA
7737 Phone: 970-221-0438
7738 E-mail: [email protected]
7739 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7740
7741 CATEGORY:
7742 Object Graphics.
7743
7744 CALLING SEQUENCE:
7745 SELECT_OBJECTS
7746
7747 REQUIRED INPUTS:
7748 None.
7749
7750 KEYWORD PARAMETERS:
7751 None.
7752
7753 COMMON BLOCKS:
7754 None.
7755
7756 SIDE EFFECTS:
7757 None.
7758
7759 RESTRICTIONS:
7760 Requires VCOLORBAR from the Coyote Library:
7761 http://www.idlcoyote.com/programs/vcolorbar__define.pro.
7762
7763 EXAMPLE:
7764 Select_Objects
7765
7766 MODIFICATION HISTORY:
7767 Written by David Fanning, 21 September 98.
7768 Added the ability to shrink and expand the objects. 27 Sept 98. DWF.
7769 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
7770 </PRE><P>
7771 <STRONG>(See select_objects.pro)</STRONG><P>
7772 <HR>
7773
7774 <A NAME="SETDEFAULTVALUE">
7775 <H2>SETDEFAULTVALUE</H2></A>
7776 <A HREF="#SELECT_OBJECTS">[Previous Routine]</A>
7777 <A HREF="#SHARPEN">[Next Routine]</A>
7778 <A HREF="#ROUTINELIST">[List of Routines]</A>
7779 <PRE>
7780 This procedure sets default values for positional and keyword arguments to
7781 IDL procedures and functions.
7782
7783 :Categories:
7784 Utilities
7785
7786 :Params:
7787 argument: in, required
7788 The augument variable you are setting the default value of. If this variable
7789 is undefined, the `defaultValue` will be assigned to it. Otherwise, the argument
7790 variable will not change.
7791 defaultvalue: in, required
7792 The default value that will be assigned to the argument variable ONLY if the argument
7793 variable is undefined. If this variable is undefined, the argument variable will
7794 be treated as if the BOOLEAN keyword had been set.
7795
7796 :Keywords:
7797 boolean: in, optional, type=integer
7798 If this keyword is set, the argument value will always be forced to return with a
7799 value of 0 or 1.
7800
7801 :Examples:
7802 Here is how to use this program::
7803
7804 FUNCTION Action, arg1, arg2, MULTIPLY=multiply
7805
7806 SetDefaultValue, arg1, 1
7807 SetDefaultValue, arg2, 2
7808 SetDefaultValue, multiply, 1, /BOOLEAN
7809
7810 IF multiply THEN RETURN, arg1 * arg2 ELSE RETURN, arg1 + arg2
7811
7812 END
7813
7814 :Author:
7815 FANNING SOFTWARE CONSULTING::
7816 David W. Fanning
7817 1645 Sheely Drive
7818 Fort Collins, CO 80526 USA
7819 Phone: 970-221-0438
7820 E-mail: [email protected]
7821 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7822
7823 :History:
7824 Change History::
7825 Written by: David W. Fanning, November 26, 2008, from suggestion by Carsten Lechte on
7826 IDL newsgroup on this date.
7827 Made a change to the way the BOOLEAN keyword works. Now argument is set to BOOLEAN before
7828 return, if required. 3 Dec 2008. DWF.
7829
7830 :Copyright:
7831 Copyright (c) 2008-2014, Fanning Software Consulting, Inc.
7832 </PRE><P>
7833 <STRONG>(See setdefaultvalue.pro)</STRONG><P>
7834 <HR>
7835
7836 <A NAME="SHARPEN">
7837 <H2>SHARPEN</H2></A>
7838 <A HREF="#SETDEFAULTVALUE">[Previous Routine]</A>
7839 <A HREF="#SORT_ND">[Next Routine]</A>
7840 <A HREF="#ROUTINELIST">[List of Routines]</A>
7841 <PRE>
7842 NAME:
7843 Sharpen
7844
7845 PURPOSE:
7846
7847 This function sharpens an image using a Laplacian kernel.
7848 The final result is color adjusted to match the histogram
7849 of the input image.
7850
7851 AUTHOR:
7852
7853 FANNING SOFTWARE CONSULTING
7854 David Fanning, Ph.D.
7855 1645 Sheely Drive
7856 Fort Collins, CO 80526 USA
7857 Phone: 970-221-0438
7858 E-mail: [email protected]
7859 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7860
7861 CATEGORY:
7862
7863 Image Processing
7864
7865 CALLING SEQUENCE:
7866
7867 sharp_image = Sharpen(image)
7868
7869 INPUTS:
7870
7871 image - The input image to be sharpened. Assumed to be a 2D byte array.
7872
7873 OUTPUTS:
7874
7875 sharp_image - The sharpened image.
7876
7877 INPUT KEYWORDS:
7878
7879 KERNEL -- By default the image is convolved with this 3-by-3 Laplacian kernel:
7880 [ [-1, -1, -1], [-1, +8, -1], [-1, -1, -1] ]. You can pass in any kernel
7881 of odd width. The filtered image is added back to the original image to provide
7882 the sharpening effect.
7883
7884 DISPLAY -- If this keyword is set a window is opened and the details of the sharpening
7885 process are displayed.
7886
7887 OUTPUT KEYWORDS:
7888
7889 None.
7890
7891 DEPENDENCIES:
7892
7893 None.
7894
7895 METHOD:
7896
7897 This function is based on the Laplacian kernel sharpening method on pages 128-131
7898 of Digital Image Processing, 2nd Edition, Rafael C. Gonzalez and Richard E. Woods,
7899 ISBN 0-20-118075-8.
7900
7901 EXAMPLE:
7902
7903 There is an example program at the end of this file.
7904
7905 MODIFICATION HISTORY:
7906
7907 Written by David W. Fanning, January 2003.
7908 Updated slightly to use Coyote Library routines. 3 Dec. 2010. DWF.
7909 Modified the example to work with cgImage. 29 March 2011. DWF.
7910 </PRE><P>
7911 <STRONG>(See sharpen.pro)</STRONG><P>
7912 <HR>
7913
7914 <A NAME="SORT_ND">
7915 <H2>SORT_ND</H2></A>
7916 <A HREF="#SHARPEN">[Previous Routine]</A>
7917 <A HREF="#STATIONPLOT">[Next Routine]</A>
7918 <A HREF="#ROUTINELIST">[List of Routines]</A>
7919 <PRE>
7920 NAME:
7921 SORT_ND
7922
7923 PURPOSE:
7924
7925 Efficiently perform an N-dimensional sort along any dimension
7926 of an array.
7927
7928 CALLING SEQUENCE:
7929
7930 inds=sort_nd(array,dimension)
7931
7932 INPUTS:
7933
7934 array: An array of at least 2 dimensions to sort.
7935
7936 dimension: The dimension along which to sort, starting at 1
7937 (1:rows, 2:columns, ...).
7938
7939 OUTPUTS:
7940
7941 inds: An index array with the same dimensions as the input
7942 array, containing the (1D) sorted indices. Can be used
7943 directly to index the arary (ala SORT).
7944
7945 EXAMPLE:
7946
7947 a=randomu(sd,5,4,3,2)
7948 sorted=a[sort_nd(a,2)]
7949
7950 SEE ALSO:
7951
7952 HISTOGRAM
7953
7954 MODIFICATION HISTORY:
7955
7956 Tue Aug 22 15:51:12 2006, J.D. Smith <[email protected]>
7957
7958 Written, based on discussion on c.l.i-p, 08/2006.
7959
7960 </PRE><P>
7961 <STRONG>(See sort_nd.pro)</STRONG><P>
7962 <HR>
7963
7964 <A NAME="STATIONPLOT">
7965 <H2>STATIONPLOT</H2></A>
7966 <A HREF="#SORT_ND">[Previous Routine]</A>
7967 <A HREF="#STR_SIZE">[Next Routine]</A>
7968 <A HREF="#ROUTINELIST">[List of Routines]</A>
7969 <PRE>
7970 NAME:
7971 STATIONPLOT
7972
7973 PURPOSE:
7974
7975 This is routine for drawing station plots on a map or other display.
7976 Normally, this routine is used in conjunction with WINDBARB.
7977
7978 AUTHOR:
7979
7980 FANNING SOFTWARE CONSULTING
7981 David Fanning, Ph.D.
7982 1645 Sheely Drive
7983 Fort Collins, CO 80526 USA
7984 Phone: 970-221-0438
7985 E-mail: [email protected]
7986 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
7987
7988 CATEGORY:
7989
7990 Graphics.
7991
7992 CALLING SEQUENCE:
7993
7994 StationPlot, x, y
7995
7996 REQUIRED INPUTS:
7997
7998 x: The X location of the center of the station plot, expressed in data coordinates.
7999
8000 y: The Y location of the center of the station plot, expressed in data coordinates.
8001
8002 KEYWORDS:
8003
8004 COLOR: The name of the color to draw the station plot in. May be a vector
8005 the same length as X. Colors are those available in cgColor.
8006
8007 RADIUS: The radius of the station plot circle in normalized coordinates.
8008
8009 RESTRICTIONS:
8010
8011 Requires cgColor from the Coyote Library:
8012
8013 http://www.idlcoyote.com/programs/cgColor.pro
8014
8015 EXAMPLE:
8016
8017 seed = -3L
8018 lon = Randomu(seed, 20) * 360 - 180
8019 lat = Randomu(seed, 20) * 180 - 90
8020 speed = Randomu(seed, 20) * 100
8021 direction = Randomu(seed, 20) * 180 + 90
8022 Erase, cgColor('Ivory', !P.Background)
8023 Map_Set, /Cylindrical,Position=[0.1, 0.1, 0.9, 0.9], Color=cgColor('Steel Blue'), /NoErase
8024 Map_Grid, Color=cgColor('Charcoal', !D.Table_Size-2)
8025 Map_Continents, Color=cgColor('Sea Green', !D.Table_Size-3)
8026 StationPlot, lon, lat, Color='Indian Red'
8027
8028 MODIFICATION HISTORY:
8029
8030 Written by: David W. Fanning, 20 May 2003, based on TVCircle from the
8031 NASA Astonomy Library.
8032 Added THICK keyword. 23 February 2005. DWF.
8033
8034 </PRE><P>
8035 <STRONG>(See stationplot.pro)</STRONG><P>
8036 <HR>
8037
8038 <A NAME="STR_SIZE">
8039 <H2>STR_SIZE</H2></A>
8040 <A HREF="#STATIONPLOT">[Previous Routine]</A>
8041 <A HREF="#TEXTBOX">[Next Routine]</A>
8042 <A HREF="#ROUTINELIST">[List of Routines]</A>
8043 <PRE>
8044 NAME:
8045 STR_SIZE
8046
8047 PURPOSE:
8048
8049 The purpose of this function is to return the proper
8050 character size to make a specified string a specifed
8051 width in a window. The width is specified in normalized
8052 coordinates. The function is extremely useful for sizing
8053 strings and labels in resizeable graphics windows.
8054
8055 AUTHOR:
8056
8057 FANNING SOFTWARE CONSULTING
8058 David Fanning, Ph.D.
8059 1645 Sheely Drive
8060 Fort Collins, CO 80526 USA
8061 Phone: 970-221-0438
8062 E-mail: [email protected]
8063 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
8064
8065 CATEGORY:
8066
8067 Graphics Programs, Widgets.
8068
8069 CALLING SEQUENCE:
8070
8071 thisCharSize = STR_SIZE(thisSting, targetWidth)
8072
8073 INPUTS:
8074
8075 thisString: This is the string that you want to make a specifed
8076 target size or width.
8077
8078 OPTIONAL INPUTS:
8079
8080 targetWidth: This is the target width of the string in normalized
8081 coordinates in the current graphics window. The character
8082 size of the string (returned as thisCharSize) will be
8083 calculated to get the string width as close as possible to
8084 the target width. The default is 0.25.
8085
8086 KEYWORD PARAMETERS:
8087
8088 INITSIZE: This is the initial size of the string. Default is 1.0.
8089
8090 STEP: This is the amount the string size will change in each step
8091 of the interative process of calculating the string size.
8092 The default value is 0.05.
8093
8094 XPOS: X position of the output test string. This can be
8095 used on the Postscript device, where no pixmap windows are
8096 available and where therefore the test strings would appear on
8097 the printable area. Default is 0.5 on most devices. If !D.NAME
8098 is PS, the default is 2.0 to draw the test string out of the
8099 drawable window area.
8100
8101 YPOS: Y position of the output test string. This can be
8102 used on the Postscript device, where no pixmap windows are
8103 available and where therefore the test strings would appear on
8104 the printable area. Default is 0.5 on most devices. If !D.NAME
8105 is PS, the default is 2.0 to draw the test string out of the
8106 drawable window area.
8107
8108 OUTPUTS:
8109
8110 thisCharSize: This is the size the specified string should be set
8111 to if you want to produce output of the specified target
8112 width. The value is in standard character size units where
8113 1.0 is the standard character size.
8114
8115 EXAMPLE:
8116
8117 To make the string "Happy Holidays" take up 30% of the width of
8118 the current graphics window, type this:
8119
8120 XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
8121 CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
8122
8123 MODIFICATION HISTORY:
8124
8125 Written by: David Fanning, 17 DEC 96.
8126 Added a scaling factor to take into account the aspect ratio
8127 of the window in determing the character size. 28 Oct 97. DWF
8128 Added check to be sure hardware fonts are not selected. 29 April 2000. DWF.
8129 Added a pixmap to get proper scaling in skinny windows. 16 May 2000. DWF.
8130 Forgot I can't do pixmaps in all devices. :-( Fixed. 7 Aug 2000. DWF.
8131 Added support of PostScript at behest of Benjamin Hornberger. 11 November 2004. DWF.
8132 Cleaned up the code a bit. 28 Feb 2011. DWF.
8133 Fixed non-square window algorithm to reflect my original intentions. 10 June 2011.
8134 </PRE><P>
8135 <STRONG>(See str_size.pro)</STRONG><P>
8136 <HR>
8137
8138 <A NAME="TEXTBOX">
8139 <H2>TEXTBOX</H2></A>
8140 <A HREF="#STR_SIZE">[Previous Routine]</A>
8141 <A HREF="#TEXTLINEFORMAT">[Next Routine]</A>
8142 <A HREF="#ROUTINELIST">[List of Routines]</A>
8143 <PRE>
8144 NAME:
8145 TEXTBOX
8146
8147 PURPOSE:
8148
8149 This function allows the user to type some text in a
8150 pop-up dialog widget and have it returned to the program.
8151 This is an example of a Pop-Up Dialog Widget.
8152
8153 AUTHOR:
8154
8155 FANNING SOFTWARE CONSULTING
8156 David Fanning, Ph.D.
8157 1645 Sheely Drive
8158 Fort Collins, CO 80526 USA
8159 Phone: 970-221-0438
8160 E-mail: [email protected]
8161 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8162
8163 CATEGORY:
8164
8165 Utility, Widgets
8166
8167 CALLING SEQUENCE:
8168
8169 thetext = TextBox()
8170
8171 INPUTS:
8172
8173 None.
8174
8175 KEYWORD PARAMETERS:
8176
8177 CANCEL: An output parameter. If the user kills the widget or clicks the Cancel
8178 button this keyword is set to 1. It is set to 0 otherwise. It
8179 allows you to determine if the user canceled the dialog without
8180 having to check the validity of the answer.
8181
8182 theText = TextBox(Title='Provide Phone Number...', Label='Number:', Cancel=cancelled)
8183 IF cancelled THEN Return
8184
8185 GROUP_LEADER: The widget ID of the group leader of this pop-up
8186 dialog. This should be provided if you are calling
8187 the program from within a widget program:
8188
8189 thetext = TextBox(Group_Leader=event.top)
8190
8191 If a group leader is not provided, an unmapped top-level base widget
8192 will be created as a group leader.
8193
8194 LABEL: A string the appears to the left of the text box.
8195
8196 TITLE: The title of the top-level base. If not specified, the
8197 string 'Provide Input:' is used by default.
8198
8199 VALUE: A string variable that is the intial value of the textbox. By default, a null string.
8200
8201 XSIZE: The size of the text widget in pixel units. By default, 200.
8202
8203 OUTPUTS:
8204
8205 theText: The string of characters the user typed in the
8206 text widget. No error checking is done.
8207
8208 RESTRICTIONS:
8209
8210 The widget is destroyed if the user clicks on either button or
8211 if they hit a carriage return (CR) in the text widget. The
8212 text is recorded if the user hits the ACCEPT button or hits
8213 a CR in the text widget.
8214
8215 MODIFICATION HISTORY:
8216
8217 Written by: David W. Fanning, December 20, 2001.
8218 Added VALUE keyword to set the initial value of the text box. 4 Nov 2002. DWF.
8219 </PRE><P>
8220 <STRONG>(See textbox.pro)</STRONG><P>
8221 <HR>
8222
8223 <A NAME="TEXTLINEFORMAT">
8224 <H2>TEXTLINEFORMAT</H2></A>
8225 <A HREF="#TEXTBOX">[Previous Routine]</A>
8226 <A HREF="#TEXTURE_SURFACE">[Next Routine]</A>
8227 <A HREF="#ROUTINELIST">[List of Routines]</A>
8228 <PRE>
8229 NAME:
8230 TextLineFormat
8231
8232 PURPOSE:
8233
8234 This is a utility program for taking a line of text and shortening
8235 it to a defined maximum length. The result of the function is a string
8236 array in which no line of text in the string array is longer than the maximum
8237 length. The text is broken into "words" by white space. The algorithm is
8238 modified slightly if there are LF (line feeds) in the text, or if any single
8239 word in the text is too large to fit on a line.
8240
8241 AUTHOR:
8242
8243 FANNING SOFTWARE CONSULTING
8244 David Fanning, Ph.D.
8245 1645 Sheely Drive
8246 Fort Collins, CO 80526 USA
8247 Phone: 970-221-0438
8248 E-mail: [email protected]
8249 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8250
8251 CATEGORY:
8252
8253 Utilities
8254
8255 CALLING SEQUENCE:
8256
8257 formattedText = TextLineFormat(theText)
8258
8259 INPUTS:
8260
8261 theText: The line of text that is to be formatted.
8262
8263 KEYWORDS:
8264
8265 LENGTH: The maximum line length allowed in the resulting text array.
8266 Set to 60 characters by default. Lines greater than length
8267 can be permitted if Line Feeds (ASCII 10B) are found
8268 in the text or single words are too large to fit on a line.
8269
8270 MODIFICATION HISTORY:
8271
8272 Written by David Fanning, June 2005.
8273 Fixed a small problem with cumulative total not counting spaces between
8274 words. Changed the default size to 60. DWF. 18 August 2005.
8275 Added check for LF in text to accommodate reading netCDF file attributes.
8276 If LF are present, I break on these, and return. 15 Feb 2008. DWF.
8277 Better handling of lines with no white space in them for breaking. 23 March 2009. DWF.
8278 </PRE><P>
8279 <STRONG>(See textlineformat.pro)</STRONG><P>
8280 <HR>
8281
8282 <A NAME="TEXTURE_SURFACE">
8283 <H2>TEXTURE_SURFACE</H2></A>
8284 <A HREF="#TEXTLINEFORMAT">[Previous Routine]</A>
8285 <A HREF="#TRANSFORM_VOLUME">[Next Routine]</A>
8286 <A HREF="#ROUTINELIST">[List of Routines]</A>
8287 <PRE>
8288 NAME:
8289 TEXTURE_SURFACE
8290
8291 PURPOSE:
8292
8293 The purpose of this program is to demonstrate how to
8294 create a simple surface plot with an image applied as
8295 a texture in object graphics.
8296
8297 AUTHOR:
8298
8299 FANNING SOFTWARE CONSULTING
8300 David Fanning, Ph.D.
8301 1645 Sheely Drive
8302 Fort Collins, CO 80526 USA
8303 Phone: 970-221-0438
8304 E-mail: [email protected]
8305 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8306
8307 CATEGORY:
8308
8309 Widgets, Object Graphics.
8310
8311 CALLING SEQUENCE:
8312
8313 TEXTURE_SURFACE, data, x, y, Image=image
8314
8315 REQUIRED INPUTS:
8316
8317 None. Fake data will be used if no data is supplied in call.
8318
8319 OPTIONAL INPUTS
8320
8321 data: A 2D array of surface data.
8322
8323 x: A vector of X data values.
8324
8325 y: A vector of Y data values.
8326
8327 OPTIONAL KEYWORD PARAMETERS:
8328
8329 BORDERCOLOR : A three element array [R, G, B] describing the color
8330 used to draw the non-textured part of the surface if POSITION is
8331 specified.
8332
8333 COLORTABLE: The number of an IDL color table to use for the image
8334 texture. Used only if the supplied image is 2D. Ignored otherwise.
8335
8336 EXACT: Set this keyword to get exact axis scaling.
8337
8338 _EXTRA: This keyword collects otherwise undefined keywords that are
8339 passed to the surface initialization routine.
8340
8341 GROUP_LEADER: The group leader for this program. When the group leader
8342 is destroyed, this program will be destroyed.
8343
8344 IMAGE: An 8-bit or 24-bit image you wish to use for the image texture.
8345
8346 LANDSCAPE: Set this keyword if you are printing in landscape mode. The
8347 default is Portrait mode. The Landscape keyword on the PRINTER object
8348 is set, but not all printers will honor this keyword setting. If yours
8349 does not, set Landscape mode in the Printer Setup dialog.
8350
8351 POSITION: A four element array of the form [x1, y1, x2, y2] that will
8352 position the image with its lower-left corner at (x1,y1) and its upper-
8353 right corner at (x2,y2) in the device coordinate system of the surface.
8354 In other words, if my surface is a 41 by 41 array, and I want the image
8355 positioned with lower-left at (5,10) and upper-right at (25,18), then
8356 I call the program like this: Texture_Surface, Position=[5, 10, 25, 18].
8357
8358 VECTOR: Set this keyword if you want vector printing (as opposed to
8359 the default bitmap printing).
8360
8361 XTITLE: A string used as the X title of the plot.
8362
8363 YTITLE: A string used as the Y title of the plot.
8364
8365 ZSCALE: A number larger than or equal to 0.001 and less than or equal to 1.0 that affects Z scaling.
8366
8367 ZTITLE: A string used as the Z title of the plot.
8368
8369 COMMON BLOCKS:
8370
8371 None.
8372
8373 EXAMPLE:
8374
8375 To use this program with your surface data and 2D image, type:
8376
8377 IDL> data = cgDemoData(2)
8378 IDL> image = cgDemoData(7)
8379 IDL> Texture_Surface, data, Image=image, Colortable=33
8380
8381 RESTRICTIONS:
8382
8383 Requires the ASPECT program from the Coyote Library:
8384
8385 http://www.idlcoyote.com/programs/aspect.pro
8386
8387 MODIFICATION HISTORY
8388
8389 Written by David W. Fanning, 1 Nov 2001, from previous Simple_Surface code.
8390 Modifications suggested by Karl Shultz added to allow surface color
8391 specification and improved resolution about image edges when
8392 positioning images. BORDERCOLOR keyword added. DWF. 4 Nov 2001.
8393 The surface now maintains the same X/Y aspect ratio as the surface data. DWF. 8 April 2002.
8394 Added ZSCALE keyword. DWF. 8 April 2002.
8395 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
8396 </PRE><P>
8397 <STRONG>(See texture_surface.pro)</STRONG><P>
8398 <HR>
8399
8400 <A NAME="TRANSFORM_VOLUME">
8401 <H2>TRANSFORM_VOLUME</H2></A>
8402 <A HREF="#TEXTURE_SURFACE">[Previous Routine]</A>
8403 <A HREF="#UNDEFINE">[Next Routine]</A>
8404 <A HREF="#ROUTINELIST">[List of Routines]</A>
8405 <PRE>
8406 NAME:
8407 TRANSFORM_VOLUME
8408
8409 PURPOSE:
8410
8411 The purpose of this program is to transform (e.g., rotate,
8412 scale, and translate) a 3D array or volume.
8413
8414 AUTHOR:
8415
8416 Martin Downing,
8417 Clinical Research Physicist,
8418 Grampian Orthopaedic RSA Research Centre,
8419 Woodend Hospital, Aberdeen, AB15 6LS.
8420 Pnone: 01224 556055 / 07903901612
8421 Fa: 01224 556662
8422 E-mail: [email protected]
8423
8424 CATEGORY:
8425
8426 Mathematics, graphics.
8427
8428 CALLING SEQUENCE:
8429
8430 result = TRANSFORM_VOLUME( volume )
8431
8432 INPUTS:
8433
8434 volume: The 3D array or volume to be transformed.
8435
8436 OPTIONAL KEYWORDS:
8437
8438 BUFFER_SIZE: To reduce memory overhead the routine processes the job in chunks, the number
8439 of elements of which can be set using the BUFFER_SIZE keyword, set this keyword to
8440 0 to force the whole array to be processed at one time. The default value is 128.
8441
8442 MISSING: The value to return for transformed values outside the bounds of
8443 the volume. (Passed to the INTERPOLATE function.) Default is 0.
8444
8445 T3DMAT: The homogeneous transforamtion matrix. If this keyword is not present,
8446 the following keywords can be used to create a homogeneous transformation matrix:
8447
8448 ROTATION - The rotation vector [rx,ry,rz]. The order of rotation is ZYX.
8449 TRANSLATE - The translation vector [tx,ty,tz].
8450 SCALE - The scale vector [sx,sy,sz].
8451 CENTRE_ROTATION - The centre of rotation [cx,cy,cz].
8452
8453 OUTPUTS:
8454
8455 result: The transformed array or volume.
8456
8457 COMMON BLOCKS:
8458
8459 None.
8460
8461 DEPENDENCIES:
8462
8463 The program uses the library INTERPLOLATE routine, which currently (IDL 5.4)
8464 uses linear interpolation. Note that the operation is performed in chunks,
8465 each of which is independant of the result of the others, so the operation
8466 could easiliy be parallelised.
8467
8468 MODIFICATION HISTORY:
8469
8470 Written by: Martin Downing, 16 September 2001.
8471 Added MISSING keyword. Removed INPLACE keyword. 25 Nov 2001. MD
8472 </PRE><P>
8473 <STRONG>(See transform_volume.pro)</STRONG><P>
8474 <HR>
8475
8476 <A NAME="UNDEFINE">
8477 <H2>UNDEFINE</H2></A>
8478 <A HREF="#TRANSFORM_VOLUME">[Previous Routine]</A>
8479 <A HREF="#VCOLORBAR">[Next Routine]</A>
8480 <A HREF="#ROUTINELIST">[List of Routines]</A>
8481 <PRE>
8482 NAME:
8483 UNDEFINE
8484
8485 PURPOSE:
8486 The purpose of this program is to delete or undefine
8487 an IDL program variable from within an IDL program or
8488 at the IDL command line. It is a more powerful DELVAR.
8489 Pointer and structure variables are traversed recursively
8490 to undefine any variables pointed to in the pointer or in
8491 a structure dereference.
8492
8493 AUTHOR:
8494 FANNING SOFTWARE CONSULTING
8495 David Fanning, Ph.D.
8496 1642 Sheely Drive
8497 Fort Collins, CO 80526 USA
8498 Phone: 970-221-0438
8499 E-mail: [email protected]
8500 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8501
8502 CATEGORY:
8503 Utilities.
8504
8505 CALLING SEQUENCE:
8506 UNDEFINE, variable
8507
8508 REQUIRED INPUTS:
8509 variable: The variable to be deleted. Up to 10 variables may be specified as arguments.
8510
8511 SIDE EFFECTS:
8512 The variable no longer exists.
8513
8514 EXAMPLE:
8515 To delete the variable "info", type:
8516
8517 IDL> Undefine, info
8518
8519 IDL> var = ptr_new({a:ptr_New(5), b:findgen(11), c: {d:ptr_New(10), f:findgen(11)}})
8520 IDL> Help, /Heap
8521 Heap Variables:
8522 # Pointer: 3
8523 # Object : 0
8524 <PtrHeapVar3> LONG = 5
8525 <PtrHeapVar4> LONG = 10
8526 <PtrHeapVar5> STRUCT = -> <Anonymous> Array[1]
8527
8528 IDL> Undefine, var
8529 IDL> Help, /Heap
8530 Heap Variables:
8531 # Pointer: 0
8532 # Object : 0
8533 IDL> Help, var
8534 VAR UNDEFINED = <Undefined>
8535
8536 MODIFICATION HISTORY:
8537 Written by David W. Fanning, 8 June 97, from an original program
8538 given to me by Andrew Cool, DSTO, Adelaide, Australia.
8539 Simplified program so you can pass it an undefined variable. :-) 17 May 2000. DWF
8540 Simplified it even more by removing the unnecessary SIZE function. 28 June 2002. DWF.
8541 Added capability to delete up to 10 variables at suggestion of Craig Markwardt. 10 Jan 2008. DWF.
8542 If the variable is a pointer, object or structure reference the variable is recursively traversed
8543 to free up all variables pointed to before the variable is itself destroyed. 10 June 2009. DWF.
8544 Updated to allow undefining of pointer arrays. 8 October 2009. DWF.
8545 Valid pointers that point to undefined variable can cause an infinite loop. Now using
8546 Heap_Free, rather than recursion, with pointers. 30 May 2013. DWF.
8547 </PRE><P>
8548 <STRONG>(See undefine.pro)</STRONG><P>
8549 <HR>
8550
8551 <A NAME="VCOLORBAR">
8552 <H2>VCOLORBAR</H2></A>
8553 <A HREF="#UNDEFINE">[Previous Routine]</A>
8554 <A HREF="#WINDBARB">[Next Routine]</A>
8555 <A HREF="#ROUTINELIST">[List of Routines]</A>
8556 <PRE>
8557 NAME:
8558 VCOLORBAR
8559
8560 FILENAME:
8561
8562 vcolorbar__define.pro
8563
8564 PURPOSE:
8565
8566 The purpose of this program is to create a vertical
8567 colorbar object to be used in conjunction with other
8568 IDL 5 graphics objects.
8569
8570 AUTHOR:
8571
8572 FANNING SOFTWARE CONSULTING
8573 David Fanning, Ph.D.
8574 1645 Sheely Drive
8575 Fort Collins, CO 80526 USA
8576 Phone: 970-221-0438
8577 E-mail: [email protected]
8578 Coyote's Guide to IDL Programming: http://www.idlcoyote.com/
8579
8580 CATEGORY:
8581
8582 IDL Object Graphics.
8583
8584 CALLING SEQUENCE:
8585
8586 thisColorBar = Obj_New('VColorBar')
8587
8588 REQUIRED INPUTS:
8589
8590 None.
8591
8592 INIT METHOD KEYWORD PARAMETERS:
8593
8594 COLOR: A three-element array representing the RGB values of a color
8595 for the colorbar axes and annotation. The default value is
8596 white: [255,255,255].
8597
8598 NAME: The name associated with this object.
8599
8600 NCOLORS: The number of colors associated with the colorbar. The
8601 default is 256.
8602
8603 MAJOR: The number of major tick divisions on the colorbar axes.
8604 The default is 5.
8605
8606 MINOR: The number of minor tick marks on the colorbar axes.
8607 The default is 4.
8608
8609 PALETTE: A palette object for the colorbar. The default palette
8610 is a gray-scale palette object.
8611
8612 POSITION: A four-element array specifying the position of the
8613 colorbar in the arbitary coordinate system of the viewplane
8614 rectangle. The default position is [0.90, 0.10, 0.95, 0.90].
8615
8616 RANGE: The range associated with the colorbar axis. The default
8617 is [0, NCOLORS].
8618
8619 TITLE: A string containing a title for the colorbar axis
8620 annotation. The default is a null string.
8621
8622 OTHER METHODS:
8623
8624 Clamp (Procedure): Given a two-element array in the data range of
8625 the colorbar, the colorbar image is clamped to this range. In
8626 other words, the range of colors is clamped to the specified
8627 range. Values above or below the range in the colorbar are set to
8628 the minimum and maximum range values, respectively.
8629
8630 GetProperty (Procedure): Returns colorbar properties in keyword
8631 parameters as defined for the INIT method. Keywords allowed are:
8632
8633 COLOR
8634 MAJOR
8635 MINOR
8636 NAME
8637 PALETTE
8638 POSITION
8639 RANGE
8640 TITLE
8641 TRANSFORM
8642
8643 SetProperty (Procedure): Sets colorbar properties in keyword
8644 parameters as defined for the INIT method. Keywords allowed are:
8645
8646 COLOR
8647 NAME
8648 MAJOR
8649 MINOR
8650 PALETTE
8651 POSITION
8652 RANGE
8653 TITLE
8654 TRANSFORM
8655
8656 SIDE EFFECTS:
8657
8658 A VCOLORBAR object is created. The colorbar INHERITS IDLgrMODEL.
8659 Thus, all IDLgrMODEL methods and keywords can also be used. It is
8660 the model that is selected in a selection event, since the SELECT_TARGET
8661 keyword is set for the model.
8662
8663 EXAMPLE:
8664
8665 To create a colorbar object and add it to a plot view object, type:
8666
8667 thisColorBarObject = Obj_New('VColorBar')
8668 plotView->Add, thisColorBarObject
8669 plotWindow->Draw, plotView
8670
8671 MODIFICATION HISTORY:
8672
8673 Written by David W. Fanning, 19 June 97.
8674 Changed the optional "colorbarmodel" parameter to an
8675 optional GETMODEL parameter. 26 June 97. DWF.
8676 Fixed bug in the way the color palette was assigned. 13 Aug 97. DWF.
8677 Added missing container object to self structure. 13 Aug 97. DWF.
8678 Removed image model, which was a workaround for
8679 broken 5.0 objects. 5 Oct 97. DWF
8680 Fixed cleanup procedure to clean up ALL objects. 12 Feb 98. DWF.
8681 Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
8682 Modified colorbar to INHERIT an IDLgrModel object. This allows me to
8683 add the colorbar to other models directly. 20 Sept 98. DWF.
8684 Added NAME keyword to give the colorbar a name. 20 Sept 98. DWF.
8685 Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
8686 Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
8687 Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
8688 Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
8689 Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
8690 Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
8691 Removed TEXT keyword (which was never used) and fixed TITLE keyword. 8 Dec 2000. DWF.
8692 Added ENABLE_FORMATTING keyword to title objects. 22 October 2001. DWF.
8693 Added a CLAMP method. 18 November 2001. DWF.
8694 Forgot to pass extra keywords along to the text widget. As a result, you couldn't
8695 format tick labels, etc. Fixed this. Any keywords appropriate for IDLgrTick objects
8696 are now available. 26 June 2002. DWF.
8697 Fixed a problem with POSITION keyword in SetProperty method. 23 May 2003. DWF.
8698 Removed NORMALIZE from source code. 29 Nov 2005. DWF.
8699 Font sizes have changed. Now using a 12 point font. 6 May 2011. DWF.
8700 Changed FSC_Normalize to cgNormalize to reflect new name. 6 Feb 2013. DWF.
8701 </PRE><P>
8702 <STRONG>(See vcolorbar__define.pro)</STRONG><P>
8703 <HR>
8704
8705 <A NAME="WINDBARB">
8706 <H2>WINDBARB</H2></A>
8707 <A HREF="#VCOLORBAR">[Previous Routine]</A>
8708 <A HREF="#WINDOWAVAILABLE">[Next Routine]</A>
8709 <A HREF="#ROUTINELIST">[List of Routines]</A>
8710 <PRE>
8711 NAME:
8712 WINDBARB
8713
8714 PURPOSE:
8715
8716 This is routine for drawing wind barbs on a map.
8717
8718 AUTHOR:
8719
8720 FANNING SOFTWARE CONSULTING
8721 David Fanning, Ph.D.
8722 1645 Sheely Drive
8723 Fort Collins, CO 80526 USA
8724 Phone: 970-221-0438
8725 E-mail: [email protected]
8726 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8727
8728 CATEGORY:
8729
8730 Graphics.
8731
8732 CALLING SEQUENCE:
8733
8734 Windbarb, x, y, speed, direction
8735
8736 REQUIRED INPUTS:
8737
8738 x: The X location of the wind barb, expressed in data coordinates.
8739 Positive X is pointing in EAST direction.
8740
8741 y: The Y location of the wind barb, expressed in data coordinates.
8742 Positive Y is pointing in NORTH direction.
8743
8744 speed: The wind speed, expressed in knots.
8745
8746 direction: The wind direction in degrees clockwise from north. Winds from
8747 the NE come at 45 degrees, and the wind "arrow" points in the
8748 direction from which the window is blowing. (The wind arrow
8749 points in the direction of the station circle, with the "barbs"
8750 of the arrow at the end of the arrow from which the wind is coming.)
8751
8752 KEYWORDS:
8753
8754 ASPECT: The aspect ratio of the map or plot in the display window.
8755
8756 CLIP: A four-element array in normalized coordinates [x0,y0,x1,y1] giving
8757 the lower-left and upper-right corner of a cliping rectangle. This
8758 is normally the extent of your plot. See the example below.
8759
8760 COLOR: The name of the color to draw the wind barbs in. May be a vector
8761 the same length as X.
8762
8763 LENGTH: The approximate length of the wind barb in normalized coordinates.
8764 Will be set to 0.066 of the plot distance in the X direction by default.
8765
8766 MAP_ROTATION: The clockwise rotation in degrees of the map North from the
8767 top of the plot. Will be set to 0.0 by default.
8768
8769 SOUTHERN_HEMISPHERE: Windbarb "feathers" are traditionally drawn in the clockwise
8770 direction in the northern hemispere and countercolockwise in the
8771 southern hemisphere. Default is "northern" type feathers. Set this
8772 keyword to select "southern" type feathers.
8773
8774 STATION: Set this keyword if you want to draw the wind barbs with station symbols.
8775 (Requires STATIONPLOT from the Coyote Library.)
8776
8777 RESTRICTIONS:
8778
8779 Requires cgColor and STATIONPLOT from the Coyote Library:
8780
8781 http://www.idlcoyote.com/programs/cgColor.pro
8782 http://www.idlcoyote.com/programs/stationplot.pro
8783
8784 EXAMPLE:
8785
8786 Window, Title='Wind Barbs', /Free
8787 seed = -3L
8788 lon = Randomu(seed, 9) * 360 - 180
8789 lat = Randomu(seed, 9) * 180 - 90
8790 speed = Randomu(seed, 9) * 100 + 5.0
8791 direction = Indgen(9)*45
8792 Erase, Color=cgColor('Ivory', !P.Background)
8793 Polyfill,[0.1, 0.1, 0.9, 0.9, 0.1], [0.1, 0.9, 0.9, 0.1, 0.1], /Normal, Color=cgColor('light gray')
8794 Map_Set, /Cylindrical, Position=[0.1, 0.1, 0.9, 0.9], Color=cgColor('Steel Blue'), /NoErase
8795 Map_Grid, Color=cgColor('Charcoal', !D.Table_Size-2)
8796 Map_Continents, Color=cgColor('Sea Green', !D.Table_Size-3)
8797 Windbarb, lon, lat, speed, direction, /Station, Color='Indian Red', /Southern_Hemisphere
8798
8799 To clip the windbards that fall outside the plot, substitute these two lines
8800 for the last line in the example above:
8801
8802 clip = [0.1, 0.1, 0.9, 0.9]
8803 Windbarb, lon, lat, speed, direction, /Station, Color='Indian Red', Clip=clip
8804
8805 MODIFICATION HISTORY:
8806
8807 Written by: David W. Fanning, 20 May 2003.
8808 It has been called to my attention that the wind barbs are pointing
8809 in *exactly* the wrong direction. Sigh... Rotated by 180 degrees. DWF. 8 June 2004.
8810 Now someone complains that the *corrected* version is off by 180 degrees! Sheesh!
8811 Clearly, I'm no meteorologist. Both lines of code are in the file. Please use the one
8812 you like the best. :-) (Line 177-178) 20 July 2004. DWF.
8813 Added a CLIP keyword so you can clip the output to the extend of your graphics plot. 12 Nov 2004. DWF.
8814 Added THICK keyword 23 February 2005. DWF.
8815 After further research, I've reverted to the direction specified originally.
8816 And I have changed the "feathers" to point clockwise normally, and counterdlockwise
8817 if the SOUTHERN_HEMISPHERE keyword is set. Here are my sources (21 July 2005. DWF):
8818
8819 http://ww2010.atmos.uiuc.edu/(Gh)/guides/maps/sfcobs/wnd.rxml
8820 http://www.al.noaa.gov/WWWHD/pubdocs/windbarb.html
8821 Fixed a small CLIP problem. 21 July 2005. DWF.
8822
8823 </PRE><P>
8824 <STRONG>(See windbarb.pro)</STRONG><P>
8825 <HR>
8826
8827 <A NAME="WINDOWAVAILABLE">
8828 <H2>WINDOWAVAILABLE</H2></A>
8829 <A HREF="#WINDBARB">[Previous Routine]</A>
8830 <A HREF="#WINDOWIMAGE">[Next Routine]</A>
8831 <A HREF="#ROUTINELIST">[List of Routines]</A>
8832 <PRE>
8833 NAME:
8834 WindowAvailable
8835
8836 PURPOSE:
8837
8838 This function returns a 1 if the specified window index number is
8839 currently open or available. It returns a 0 if the window is currently
8840 closed or unavailable.
8841
8842 AUTHOR:
8843
8844 FANNING SOFTWARE CONSULTING
8845 David Fanning, Ph.D.
8846 1645 Sheely Drive
8847 Fort Collins, CO 80526 USA
8848 Phone: 970-221-0438
8849 E-mail: [email protected]
8850 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8851
8852 CATEGORY:
8853
8854 Utilities
8855
8856 CALLING SEQUENCE:
8857
8858 available = WindowAvaiable(windowIndexNumber)
8859
8860 INPUTS:
8861
8862 windowIndexNumber: The window index number of the window you wish to
8863 know is available or not.
8864
8865 KEYWORDS:
8866
8867 None.
8868
8869 NOTES:
8870
8871 The window vector obtained from the DEVICE command is not always the same length. It
8872 is normally (on my machine) 65 elements long, but can be much longer if you have lots
8873 of IDL windows open (by calling cgPickColorName, for example). But if no windows with
8874 index numbers greater than 65 are open, IDL shinks the larger vector to the smaller one
8875 as part of its housekeeping operations, which means it happens on their timetable, not yours.
8876 This can result in the user having "stale" index numbers greater than 65, but no larger vector
8877 to check them against. I have modified the code to return a 0 in this case, assuming that
8878 whatever window your index number points to is long gone. I have not experience any ill effects
8879 by doing this, but I STRONGLY advice you to ALWAYS know what window you are drawing into
8880 when you issue a graphics command.
8881
8882 MODIFICATION HISTORY:
8883
8884 Written by David W. Fanning, June 2005.
8885 Modified to return 0 if the window index number is larger than the number of elements
8886 in the WINDOW_STATE array. 25 June 2008. DWF.
8887 </PRE><P>
8888 <STRONG>(See windowavailable.pro)</STRONG><P>
8889 <HR>
8890
8891 <A NAME="WINDOWIMAGE">
8892 <H2>WINDOWIMAGE</H2></A>
8893 <A HREF="#WINDOWAVAILABLE">[Previous Routine]</A>
8894 <A HREF="#ROUTINELIST">[List of Routines]</A>
8895 <PRE>
8896 :Description:
8897 Allows the user to interactively adjust image contrast by means of "windowing and
8898 leveling" the image. Move the cursor vertically in the window to adjust the image
8899 stretch "window". Move the cursor horizontally in the window to adjust the image
8900 "level".
8901
8902 :Categories:
8903 Graphics
8904
8905 :Params:
8906 image: in, required, type=any
8907 Any 2D array that you wish to adjust the contrast of.
8908
8909 :Keywords:
8910 brewer: in, optional, type=boolean, default=0
8911 Set this keyword to indicate a Brewer color table is desired.
8912 colortable: in, optional, type=integer, default=0
8913 The index number of a color table to load with cgLoadCT.
8914 neutralcolor: in, optional, type=string
8915 The name of the color to use for values outside the image "window" in
8916 the color table. If a default grayscale color table is loaded, the default
8917 color is "rose", otherwise the default is "black".
8918 reverse: in, optional, type=boolean, default=0
8919 Set this keyword if you wish to reverse the color table.
8920
8921 :Examples:
8922 To see a demonstation::
8923 IDL> WindowImage
8924
8925 :Author:
8926 FANNING SOFTWARE CONSULTING::
8927 David W. Fanning
8928 1645 Sheely Drive
8929 Fort Collins, CO 80526 USA
8930 Phone: 970-221-0438
8931 E-mail: [email protected]
8932 Coyote's Guide to IDL Programming: http://www.idlcoyote.com
8933
8934 :History:
8935 Change History::
8936 Written, 29 November 2010. DWF.
8937 Added color protection to the program. 30 Nov 2010. DWF.
8938 Modification of cgImage command to prevent flashing. 27 Feb 2011. DWF.
8939
8940 :Copyright:
8941 Copyright (c) 2010, Fanning Software Consulting, Inc.
8942 </PRE><P>
8943 <STRONG>(See windowimage.pro)</STRONG><P>
8944 <HR>
8945
8946 </body>
8947 </html>