1Window(3) User Contributed Perl Documentation Window(3)
2
6 PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows
7
9 pdl> use PDL::Graphics::PGPLOT::Window
10 pdl> $win = pgwin(Device => '/xs');
11 pdl> $a = pdl [1..100]
12 pdl> $b = sqrt($a)
13 pdl> $win->line($b)
14 pdl> $win->hold()
15 pdl> $c = sin($a/10)*2 + 4
16 pdl> $win->line($c)
17 In the following documentation the commands are not shown in their OO
19 versions. This is for historical reasons and should not cause too much
20 trouble.
21
23 This package offers a OO interface to the PGPLOT plotting package. This
24 is intended to replace the traditional interface in
25 PDL::Graphics::PGPLOT and contains interfaces to a large number of
26 PGPLOT routines. Below the usage examples for each function tend to be
27 given in the non-OO version for historical reasons. This will slowly be
28 changed, but in the meantime refer to the section on OO-interface below
29 to see how to convert the usage information below to OO usage (it is
30 totally trivial).
31 PDL::Graphics::PGPLOT::Window is an interface to the PGPLOT graphical
33 libraries. It currently supports PGPLOT-5.2 and PGPLOT-5.2-cd2. The
34 -cd2 version includes RGB output and anti-aliasing.
35 High-level plotting commands:
37 imag - Display an image (uses pgimag/pggray/pgrgbi as appropriate)
39 fits_imag - Display a FITS image in scientific coordinates
40 cont - Display image as contour map
41 fits_cont - Display a FITS image in scientific coordinates as a contour map
42 vect - Display 2 images as a vector field
43 fits_vect - Display 2 FITS images in sci. coordinates as a vector field
44 ctab - Load an image colour table
45 ctab_info - Get information about currently loaded colour table
46 line - Plot vector as connected points
47 tline - Plot a collection of vectors as lines
48 lines - Plot a polyline, multicolor vector [threadable]
49 points - Plot vector as points
50 tpoints - Plot a collection of vectors as points [threadable]
51 errb - Plot error bars
52 bin - Plot vector as histogram (e.g. bin(hist($data)) )
53 hi2d - Plot image as 2d histogram (not very good IMHO...)
54 tcircle - Plot vectors as circles [threadable]
55 label_axes - Print axis titles
56 legend - Create a legend with different texts, linestyles etc.
57 Low-level plotting commands:
59 arrow - Draw an arrow
61 poly - Draw a polygon
62 rectangle - Draw a rectangle
63 text - Write text in the plot area
64 cursor - Interactively read cursor positions.
65 circle - Draw a circle
66 ellipse - Draw an ellipse.
67 Device manipulation commands:
69 new - Construct a new output device
71 pgwin - Exported hook to new()
72 close - Close a PGPLOT output device.
73 hold - Hold current plot window range - allows overlays etc.
74 release - Release back to freshly autoscaling for each command.
75 held - Indicates whether the current window is held.
76 focus - Set focus to the given device.
77 erase - Erase the current window (or panel).
78 options - Get the options set for the present output device.
79 id - The ID for the device.
80 device - The device type.
81 name - The window name.
82 Notes: $transform for image/cont etc. is used in the same way as the
84 "TR()" array in the underlying PGPLOT FORTRAN routine but is,
85 fortunately, zero-offset. The transform() routine can be used to create
86 this piddle.
87 For completeness: The transformation array connect the pixel index to a
89 world coordinate such that:
90 X = tr[0] + tr[1]*i + tr[2]*j
92 Y = tr[3] + tr[4]*i + tr[5]*j
93 Variable passing and extensions
95 In general variables are passed to the pgplot routines by using
96 "get_dataref" to get the reference to the values. Before passing to
97 pgplot routines however, the data are checked to see if they are in
98 accordance with the format (typically dimensionality) required by the
99 PGPLOT routines. This is done using the routine "checkarg" (internal
100 to PGPLOT). This routine checks the dimensionality of the input data.
101 If there are superfluous dimensions of size 1 they will be trimmed away
102 until the dimensionality is correct. Example:
103 Assume a piddle with dimensions (1,100,1,1) is passed to "line", which
105 expects its inputs to be vectors. "checkarg" will then return a piddle
106 with dimensions (100). If instead the same piddle was passed to "imag",
107 which requires 2D piddles as output, "checkarg" would return a piddle
108 with dimensionality (100, 1) (Dimensions are removed from the start)
109 Thus, if you want to provide support for another PGPLOT function, the
111 structure currently look like this (there are plans to use the Options
112 package to simplify the options parsing):
113 # Extract the hash(es) on the commandline
115 ($arg, $opt)=_extract_hash(@_);
116 <Check the number of input parameters>
117 <deal with $arg>
118 checkarg($x, 3); # For a hypothetical 3D routine.
119 &catch_signals;
120 ...
121 pgcube($n, $x->get_dataref);
122 &release_signals;
123 1;
124 (the catch_signals/release_signals pair prevent problems with the perl-
126 PGPLOT interface if the user hits c-C during an operation).
127 Setting options
129 All routines in this package take a hash with options as an optional
130 input. This options hash can be used to set parameters for the
131 subsequent plotting without going via the PGPLOT commands.
132 This is implemented such that the plotting settings (such as line
134 width, line style etc.) are affected only for that plot, any global
135 changes made, say, with "pgslw()" are preserved. Some modifications
136 apply when using the OO interface, see below.
137 Alphabetical listing of standard options
139 The following options are always parsed. Whether they have any
140 importance depend on the routine invoked - e.g. line style is
141 irrelevant for "imag", or the "justify" option is irrelevant if the
142 display is on 'hold'. This is indicated in the help text for the
143 commands below.
144 The options are not case sensitive and will match for unique
146 substrings, but this is not encouraged as obscure options might
147 invalidate what you thought was a unique substring.
148 In the listing below examples are given of each option. The actual
150 option can then be used in a plot command by specifying it as an
151 argument to the function wanted (it can be placed anywhere in the
152 command list).
153 E.g:
155 $opt={COLOR=>2};
157 line $x, $y, $opt; # This will plot a line with red color
158 If you are plotting to a hardcopy device then a number of options use a
160 different name:
161 HardLW instead of LineWidth
163 HardCH instead of CharSize
164 HardFont instead of Font
165 HardAxisColour instead of AxisColour
167 HardColour instead of Colour
168 [although I'm not sure when HardColour is actually used]
170 align
172 If "pix" is set, then images and plots are not stretched to fill
173 the plot area. the "align" string tells how to align them within
174 the available area. 'L' and 'R' shove the plot against the left
175 and right edges, respectively; 'B' and 'T' shove the plot against
176 the bottom and top edges. The default is to center the image.
177 e.g. 'BL' puts the image on the bottom left corner, while 'CT'
178 centers the image horizontally while placing it at the top of the
179 available plot area. This defaults to 'BT' for non-justified
180 images, to 'CC' for justified images.
181 arrow
183 This options allows you to set the arrow shape, and optionally size
184 for arrows for the vect routine. The arrow shape is specified as a
185 hash with the key FS to set fill style, ANGLE to set the opening
186 angle of the arrow head, VENT to set how much of the arrow head is
187 cut out and SIZE to set the arrowsize.
188 The following
190 $opt = {ARROW => {FS=>1, ANGLE=>60, VENT=>0.3, SIZE=>5}};
192 will make a broad arrow of five times the normal size.
194 Alternatively the arrow can be specified as a set of numbers
196 corresponding to an extension to the syntax for pgsah. The
197 equivalent to the above is
198 $opt = {ARROW => pdl([1, 60, 0.3, 5})};
200 For the latter the arguments must be in the given order, and if any
202 are not given the default values of 1, 45, 0.3 and 1.0 respectively
203 will be used.
204 arrowsize
206 The arrowsize can be specified separately using this option to the
207 options hash. It is useful if an arrowstyle has been set up and one
208 wants to plot the same arrow with several sizes. Please note that
209 it is not possible to set arrowsize and character size in the same
210 call to a plotting function. This should not be a problem in most
211 cases.
212 $opt = {ARROWSIZE => 2.5};
214 axis
216 Set the axis value (see "env"). If you pass in a scalar you set
217 the axis for the whole plot. You can also pass in an array ref for
218 finer control of the axes.
219 If you set the option to a scalar value, you get one of a few
221 standard layouts. You can specify them by name or by number:
222 EMPTY (-2) draw no box, axes or labels
224 BOX (-1) draw box only
225 NORMAL (0) draw box and label it with coordinates
226 AXES (1) same as NORMAL, but also draw (X=0,Y=0) axes
227 GRID (2) same as AXES, but also draw grid lines
228 LOGX (10) draw box and label X-axis logarithmically
229 LOGY (20) draw box and label Y-axis logarithmically
230 LOGXY (30) draw box and label both axes logarithmically
231 When using logarithmic axes ("LOGX", "LOGY" and "LOGXY") you
233 normally need to log the data yourself, e.g.
234 line $x->log10, $y, {axis=>'LOGX'};
236 For your convenience you can put PDL::Graphics::PGPLOT into autolog
238 mode. In this mode a call to "line" or "points" will log the data
239 for you and you can pass in the unmodified data, e.g.
240 autolog(1); # enable automatic logarithm calculation
242 line $x, $y, {axis=>'LOGX'}; # automatically displays logged x data
243 You can use the function interface to enable autologging:
245 autolog(1);
247 or use it with a window reference (mode switching on a per window
249 basis)
250 $win->autolog(1);
252 "autolog" without arguments returns the current autolog setting
254 (0=off, 1=on).
255 If you set the "AXIS" option to an array ref, then you can specify
257 the box/axis options separately for the horizontal (ordinate; X
258 coordinate; 0th element) and vertical (abscissa; Y coordinate; 1st
259 element)) axes. Each element of the array ref should contain a
260 PGPLOT format string. Presence or absence of specific characters
261 flags particular options. For normal numeric labels, the options
262 are:
263 A : draw axis for this dimension.
265 B : draw bottom (X) or left (Y) edge of frame.
266 C : draw top (X) or right (Y) edge of frame.
267 G : draw Grid of vertical (X) or horizontal (Y) lines.
268 I : Invert ticks: draw them outside the plot rather than inside.
269 L : Label the axis Logarithmically.
270 P : Extend ("Project") major tick marks outside the box.
271 M : Numeric labels go in the alternate place above (X) or to the
272 right (Y) of the viewport.
273 N : Numeric labels go in the usual location below (X) or to the
274 left (Y) of the viewport
275 T : Draw major tick marks at the major coordinate interval.
276 S : Draw minor tick marks (subticks).
277 V : Orient numeric labels Vertically. Only applicable to Y.
278 (The default is to write them parallel to the axis.)
279 1 : Force decimal labelling, instead of automatic choice
280 2 : Force exponential labeling, instead of automatic.
281 If you don't specify any axis value at all, the default is
283 ['BCNST','BCNST'] for plots and ['BCINST','BCINST'] for images.
284 (These list ref elements are handed on directly to the low-level
285 PGPLOT routines).
286 In addition, you can specify that your axis labels should be
288 printed as days, hours, minutes, and seconds (ideal for julian
289 dates and delta-t, or for angular quantities). You do that by
290 setting additional character flags on the affected axis:
291 X : Use HH MM SS.S time labeling rather than conventional numeric
293 labels. The ordinate is in secsonds. Hours roll over at 24.
294 Y : Like 'X' but the hour field runs past 24 if necessary.
295 Z : Like 'X' but with a days field too (only shown where nonzero).
296 H : Label the numbers with superscript d, h, m, and s symbols.
297 D : Label the numbers with superscript o, ', and '' symbols.
298 F : Omit first (lowest/leftmost) label; useful for tight layouts.
299 O : Omit leading zeroes in numbers under 10 (e.g. " 3h 3m 1.2s"
300 rather than "03h 03m 01.2s").
301 For example, to plot a numeric quantity versus Julian day of the
303 year in a standard boxed plot with tick marks, you can use
304 ["BNCSTZHO","BCNST"].
305 border
307 Normally the limits are chosen so that the plot just fits; with
308 this option you can increase (or decrease) the limits by either a
309 relative (ie a fraction of the original axis width) or an absolute
310 amount. Either specify a hash array, where the keys are "TYPE"
311 (set to 'relative' or 'absolute') and "VALUE" (the amount to change
312 the limits by), or set to 1, which is equivalent to
313 BORDER => { TYPE => 'rel', VALUE => 0.05 }
315 charsize
317 Set the character/symbol size as a multiple of the standard size.
318 $opt = {CHARSIZE => 1.5}
320 The HardCH option should be used if you are plotting to a hardcopy
322 device.
323 colour (or color)
325 Set the colour to be used for the subsequent plotting. This can be
326 specified as a number, and the most used colours can also be
327 specified with name, according to the following table (note that
328 this only works for the default colour map):
329 0 - WHITE 1 - BLACK 2 - RED 3 - GREEN 4 - BLUE
331 5 - CYAN 6 - MAGENTA 7 - YELLOW 8 - ORANGE 14 - DARKGRAY
332 16 - LIGHTGRAY
333 However there is a much more flexible mechanism to deal with
335 colour. The colour can be set as a 3 or 4 element anonymous array
336 (or piddle) which gives the RGB colours. If the array has four
337 elements the first element is taken to be the colour index to
338 change. For normal work you might want to simply use a 3 element
339 array with R, G and B values and let the package deal with the
340 details. The R,G and B values go from 0 to 1.
341 In addition the package will also try to interpret non-recognised
343 colour names using the default X11 lookup table, normally using the
344 "rgb.txt" that came with PGPLOT.
345 For more details on the handling of colour it is best that the user
347 consults the PGPLOT documentation. Further details on the handling
348 of colour can be found in the documentation for the internal
349 routine "_set_colour".
350 The HardColour option should be used if you are plotting to a
352 hardcopy device [this may be untrue?].
353 diraxis
355 This sets the direction of the axes of a plot or image, when you
356 don't explicitly set them with the XRange and YRange options. It's
357 particularly useful when you want (for example) to put long
358 wavelengths (larger numbers) on the left hand side of your plot, or
359 when you want to plot an image in (RA,dec) coordinates.
360 You can use either a scalar or a two-element perl array. If you
362 set it to 0 (the default) then PDL will guess which direction you
363 want to go. If you set it to a positive number, the axis will
364 always increase to the right. If you set it to a negative number,
365 the axis will always increase to the left.
366 For example, [0,0] is the default, which is usually right. [1,1]
368 tells PGPLOT to always increase the axis values up and to the
369 right. For a plot of intensity (y-axis) versus wavelength (x-axis)
370 you could say [-1,1].
371 This option is really only useful if you want to allow autoranging
373 but need to set the direction that the axis goes. If you use the
374 ranging options ("XRange" and "YRange"), you can change the
375 direction by changing the order of the maximum and minimum values.
376 That direction will override "DirAxis".
377 filltype
379 Set the fill type to be used by "poly", "circle", "ellipse", and
380 "rectangle" The fill can either be specified using numbers or name,
381 according to the following table, where the recognised name is
382 shown in capitals - it is case-insensitive, but the whole name must
383 be specified.
384 1 - SOLID
386 2 - OUTLINE
387 3 - HATCHED
388 4 - CROSS_HATCHED
389 $opt = {FILLTYPE => 'SOLID'};
391 (see below for an example of hatched fill)
393 font
395 Set the character font. This can either be specified as a number
396 following the PGPLOT numbering or name as follows (name in
397 capitals):
398 1 - NORMAL
400 2 - ROMAN
401 3 - ITALIC
402 4 - SCRIPT
403 (Note that in a string, the font can be changed using the escape
405 sequences "\fn", "\fr", "\fi" and "\fs" respectively)
406 $opt = {FONT => 'ROMAN'};
408 gives the same result as
410 $opt = {FONT => 2};
412 The HardFont option should be used if you are plotting to a
414 hardcopy device.
415 hatching
417 Set the hatching to be used if either fillstyle 3 or 4 is selected
418 (see above) The specification is similar to the one for specifying
419 arrows. The arguments for the hatching is either given using a
420 hash with the key ANGLE to set the angle that the hatch lines will
421 make with the horizontal, SEPARATION to set the spacing of the
422 hatch lines in units of 1% of "min(height, width)" of the view
423 surface, and PHASE to set the offset the hatching. Alternatively
424 this can be specified as a 1x3 piddle "$hatch=pdl[$angle, $sep,
425 $phase]".
426 $opt = {FILLTYPE => 'HATCHED',
428 HATCHING => {ANGLE=>30, SEPARATION=>4}};
429 Can also be specified as
431 $opt = {FILL=> 'HATCHED', HATCH => pdl [30,4,0.0]};
433 For another example of hatching, see "poly".
435 justify
437 If "justify" is set true, then the plot axes are shrunk to fit the
438 plot or image and it specifies the aspect ratio of pixel
439 coordinates in the plot or image. Setting justify=>1 will produce
440 a correct-aspect-ratio, shrink-wrapped image or plot; setting
441 justify=>0.5 will do the same thing but with a short and fat plot.
442 The difference between "justify" and "pix" is that "pix" does not
443 affect the shape of the axes themselves.
444 linestyle
446 Set the line style. This can either be specified as a number
447 following the PGPLOT numbering:
448 1 - SOLID line
450 2 - DASHED
451 3 - DOT-DASH-dot-dash
452 4 - DOTTED
453 5 - DASH-DOT-DOT-dot
454 or using name (as given in capitals above). Thus the following two
456 specifications both specify the line to be dotted:
457 $opt = {LINESTYLE => 4};
459 $varopt = {LINESTYLE => 'DOTTED'};
460 The names are not case sensitive, but the full name is required.
462 linewidth
464 Set the line width. It is specified as a integer multiple of 0.13
465 mm.
466 $opt = {LINEWIDTH => 10}; # A rather fat line
468 The HardLW option should be used if you are plotting to a hardcopy
470 device.
471 pitch
473 Sets the number of data pixels per inch on the output device. You
474 can set the "unit" (see below) to change this to any other PGPLOT
475 unit (millimeters, pixels, etc.). Pitch is device independent, so
476 an image should appear exactly the same size (e.g. "Pitch=>100" is
477 100 dpi) regardless of output device.
478 pix Sets the pixel aspect ratio height/width. The height is adjusted
480 to the correct ratio, while maintaining any otherwise-set pitch or
481 scale in the horizontal direction. Larger numbers yield tall,
482 skinny pixels; smaller numbers yield short, fat pixels.
483 scale
485 Sets the number of output display pixels per data pixel. You can
486 set the "unit" (see below) to change this to number of PGPLOT units
487 (inches, millimeters, etc.) per data pixel. "scale" is deprecated,
488 as it is not device-independent; but it does come in handy for
489 quick work on digital displays, where aliasing might otherwise
490 interfere with image interpretation. For example, "scale=>1"
491 displays images at their native resolution.
492 Panel
494 It is possible to define multiple plot ``panels'' with in a single
495 window (see the NXPanel and NYPanel options in the constructor).
496 You can explicitly set in which panel most plotting commands occur,
497 by passing either a scalar or an array ref into the "Panel" option.
498 There is also a panel method, but its use is deprecated because of
499 a wart with the PGPLOT interface.
500 plotting & imaging range
502 Explicitly set the plot range in x and y. X-range and Y-range are
503 set separately via the aptly named options "XRange" and "YRange".
504 If omitted PGPLOT selects appropriate defaults (minimum and maximum
505 of the data range in general). These options are ignored if the
506 window is on hold.
507 line $x, $y, {xr => [0,5]}; # y-range uses default
509 line $x, $y, {XRange => [0,5], YRange => [-1,3]}; # fully specified range
510 imag $im, {XRange => [30,50], YRange=>[-10,30]};
511 fits_imag $im, {XRange=>[-2,2], YRange=>[0,1]};
512 Imaging requires some thought if you don't want to lose a pixel off
514 the edge of the image. Pixels are value-centered (they are
515 centered on the coordinate whose value they represent), so the
516 appropriate range to plot the entirety of a 100x100 pixel image is
517 "[-0.5,99.5]" on each axis.
518
520 This section will briefly describe how the
521 PDL::Graphics::PGPLOT::Window package can be used in an object-oriented
522 (OO) approach and what the advantages of this would be. We will start
523 with the latter
524 Multiple windows.
526 For the common user it is probably most interesting to use the OO
527 interface when handling several open devices at the same time. If
528 you have one variable for each plot device it is easier to
529 distribute commands to the right device at the right time. This is
530 the angle we will take in the rest of this description.
531 Coding and abstraction
533 At a more fundamental level it is desirable to approach a situation
534 where it is possible to have a generic plotting interface which
535 gives access to several plotting libraries, much as PGPLOT gives
536 access to different output devices. Thus in such a hypothetical
537 package one would say:
538 my $win1 = Graphics::new('PGPLOT', {Device => '/xs'});
540 my $win2 = Graphics::new('gnuplot', {Background => 'Gray'};
541 From a more practical point of of view such abstraction also comes
543 in handy when you write a large program package and you do not want
544 to import routines nilly-willy in which case an OO approach with
545 method calls is a lot cleaner.
546 The pgwin exported constructor, arguably, breaks this philosophy;
548 hopefully it will ``wither away'' when other compatible modules are
549 available.
550 Anyway, enough philosophizing, let us get down to Earth and give some
552 examples of the use of OO PGPLOT. As an example we will take Odd (which
553 happens to be a common Norwegian name) who is monitoring the birth of
554 rabbits in O'Fib-o-nachy's farm (alternatively he can of course be
555 monitoring processes or do something entirely different). Odd wants the
556 user to be able to monitor both the birth rates and accumulated number
557 of rabbits and the spatial distribution of the births. Since these are
558 logically different he chooses to have two windows open:
559 $rate_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw',
561 Aspect => 1, WindowWidth => 5, NXPanel => 2);
562 $area_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw',
564 Aspect => 1, WindowWidth => 5);
565 See the documentation for new below for a full overview of the options
567 you can pass to the constructor.
568 Next, Odd wants to create plotting areas for subsequent plots and maybe
570 show the expected theoretical trends
571 $rate_win->env(0, 10, 0, 1000, {XTitle => 'Days', YTitle => '#Rabbits'});
573 $rate_win->env(0, 10, 0, 100, {Xtitle=>'Days', Ytitle => 'Rabbits/day'});
574 $area_win->env(0, 1, 0, 1, {XTitle => 'Km', Ytitle => 'Km'});
576 # And theoretical prediction.
577 $rate_win->line(sequence(10), fibonacci(10), {Panel => [1, 1]});
578 That is basically it. The commands should automatically focus the
580 relevant window. Due to the limitations of PGPLOT this might however
581 lead you to plot in the wrong panel... The package tries to be smart
582 and do this correctly, but might get it wrong at times.
583
585 A new addition to the graphics interface is the ability to record plot
586 commands. This can be useful when you create a nice-looking plot on the
587 screen that you want to re-create on paper for instance. Or if you want
588 to redo it with slightly changed variables for instance. This is still
589 under development and views on the interface are welcome.
590 The functionality is somewhat detached from the plotting functions
592 described below so I will discuss them and their use here.
593 Recording is off by default. To turn it on when you create a new device
595 you can set the "Recording" option to true, or you can set the
596 $PDL::Graphics::PGPLOT::RECORDING variable to 1. I recommend doing the
597 latter in your ".perldlrc" file at least since you will often have use
598 for recording in the perldl or pdl2 script.
599 Use of recording
601 The recording is meant to help you recreate a plot with new data or to
602 a different device. The most typical situation is that you have created
603 a beautiful plot on screen and want to have a Postscript file with it.
604 In the dreary old world you needed to go back and execute all commands
605 manually, but with this wonderful new contraption, the recorder, you
606 can just replay your commands:
607 dev '/xs', {Recording => 1}
609 $x = sequence(10)
610 line $x, $x**2, {Linestyle => 'Dashed'}
611 $s = retrieve_state() # Get the current tape out of the recorder.
612 dev '/cps'
613 replay $s
614 This should result in a "pgplot.ps" file with a parabola drawn with a
616 dashed line. Note the command "retrieve_state" which retrieves the
617 current state of the recorder and return an object (of type
618 PDL::Graphics::State) that is used to replay commands later.
619 Controlling the recording
621 Like any self-respecting recorder you can turn the recorder on and off
622 using the "turn_on_recording" and "turn_off_recording" respectively.
623 Likewise you can clear the state using the "clear_state" command.
624 $w=PDL::Graphics::PGPLOT::Window->new(Device => '/xs');
626 $w->turn_on_recording;
627 $x=sequence(10); $y=$x*$x;
628 $w->line($x, $y);
629 $w->turn_off_recording;
630 $w->line($y, $x);
631 $w->turn_on_recording;
632 $w->line($x, $y*$x);
633 $state = $w->retrieve_state();
634 We can then replay $state and get a parabola and a cubic plot.
636 $w->replay($state);
638 Tips and Gotchas!
640 The data are stored in the state object as references to the real data.
641 This leads to one good and one potentially bad consequence:
642 The good is that you can create the plot and then subsequently redo the
644 same plot using a different set of data. This is best explained by an
645 example. Let us first create a simple gradient image and get a copy of
646 the recording:
647 $im = sequence(10,10)
648 imag $im
649 $s=retrieve_state
650 Now this was a rather dull plot, and in reality we wanted to show
652 an image using "rvals". Instead of re-creating the plot (which of
653 course here would be the simplest option) we just change $im:
654 $im -= sequence(10,10)
656 $im += rvals(10,10)
657 Now replay the commands
659 replay $s
661 And hey presto! A totally different plot. Note however the trickery
663 required to avoid losing reference to $im
664 This takes us immediately to the major problem with the recording
666 though. Memory leakage! Since the recording keeps references to the
667 data it can keep data from being freed (zero reference count) when you
668 expect it to be. For instance, in this example, we lose totally track
669 of the original $im variable, but since there is a reference to it in
670 the state it will not be freed
671 $im = sequence(1000,1000)
672 imag $im
673 $s = retrieve_state
674 $im = rvals(10,10)
675 Thus after the execution of these commands we still have a
677 reference to a 1000x1000 array which takes up a lot of memory...
678 The solution is to call "clear" on the state variable:
680 $s->clear()
682 (This is done automatically if the variable goes out of scope). I
684 forsee this problem to most acute when working on the "perldl" or
685 "pdl2" command line, but since this is exactly where the recording
686 is most useful the best advice is just to be careful and call clear
687 on state variables.
688 If you are working with scripts and use large images for instance I
690 would instead recommend that you do not turn on recording unless
691 you need it.
692
694 A more detailed listing of the functions and their usage follows. For
695 all functions we specify which options take effect and what other
696 options exist for the given function. The function descriptions below
697 are all given for the non-OO usage for historical reasons, but since
698 the conversion to an OO method is trivial there is no major need for
699 concern. Whenever you see a function example of the form
700 Usage: a_simple_function($x, $y, $z [, $opt]);
702 and you wish to use the OO version, just let your mind read the above
704 line as:
705 Usage: $win->a_simple_function($x, $y, $z [, $opt]);
707 where $win is a PDL::Graphics::PGPLOT::Window object. That is all.
709 Window control functions.
711 pgwin
712 Exported constructor for PGPLOT object/device/plot window.
713 Usage: pgwin($opt);
715 Usage: pgwin($option->$value,...);
716 Usage: pgwin($device);
717 Parameters are passed on to new() and can either be specified by hash
719 reference or as a list.
720 See the documentation fo PDL::Graphics::PGPLOT::Window::new for
722 details.
723 Because pgwin is a convenience function, you can specify the device by
725 passing in a single non-ref parameter. For even further convenience,
726 you can even omit the '/' in the device specifier, so these two lines
727 deliver the same result:
728 $a = pgwin(gif);
730 $a = new PDL::Graphics::PGPLOT::Window({Dev=>'/gif'});
731 new
733 Constructor for PGPLOT object/device/plot window.
734 Usage: PDL::Graphics::PGPLOT::Window->new($opt);
736 Usage: PDL::Graphics::PGPLOT::Window->new($option=>$value,...);
737 Options to new() can either be specified via a reference to a hash
739 $win = PDL::Graphics::PGPLOT::Window->new({Dev=>'/xserve',ny=>2});
741 or directly, as an array
743 # NOTE: no more {} !
745 $win = PDL::Graphics::PGPLOT::Window->new(Dev=>'/xserve',ny=>2);
746 The following lists the recognised options:
748 AspectRatio
750 The aspect ratio of the image, in the sense vertical/horizontal.
751 See the discussion on size setting.
752 Device
754 The type of device to use. The syntax of this is the one used by
755 PGPLOT.
756 Hold
758 Hold the plot window so that subsequent plots can plot over
759 existing plots. This can be adjusted with the "hold()" and
760 "release()" methods.
761 NXPanel
763 The number of panels in the X-direction
764 NYPanel
766 The number of panels in the Y-direction
767 Size
769 Yet another way to identify the plot window size -- this takes a
770 scalar or an array ref containing one, two, or three numbers. One
771 number gives you a square window. Two gives you a rectangular
772 window "(X,Y)". Three lets you specify the unit compactly (e.g.
773 "[<X>,<Y>,1]" for inches, "[<X>,<Y>,2]" for mm) but is deprecated
774 in favor of using the "Unit" option. See the discussion on size
775 setting.
776 Unit
778 The unit to use for size setting. PGPLOT accepts inch, mm, or
779 pixel. The default unit is inches for historical reasons, but you
780 can choose millimeters or (God forbid) pixels as well. String or
781 numeric specifications are OK (0=normalized, 1=inches, 2=mm,
782 3=pixels). Normalized units make no sense here and are not
783 accepted. Ideally someone will one day hook this into the CPAN
784 units parser so you can specify window size in rods or attoparsecs.
785 WindowName
787 The name to give to the window. No particular use is made of this
788 at present. It would be great if it was possible to change the
789 title of the window frame.
790 WindowWidth
792 The width of the window in inches (or the specified Unit). See the
793 discussion on size setting.
794 WindowXSize and WindowYSize
796 The width and height of the window in inches (or the specified
797 Unit). See the discussion on size setting.
798 An important point to note is that the default values of most options
800 can be specified by passing these to the constructor. All general
801 options (common to several functions) can be adjusted in such a way,
802 but function specific options can not be set in this way (this is a
803 design limitation which is unlikely to be changed).
804 Thus the following call will set up a window where the default axis
806 colour will be yellow and where plot lines normally have red colour and
807 dashed linestyle.
808 $win = PDL::Graphics::PGPLOT::Window->new(Device => '/xs',
810 AxisColour => 'Yellow', Colour => 'Red', LineStyle => 'Dashed');
811 Size setting: There are a gazillion ways to set window size, in keeping
813 with TIMTOWTDI. In general you can get away with passing any unique
814 combination of an "<X>" size, a "<Y>"size, and/or an aspect ratio. In
815 increasing order of precedence, the options are: ("Units",
816 "AspectRatio", "WindowWidth", "Window<X,Y>Size", "Size").
817 So if you specify an AspectRatio *and* an X and a Y coordinate, the
819 AspectRatio is ignored. Likewise, if you specify Units and a three-
820 component Size, the Units option is ignored in favor of the numeric
821 unit in the Size.
822 If you don't specify enough information to set the size of the window,
824 you get the default pane size and shape for that device.
825 close
827 Close a plot window
828 Usage: $win->close()
830 Close the current window. This does not necessarily mean that the
832 window is removed from your screen, but it does ensure that the device
833 is closed.
834 A message will be printed to STDOUT giving the name of the file created
836 if the plot was made to a hardcopy device and $PDL::verbose is true.
837 held
839 Check if a window is on hold
840 $is_held = $win->held();
842 Function to check whether the window is held or not.
844 hold
846 Hold the present window.
847 Usage: $win->hold()
849 Holds the present window so that subsequent plot commands overplots.
851 panel
853 Switch to a different panel
854 $win->panel(<num>);
856 Move to a different panel on the plotting surface. Note that you will
858 need to erase it manually if that is what you require.
859 This routine currently does something you probably don't want, and
861 hence is deprecated for most use: if you say
862 $win->panel(1);
864 $win->imag($image);
865 then $image will actually be displayed in panel 2. That's because the
867 main plotting routines such as line and imag all advance the panel when
868 necessary. Instead, it's better to use the Panel option within
869 plotting commands, if you want to set the panel explicitly.
870 release
872 Release a plot window.
873 $win->release()
875 Release a plot window so that subsequent plot commands move to the next
877 panel or erase the plot and create a new plot.
878 erase
880 Erase plot
881 $win->erase($opt);
883 Erase a plot area. This accepts the option "Panel" or alternatively a
885 number or array reference which makes it possible to specify the panel
886 to erase when working with several panels.
887 Plotting functions
889 env
890 Define a plot window, and put graphics on 'hold'
891 $win->env( $xmin, $xmax, $ymin, $ymax, [$justify, $axis] );
893 $win->env( $xmin, $xmax, $ymin, $ymax, [$options] );
894 $xmin, $xmax, $ymin, $ymax are the plot boundaries. $justify is a
896 boolean value (default is 0); if true the axes scales will be the same
897 (see "justify"). $axis describes how the axes should be drawn (see
898 "axis") and defaults to 0.
899 If the second form is used, $justify and $axis can be set in the
901 options hash, for example:
902 $win->env( 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID',
904 CHARSIZE => 0.7} );
905 In addition the following options can also be set for "env":
907 PlotPosition
909 The position of the plot on the page relative to the view surface
910 in normalised coordinates as an anonymous array. The array should
911 contain the lower and upper X-limits and then the lower and upper
912 Y-limits. To place two plots above each other with no space between
913 them you could do
914 $win->env(0, 1, 0, 1, {PlotPosition => [0.1, 0.5, 0.1, 0.5]});
916 $win->env(5, 9, 0, 8, {PlotPosition => [0.1, 0.5, 0.5, 0.9]});
917 Axis, Justify, Border
919 See the description of general options for these options.
920 AxisColour
922 Set the colour of the coordinate axes.
923 XTitle, YTitle, Title, Font, CharSize
925 Axes titles and the font and size to print them.
926 label_axes
928 Label plot axes
929 $win->label_axes(<xtitle>, <ytitle>, <plot title>, $options);
931 Draw labels for each axis on a plot.
933 imag
935 Display an image (uses "pgimag()"/"pggray()" as appropriate)
936 $win->imag ( $image, [$min, $max, $transform], [$opt] )
938 NOTES
940 $transform for image/cont etc. is used in the same way as the "TR()"
942 array in the underlying PGPLOT FORTRAN routine but is, fortunately,
943 zero-offset. The transform() routine can be used to create this piddle.
944 If $image is two-dimensional, you get a grey or pseudocolor image using
946 the scalar values at each X,Y point. If $image is three-dimensional
947 and the third dimension has order 3, then it is treated as an RGB true-
948 color image via rgbi.
949 There are several options related to scaling. By default, the image is
951 scaled to fit the PGPLOT default viewport on the screen. Scaling,
952 aspect ratio preservation, and 1:1 pixel mapping are available. (1:1
953 pixel mapping is useful for avoiding display artifacts, but it's not
954 recommended for final output as it's not device-independent.)
955 Here's an additional complication: the "pixel" stuff refers not
957 (necessarily) to normal image pixels, but rather to transformed image
958 pixels. That is to say, if you feed in a transform matrix via the
959 "TRANSFORM" option, the "PIX", "SCALE", etc. options all refer to the
960 transformed coordinates and not physical image pixels. That is a Good
961 Thing because it, e.g., lets you specify plate scales of your output
962 plots directly! See fits_imag for an example application. If you do
963 not feed in a transform matrix, then the identity matrix is applied so
964 that the scaling options refer to original data pixels.
965 To draw a colour bar (or wedge), either use the "DrawWedge" option, or
967 the "draw_wedge()" routine (once the image has been drawn).
968 Options recognised:
970 ITF
972 the image transfer function applied to the pixel values. It may be
973 one of 'LINEAR', 'LOG', 'SQRT' (lower case is acceptable). It
974 defaults to 'LINEAR'.
975 MIN
977 Sets the minimum value to be used for calculation of the color-table
978 stretch.
979 MAX
981 Sets the maximum value for the same.
982 RANGE
984 A more compact way to specify MIN and MAX, as a list: you can say
985 "Range=>[0,10]" to scale the color table for brightness values
986 between 0 and 10 in the iamge data.
987 CRANGE
989 Image values between MIN and MAX are scaled to an interval in
990 normalized color domain space, on the interval [0,1], before lookup
991 in the window's color table. CRANGE lets you use only a part of the
992 color table by specifying your own range -- e.g. if you say
993 "CRange=>[0.25,0.75]" then only the middle half of the pseudocolor
994 space will be used. (See the writeup on ctab().)
995 TRANSFORM
997 The PGPLOT transform 'matrix' as a 6x1 vector for display
998 DrawWedge
1000 set to 1 to draw a colour bar (default is 0)
1001 Wedge
1003 see the draw_wedge() routine
1004 The following standard options influence this command:
1006 AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN, XRANGE, YRANGE
1008 To see an image with maximum size in the current window, but square
1010 pixels, say:
1011 $win->imag( $a, { PIX=>1 } );
1012 An alternative approach is to try:
1013 $win->imag( $a, { JUSTIFY=>1 } );
1014 To see the same image, scaled 1:1 with device pixels, say:
1015 $win->imag( $a, { SCALE=>1 } );
1016 To see an image made on a device with 1:2 pixel aspect ratio, with
1017 X pixels the same as original image pixels, say
1018 $win->imag( $a, { PIX=>0.5, SCALE=>2 } );
1019 To display an image at 100 dpi on any device, say:
1020 $win->imag( $a, { PITCH=>100 } );
1021 To display an image with 100 micron pixels, say:
1022 $win->imag( $a, { PITCH=>10, UNIT=>'mm' } );
1023 imag1
1025 Display an image with correct aspect ratio
1026 $win->imag1 ( $image, [$min, $max, $transform], [$opt] )
1028 This is syntactic sugar for
1030 $win->imag( { PIX=>1, ALIGN=>'CC' } );
1032 rgbi
1034 Display an RGB color image
1035 The calling sequence is exactly like "imag", except that the input
1037 image must have three dimensions: "N x M x 3". The last dimension is
1038 the (R,G,B) color value. This routine requires pgplot 5.3devel or
1039 later. Calling rgbi explicitly is not necessary, as calling image with
1040 an appropriately dimensioned RGB triplet makes it fall through to rgbi.
1041 fits_imag
1043 Display a FITS image with correct axes
1044 $win->fits_imag( image, [$min, $max], [$opt] );
1046 NOTES
1048 Titles:
1050 Currently fits_imag also generates titles for you by default and
1051 appends the FITS header scientific units if they're present. So if
1052 you say
1053 $pdl->hdr->{CTYPE1} = "Flamziness";
1055 $pdl->hdr->{CUNIT1} = "milliBleems";
1056 $win->fits_imag($pdl);
1057 then you get an X title of "Flamziness (milliBleems)". But you can
1059 (of course) override that by specifying the XTitle and YTitle
1060 switches:
1061 $win->fits_imag($pdl,{Xtitle=>"Arbitrary"});
1063 will give you "Arbitrary" as an X axis title, regardless of what's
1065 in the header.
1066 Scaling and aspect ratio:
1068 If CUNIT1 and CUNIT2 (or, if they're missing, CTYPE1 and CTYPE2)
1069 agree, then the default pixel aspect ratio is 1 (in scientific
1070 units, NOT in original pixels). If they don't agree (as for a
1071 spectrum) then the default pixel aspect ratio is adjusted
1072 automatically to match the plot viewport and other options you've
1073 specified.
1074 You can override the image scaling using the SCALE, PIX, or PITCH
1076 options just as with the imag() method -- but those parameters refer
1077 to the scientific coordinate system rather than to the pixel
1078 coordinate system (e.g. "PITCH=>100" means "100 scientific units per
1079 inch", and "SCALE=>1" means "1 scientific unit per device pixel").
1080 See the imag() writeup for more info on these options.
1081 The default value of the "ALIGN" option is 'CC' -- centering the
1083 image both vertically and horizontally.
1084 Axis direction:
1086 By default, fits_imag tries to guess which direction your axes are
1087 meant to go (left-to-right or right-to-left) using the CDELT
1088 keywords: if "CDELT" is negative, then rather than reflecting the
1089 image fits_imag will plot the X axis so that the highest values are
1090 on the left.
1091 This is the most convenient behavior for folks who use calibrated
1093 (RA,DEC) images, but it is technically incorrect. To force the
1094 direction, use the DirAxis option. Setting "DirAxis=>1"
1095 (abbreviated "di=>1") will force the scientific axes to increase to
1096 the right, reversing the image as necessary.
1097 Color wedge:
1099 By default fits_imag draws a color wedge on the right; you can
1100 explicitly set the "DrawWedge" option to 0 to avoid this. Use the
1101 "WTitle" option to set the wedge title.
1102 Alternate WCS coordinates:
1104 The default behaviour is to use the primary/default WCS information
1105 in the FITS header (i.e. the "CRVAL1","CRPIX1",... keywords). The
1106 Greisen et al. standard
1107 (<http://fits.cv.nrao.edu/documents/wcs/wcs.html>) allows
1108 alternative/additional mappings to be included in a header; these
1109 are denoted by the letters "A" to "Z". If you know that your image
1110 contains such a mapping then you can use the "WCS" option to select
1111 the appropriate letter. For example, if you had read in a Chandra
1112 image created by the CIAO software package then you can display the
1113 image in the "physical" coordinate system by saying:
1114 $win->fits_imag( $pdl, { wcs => 'p' } );
1116 The identity transform is used if you select a mapping for which
1118 there is no information in the header. Please note that this
1119 support is experimental and is not guaranteed to work correctly;
1120 please see the documentation for the _FITS_tr routine for more
1121 information.
1122 fits_rgbi
1124 Display an RGB FITS image with correct axes
1125 $win->fits_rgbi( image, [$min,$max], [$opt] );
1127 Works exactly like fits_imag, but the image must be in (X,Y,RGB) form.
1129 Only the first two axes of the FITS header are examined.
1130 fits_cont
1132 Draw contours of an image, labelling the axes using the WCS information
1133 in the FITS header of the image.
1134 $win->fits_cont( image, [$contours, $transform, $misval], [$opt] )
1136 Does the same thing for the cont routine that fits_imag does for the
1138 imag routines.
1139 draw_wedge
1141 Add a wedge (colour bar) to an image.
1142 $win->draw_wedge( [$opt] )
1144 Adds a wedge - shows the mapping between colour and value for a pixel -
1146 to the current image. This can also be achieved by setting "DrawWedge"
1147 to 1 when calling the "imag" routine.
1148 The colour and font size are the same as used to draw the image axes
1150 (although this will probably fail if you did it yourself). To control
1151 the size and location of the wedge, use the "Wedge" option, giving it a
1152 hash reference containing any of the following:
1153 Side
1155 Which side of the image to draw the wedge: can be one of 'B', 'L',
1156 'T', or 'R'. Default is 'R'.
1157 Displacement
1159 How far from the edge of the image should the wedge be drawn, in
1160 units of character size. To draw within the image use a negative
1161 value. Default is 1.5.
1162 Width
1164 How wide should the wedge be, in units of character size. Default
1165 is 2.
1166 Label
1168 A text label to be added to the wedge. If set, it is probably
1169 worth increasing the "Width" value by about 1 to keep the text
1170 readable. Default is ''. This is equivalent to the "WTitle"
1171 option to imag, fits_imag, and similar methods.
1172 ForeGround (synonym Fg)
1174 The pixel value corresponding to the "maximum" colour. If "undef",
1175 uses the value used by "imag" (recommended choice). Default is
1176 "undef".
1177 BackGround (synonym Bg)
1179 The pixel value corresponding to the "minimum" colour. If "undef",
1180 uses the value used by "imag" (recommended choice). Default is
1181 "undef".
1182 $a = rvals(50,50);
1184 $win = PDL::Graphics::PGPLOT::Window->new();
1185 $win->imag( $a, { Justify => 1, ITF => 'sqrt' } );
1186 $win->draw_wedge( { Wedge => { Width => 4, Label => 'foo' } } );
1187 # although the following might be more sensible
1188 $win->imag( $a, { Justify => 1, ITF => 'sqrt', DrawWedge => 1,
1189 Wedge => { Width => 4, Label => 'foo'} } );
1190 ctab
1192 Load an image colour table.
1193 Usage:
1195 ctab ( $name, [$contrast, $brightness] ) # Builtin col table
1197 ctab ( $ctab, [$contrast, $brightness] ) # $ctab is Nx4 array
1198 ctab ( $levels, $red, $green, $blue, [$contrast, $brightness] )
1199 ctab ( '', $contrast, $brightness ) # use last color table
1200 Note: See PDL::Graphics::LUT for access to a large number of colour
1202 tables.
1203 Notionally, all non-RGB images and vectors have their colors looked up
1205 in the window's color table. Colors in images and such are scaled to a
1206 normalized pseudocolor domain on the line segment [0,1]; the color
1207 table is a piecewise linear function that maps this one-dimensional
1208 scale to the three-dimensional normalized RGB color space [0,1]^3.
1209 You can specify specific indexed colors by appropriate use of the
1211 (levels,red,green,blue) syntax -- but that is deprecated, since the
1212 actual available number of colors can change depending on the output
1213 device. (Someone needs to write a specific hardware-dependent lookup
1214 table interface).
1215 See also imag for a description of how to use only part of the color
1217 table for a particular image.
1218 ctab_info
1220 Return information about the currently loaded color table
1221 autolog
1223 Turn on automatic logarithmic scaling in "line" and "points"
1224 Usage: autolog([0|1]);
1226 Setting the argument to 1 turns on automatic log scaling and setting it
1228 to zero turns it off again. The function can be used in both the object
1229 oriented and standard interface. To learn more, see the documentation
1230 for the axis option.
1231 my $win = PDL::Graphics::PGPLOT::Window->new(dev=>'/xserve');
1233 my $x=sequence(10);
1234 my $y=$x*$x+1;
1235 $win->autolog(1);
1237 $win->line($x,$y, {Axis => 'LogY'});
1238 line
1240 Plot vector as connected points
1241 If the 'MISSING' option is specified, those points in the $y vector
1243 which are equal to the MISSING value are not plotted, but are skipped
1244 over. This allows one to quickly draw multiple lines with one call to
1245 "line", for example to draw coastlines for maps.
1246 Usage: line ( [$x,] $y, [$opt] )
1248 The following standard options influence this command:
1250 AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING,
1252 JUSTIFY, SCALE, PITCH, PIX, ALIGN
1253 $x = sequence(10)/10.;
1255 $y = sin($x)**2;
1256 # Draw a red dot-dashed line
1257 line $x, $y, {COLOR => 'RED', LINESTYLE=>3};
1258 lines
1260 Plot a list of vectors as discrete sets of connected points
1261 This works much like line, but for discrete sets of connected points.
1263 There are two ways to break lines: you can pass in x/y coordinates just
1264 like in line, but with an additional "pen" piddle that indicates
1265 whether the pen is up or down on the line segment following each point
1266 (so you set it to zero at the end of each line segment you want to
1267 draw); or you can pass in an array ref containing a list of single
1268 polylines to draw.
1269 Happily, there's extra meaning packed into the "pen" piddle: it
1271 multiplies the COLO(U)R that you set, so if you feed in boolean values
1272 you get what you expect -- but you can also feed in integer or
1273 floating-point values to get multicolored lines.
1274 Furthermore, the sign bit of "pen" can be used to draw hairline
1276 segments: if "pen" is negative, then the segment is drawn as though it
1277 were positive but with LineWidth and HardLW set to 1 (the minimum).
1278 Equally happily, even if you are using the array ref mechanism to break
1280 your polylines you can feed in an array ref of "pen" values to take
1281 advantage of the color functionality or further dice your polylines.
1282 Note that, unlike line, "lines" has no no specify-$y-only calling path.
1284 That's because "lines" is intended more for line art than for plotting,
1285 so you always have to specify both $x and $y.
1286 Infinite or bad values are ignored -- that is to say, if your vector
1288 contains a non-finite point, that point breaks the vector just as if
1289 you set pen=0 for both that point and the point before it.
1290 Usage: $w->lines( $x, $y, [$pen], [$opt] );
1292 $w->lines( $xy, [$pen], [$opt] );
1293 $w->lines( \@xvects, \@yvects, [\@pen], [$opt] );
1294 $w->lines( \@xyvects, [\@pen], [$opt] );
1295 The following standard options influence this command:
1297 AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING,
1298 JUSTIFY, SCALE, PITCH, PIX, ALIGN
1299 CAVEAT:
1301 Setting "pen" elements to 0 prevents drawing altogether, so you can't
1303 use that to draw in the background color.
1304 points
1306 Plot vector as points
1307 Usage: points ( [$x,] $y, [$symbol(s)], [$opt] )
1309 Options recognised:
1311 SYMBOL - Either a piddle with the same dimensions as $x, containing
1313 the symbol associated to each point or a number specifying
1314 the symbol to use for every point, or a name specifying the
1315 symbol to use according to the following (recognised name in
1316 capital letters):
1317 0 - SQUARE 1 - DOT 2 - PLUS 3 - ASTERISK
1318 4 - CIRCLE 5 - CROSS 7 - TRIANGLE 8 - EARTH
1319 9 - SUN 11 - DIAMOND 12- STAR
1320 PLOTLINE - If this is >0 a line will be drawn through the points.
1321 The following standard options influence this command:
1323 AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH,
1325 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1326 "SymbolSize" allows adjusting the symbol size, it defaults to CharSize.
1328 The "ColorValues" option allows one to plot XYZ data with the Z axis
1330 mapped to a color value. For example:
1331 use PDL::Graphics::LUT;
1333 ctab(lut_data('idl5')); # set up color palette to 'idl5'
1334 points ($x, $y, {ColorValues => $z});
1335 $y = sequence(10)**2+random(10);
1337 # Plot blue stars with a solid line through:
1338 points $y, {PLOTLINE => 1, COLOUR => BLUE, symbol => STAR}; # case insensitive
1339 errb
1341 Plot error bars (using "pgerrb()")
1342 Usage:
1344 errb ( $y, $yerrors, [$opt] )
1346 errb ( $x, $y, $yerrors, [$opt] )
1347 errb ( $x, $y, $xerrors, $yerrors, [$opt] )
1348 errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt])
1349 Any of the error bar parameters may be "undef" to omit those error
1351 bars.
1352 Options recognised:
1354 TERM - Length of terminals in multiples of the default length
1356 SYMBOL - Plot the datapoints using the symbol value given, either
1357 as name or number - see documentation for 'points'
1358 The following standard options influence this command:
1360 AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH,
1362 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1363 $y = sequence(10)**2+random(10);
1365 $sigma=0.5*sqrt($y);
1366 errb $y, $sigma, {COLOUR => RED, SYMBOL => 18};
1367 # plot X bars only
1369 errb( $x, $y, $xerrors, undef );
1370 # plot negative going bars only
1372 errb( $x, $y, $xloerr, undef, $yloerr, undef );
1373 cont
1375 Display image as contour map
1376 Usage: cont ( $image, [$contours, $transform, $misval], [$opt] )
1378 Notes: $transform for image/cont etc. is used in the same way as the
1380 "TR()" array in the underlying PGPLOT FORTRAN routine but is,
1381 fortunately, zero-offset. The transform() routine can be used to create
1382 this piddle.
1383 Options recognised:
1385 CONTOURS - A piddle with the contour levels
1387 FOLLOW - Follow the contour lines around (uses pgcont rather than
1388 pgcons) If this is set >0 the chosen linestyle will be
1389 ignored and solid line used for the positive contours
1390 and dashed line for the negative contours.
1391 LABELS - An array of strings with labels for each contour
1392 LABELCOLOUR - The colour of labels if different from the draw colour
1393 This will not interfere with the setting of draw colour
1394 using the colour keyword.
1395 MISSING - The value to ignore for contouring
1396 NCONTOURS - The number of contours wanted for automatical creation,
1397 overridden by CONTOURS
1398 TRANSFORM - The pixel-to-world coordinate transform vector
1399 The following standard options influence this command:
1401 AXIS, BORDER, COLOUR, LINESTYLE, LINEWIDTH,
1403 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1404 $x=sequence(10,10);
1406 $ncont = 4;
1407 $labels= ['COLD', 'COLDER', 'FREEZING', 'NORWAY']
1408 # This will give four blue contour lines labelled in red.
1409 cont $x, {NCONT => $ncont, LABELS => $labels, LABELCOLOR => RED,
1410 COLOR => BLUE}
1411 bin
1413 Plot vector as histogram (e.g. "bin(hist($data))")
1414 Usage: bin ( [$x,] $data )
1416 Options recognised:
1418 CENTRE - (default=1) if true, the x values denote the centre of the
1420 bin otherwise they give the lower-edge (in x) of the bin
1421 CENTER - as CENTRE
1422 The following standard options influence this command:
1424 AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
1426 hi2d
1428 Plot image as 2d histogram (not very good IMHO...)
1429 Usage: hi2d ( $image, [$x, $ioff, $bias], [$opt] )
1431 Options recognised:
1433 IOFFSET - The offset for each array slice. >0 slants to the right
1435 <0 to the left.
1436 BIAS - The bias to shift each array slice up by.
1437 The following standard options influence this command:
1439 AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN
1441 Note that meddling with the "ioffset" and "bias" often will require you
1443 to change the default plot range somewhat. It is also worth noting that
1444 if you have TriD working you will probably be better off using mesh3d
1445 or a similar command - see the PDL::Graphics::TriD module.
1446 $r=sequence(100)/50-1.0;
1448 $y=exp(-$r**2)*transpose(exp(-$r**2))
1449 hi2d $y, {IOFF => 1.5, BIAS => 0.07};
1450 arrow
1452 Plot an arrow
1453 Usage: arrow($x1, $y1, $x2, $y2, [, $opt]);
1455 Plot an arrow from "$x1, $y1" to "$x2, $y2". The arrow shape can be set
1457 using the option "Arrow". See the documentation for general options for
1458 details about this option (and the example below):
1459 Example:
1461 arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 1, Vent => 0.3, Size => 5}});
1463 which draws a broad, large arrow from (0, 1) to (1, 2).
1465 rect
1467 Draw a non-rotated rectangle
1468 Usage: rect ( $x1, $x2, $y1, $y2 )
1470 Options recognised:
1472 The following standard options influence this command:
1474 AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH
1476 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1477 poly
1479 Draw a polygon
1480 Usage: poly ( $x, $y )
1482 Options recognised:
1484 The following standard options influence this command:
1486 AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH
1488 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1489 # Fill with hatching in two different colours
1491 $x=sequence(10)/10;
1492 # First fill with cyan hatching
1493 poly $x, $x**2, {COLOR=>5, FILL=>3};
1494 hold;
1495 # Then do it over again with the hatching offset in phase:
1496 poly $x, $x**2, {COLOR=>6, FILL=>3, HATCH=>{PHASE=>0.5}};
1497 release;
1498 circle
1500 Plot a circle on the display using the fill setting.
1501 Usage: circle($x, $y, $radius [, $opt]);
1503 All arguments can alternatively be given in the options hash using the
1505 following options:
1506 XCenter and YCenter
1508 The position of the center of the circle
1509 Radius
1511 The radius of the circle.
1512 ellipse
1514 Plot an ellipse, optionally using fill style.
1515 Usage: ellipse($x, $y, $a, $b, $theta [, $opt]);
1517 All arguments can alternatively be given in the options hash using the
1519 following options:
1520 MajorAxis
1522 The major axis of the ellipse - this must be defined or $a must be
1523 given.
1524 MinorAxis
1526 The minor axis, like A this is required.
1527 Theta (synonym Angle)
1529 The orientation of the ellipse - defaults to 0.0. This is given in
1530 radians.
1531 XCenter and YCenter
1533 The coordinates of the center of the ellipse. These must be
1534 specified or $x and $y must be given.
1535 NPoints
1537 The number of points used to draw the ellipse. This defaults to 100
1538 and might need changing in the case of very large ellipses.
1539 The routine also recognises the same standard options as accepted by
1541 poly.
1542 rectangle
1544 Draw a rectangle.
1545 Usage: rectangle($xcenter, $ycenter, $xside, $yside, [, $angle, $opt]);
1547 This routine draws a rectangle with the chosen fill style. Internally
1549 it calls poly which is somewhat slower than "pgrect" but which allows
1550 for rotated rectangles as well. The routine recognises the same options
1551 as "poly" and in addition the following:
1552 XCenter and YCenter
1554 The position of the center of the rectangle. XCentre and YCentre
1555 are valid synonyms.
1556 XSide and YSide
1558 The length of the X and Y sides. If only one is specified the shape
1559 is taken to be square with that as the side-length, alternatively
1560 the user can set Side
1561 Side
1563 The length of the sides of the rectangle (in this case a square) -
1564 syntactic sugar for setting XSide and YSide identical. This is
1565 overridden by XSide or YSide if any of those are set.
1566 Angle (synonym Theta)
1568 The angle at which the rectangle is to be drawn. This defaults to
1569 0.0 and is given in radians.
1570 vect
1572 Display 2 images as a vector field
1573 Usage: vect ( $w, $a, $b, [$scale, $pos, $transform, $misval], { opt } );
1575 $w->vect($a,$b,[$scale,$pos,$transform,$misval], { opt });
1576 Notes: $transform for image/cont etc. is used in the same way as the
1578 "TR()" array in the underlying PGPLOT FORTRAN routine but is,
1579 fortunately, zero-offset. The transform() routine can be used to create
1580 this piddle.
1581 This routine will plot a vector field. $a is the horizontal component
1583 and $b the vertical component. The scale factor converts between
1584 vector length units and scientific positional units. You can set the
1585 scale, position, etc. either by passing in parameters in the normal
1586 parameter list or by passing in options.
1587 Options recognised:
1589 SCALE - Set the scale factor for vector lengths.
1591 POS - Set the position of vectors.
1592 <0 - vector head at coordinate
1593 >0 - vector base at coordinate
1594 =0 - vector centered on the coordinate
1595 TRANSFORM - The pixel-to-world coordinate transform vector
1596 MISSING - Elements with this value are ignored.
1597 The following standard options influence this command:
1599 ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR,
1601 LINESTYLE, LINEWIDTH,
1602 $a=rvals(11,11,{Centre=>[5,5]});
1604 $b=rvals(11,11,{Centre=>[0,0]});
1605 vect $a, $b, {COLOR=>YELLOW, ARROWSIZE=>0.5, LINESTYLE=>dashed};
1606 fits_vect
1608 Display a pair of 2-D piddles as vectors, with FITS header
1609 interpretation
1610 Usage: fits_vect ($a, $b, [$scale, $pos, $transform, $misval] )
1612 "fits_vect" is to vect as fits_imag is to imag.
1614 transform
1616 Create transform array for contour and image plotting
1617 $win->transform([$xdim,$ydim], $options);
1619 (For information on coordinate transforms, try PDL::Transform.) This
1621 function creates a transform array in the format required by the image
1622 and contouring routines. You must call it with the dimensions of your
1623 image as arguments or pass these as an anonymous hash - see the example
1624 below.
1625 Angle
1627 The rotation angle of the transform, in radians. Positive numbers
1628 rotate the image clockwise on the screen.
1629 ImageDimensions
1631 The dimensions of the image the transform is required for. The
1632 dimensions should be passed as a reference to an array.
1633 Pixinc
1635 The increment in output coordinate per pixel.
1636 ImageCenter (or ImageCentre)
1638 The centre of the image as an anonymous array or as a scalar, in
1639 scientific coordinates. In the latter case the x and y value for
1640 the center will be set equal to this scalar. This is particularly
1641 useful in the common case when the center is (0, 0). (ImageCenter
1642 overrides RefPos if both are specified).
1643 RefPos (or ReferencePosition)
1645 If you wish to set a pixel other than the image centre to a given
1646 value, use this option. It should be supplied with a reference to
1647 an array containing 2 2-element array references, e.g.
1648 RefPos => [ [ $xpix, $ypix ], [ $xplot, $yplot ] ]
1650 This will label pixel "($xpix,$ypix)" as being at position
1652 "($xplot,$yplot)". For example
1653 RefPos => [ [100,74], [ 0, 0 ] ]
1655 sets the scientific coordinate origin to be at the center of the
1657 (100,74) pixel coordinate. The pixel coordinates are pixel-
1658 centered, and start counting from 0 (as all good pixel coordinates
1659 should).
1660 Example:
1662 $im = rvals(100, 100);
1664 $w = PDL::Graphics::PGPLOT::Window->new(Device => '/xs');
1665 $t = $w->transform(dims($im), {ImageCenter => 0, Pixinc => 5});
1666 $w->imag($im, {Transform => $t});
1667 tline
1669 Threaded line plotting
1670 $win->tline($x, $y, $options);
1672 This is a threaded interface to "line". This is convenient if you have
1674 a 2D array and want to plot out every line in one go. The routine will
1675 apply any options you apply in a "reasonable" way. In the sense that it
1676 will loop over the options wrapping over if there are less options than
1677 lines.
1678 Example:
1680 $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']};
1682 $tx=zeroes(100,5)->xlinvals(-5,5);
1683 $ty = $tx + $tx->yvals;
1684 $win->tline($tx, $ty, $h);
1685 tpoints
1687 A threaded interface to points
1688 Usage: tpoints($x, $y, $options);
1690 This is a threaded interface to "points". This is convenient if you
1692 have a 2D array and want to plot out every line in one go. The routine
1693 will apply any options you apply in a "reasonable" way. In the sense
1694 that it will loop over the options wrapping over if there are less
1695 options than lines.
1696 Example:
1698 $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']};
1700 $tx=zeroes(100,5)->xlinvals(-5,5);
1701 $ty = $tx + $tx->yvals;
1702 tpoints($tx, $ty, $h);
1703 tcircle
1705 A threaded interface to circle
1706 Usage: tcircle($x, $y, $r, $options);
1708 This is a threaded interface to "circle". This is convenient if you
1710 have a list of circle centers and radii and want to draw every circle
1711 in one go. The routine will apply any options you apply in a
1712 "reasonable" way, in the sense that it will loop over the options
1713 wrapping over if there are less options than circles.
1714 Example:
1716 $x=sequence(5);
1718 $y=random(5);
1719 $r=sequence(5)/10 + 0.1;
1720 $h={justify => 1,Color => ['red','green','blue'], filltype => ['solid','outline','hatched','cross_hatched']};
1721 tcircle($x, $y, $r, $h);
1722 Note that $x and $y must be the same size (>1D is OK, though
1724 meaningless as far as "tcircle" is concerned). $r can be the same size
1725 as $x OR a 1-element piddle OR a single perl scalar.
1726 Text routines
1728 text
1729 Write text in a plot window at a specified position.
1730 Usage: text ($text, $x, $y [, $opt])
1732 Options recognised:
1734 "ANGLE"
1736 The angle in degrees between the baseline of the text and the
1737 horisontal (increasing counter-clockwise). This defaults to 0.
1738 "JUSTIFICATION"
1740 The justification of the text relative to the position specified.
1741 It defaults to 0.0 which gives left-justified text. A value of 0.5
1742 gives centered text and a value of 1.0 gives right-justified text.
1743 "XPos", "YPos", "Text"
1745 These gives alternative ways to specify the text and position.
1746 "BackgroundColour"
1748 This sets the background colour for the text in case an opaque
1749 background is desired. You can also use the synonyms "Bg" and
1750 "BackgroundColor".
1751 The following standard options influence this command:
1753 COLOUR, CHARSIZE
1755 line sequence(10), sequence(10)**2;
1757 text 'A parabola', 3, 9, {Justification => 1, Angle=>atan2(6,1)};
1758 legend
1760 Add a legend to a plot
1761 Usage: legend($text, $x, $y, [, $width], $opt]);
1763 This function adds a legend to an existing plot. The action is
1765 primarily controlled by information in the options hash, and the basic
1766 idea is that $x and $y determines the upper left hand corner of the box
1767 in which the legend goes. If the width is specified either as an
1768 argument or as an option in the option hash this is used to determine
1769 the optimal character size to fit the text into part of this width
1770 (defaults to 0.5 - see the description of "TextFraction" below). The
1771 rest of the width is filled out with either lines or symbols according
1772 to the content of the "LineStyle", "Symbol", "Colour" and "LineWidth"
1773 options.
1774 The local options recognised are as follows:
1776 "Text"
1778 An anonymous array of annotations, can also be specified directly.
1779 "XPos" and "YPos"
1781 The X and Y position of the upper left-hand corner of the text.
1782 "Width" and "Height"
1784 The width and/or height of each line (including symbol/line). This
1785 is used to determine the character size. If any of these are set to
1786 'Automatic' the current character size will be used.
1787 "TextFraction"
1789 The text and the symbol/line is set inside a box. "TextFraction"
1790 determines how much of this box should be devoted to text. This
1791 defaults to 0.5. You can also use "Fraction" as a synonym to this.
1792 "TextShift"
1794 This option allows for fine control of the spacing between the text
1795 and the start of the line/symbol. It is given in fractions of the
1796 total width of the legend box. The default value is 0.1.
1797 "VertSpace" or "VSpace"
1799 By default the text lines are separated by one character height (in
1800 the sense that if the separation were 0 then they would lie on top
1801 of each other). The "VertSpace" option allows you to increase (or
1802 decrease) this gap in units of the character height; a value of 0.5
1803 would add half a character height to the gap between lines, and
1804 -0.5 would remove the same distance. The default value is 0.
1805 "BackgroundColour"
1807 This sets the background colour for the text in case an opaque
1808 background is desired. You can also use the synonyms "Bg" and
1809 "BackgroundColor".
1810 line $x, $y, {Color => 'Red', LineStyle => 'Solid'};
1812 line $x2, $y2, {Color => 'Blue', 'LineStyle' => 'Dashed', LineWidth => 10};
1813 legend ['A red line', 'A blue line'], 5, 5,
1815 {LineStyle => ['Solid', 'Dashed'], Colour => ['Red', 'Blue']
1816 LineWidth => [undef, 10]}; # undef gives default.
1817 Cursor routines
1819 cursor
1820 Interactively read cursor positions.
1821 Usage: ($x, $y, $ch, $xref, $yref) = cursor($opt)
1823 This routine has no standard input parameters, but the type of cursor
1825 can be set by setting the option "Type" as a key in the anonymous hash
1826 $opt. The first three return values from the function are always
1827 defined and gives the position selected by the user and the character
1828 pressed.
1829 Depending on the cursor type selected the last two arguments might also
1831 be defined and these give a reference position. For instance if the
1832 cursor is selected to be "Rectangle" then the reference position gives
1833 one of the corners of the rectangle and $x and $y the diagonally
1834 opposite one.
1835 Options recognised:
1837 XRef, YRef
1839 The reference position to be used
1840 Type
1842 The type of cursor. This can be selected using a number between 0
1843 and 7 as in PGPLOT, or alternatively you can specify these as,
1844 "Default" (0), "RadialLine" (1), "Rectangle" (2),
1845 "TwoHorizontalLines" (3), "TwoVerticalLines" (4), "HorizontalLine"
1846 (5), "VerticalLine" (6) and "CrossHair" (7) respectively. The
1847 default cursor is just the normal mouse cursor.
1848 For the "RadialLine" you must specify the reference point, whereas
1850 for the "Two(Vertical|Horizontal)Lines" cursor the X or Y reference
1851 point, respectively, must be specified.
1852 To select a region on a plot, use the rectangle cursor:
1854 ($x, $y, $ch, $xref, $yref) = cursor({Type => 'Rectangle'});
1856 poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y);
1857 To select a region of the X-axis:
1859 ($x1, $y1, $ch) = cursor({Type => 'VerticalLine'});
1861 ($x2, $y2, $ch) = cursor({Type => 'TwoVerticalLines', XRef => $x1});
1862
1864 signal_catcher, catch_signals, release_signals
1865 To prevent pgplot from doing a fandango on core, we have to block
1866 interrupts during PGPLOT calls. Specifically, INT needs to get caught.
1867 These internal routines provide a mechanism for that.
1868 You simply bracket any PGPLOT calls with &catch_signals above and
1870 &release_signals below, and the signal_catcher will queue up any
1871 signals (like INT -- the control-C interrupt) until the
1872 &release_signals call.
1873 Any exit path from your hot code must include &release_signals, or
1875 interrupts could be deferred indefinitely (which would be a bug). This
1876 includes calls to &barf -- even barfs from someone you called! So
1877 avoid calling out of the local module if possible, and use
1878 release_and_barf() instead of barf() from within this module.
1879 Perl 5.6.1 interrupt handling has a bug that this code tickles --
1881 sometimes the re-emitted signals vanish into hyperspace. Perl 5.8
1882 seems NOT to have that problem.
1883 _open_new_window
1885 Open a new window. This sets the window ID, which is the one used when
1886 accessing a window later using "pgslct". It also sets the window name
1887 to something easily remembered if it has not been set before.
1888 _setup_window
1890 This routine sets up a new window with its shape and size. This is also
1891 where the size options are actually parsed. These are then forgotten
1892 (well, they are stored in $self->{Options}) and the corresponding
1893 aspect ratio and window width is stored. See the discussion under
1894 new() for the logic.
1895 Finally the subpanels are set up using "pgsubp" and colours and
1897 linewidth are adjusted according to whether we have a hardcopy device
1898 or not.
1899 _status
1901 This routine checks PGPLOT's status for the window. It returns OPEN if
1902 the window is open and CLOSED if it is closed. (Windows can be closed
1903 but still exist).
1904 _reopen
1906 This functions reopens a window. Since this is an internal function it
1907 does not have a lot of error-checking. Make sure the device is closed
1908 before calling this routine.
1909 There is an unfortunate problem which pops up viz. that the window name
1911 cannot be changed at this point since we are offering that to the rest
1912 of the world. That might be sensible, but it means that the window name
1913 will not reflect the id of the window - use "id()" for that (this is
1914 also why we do not call "open_new_window" )
1915 _advance_panel
1917 This routine advances one plot panel, updating the CurrentPanel as
1918 well. If the advance will proceed past the page the page will be
1919 erased. Also note that when you advance one panel the hold value will
1920 be changed.
1921 _check_move_or_erase
1923 This routine is a utility routine which checks if we need to move
1924 panel, and if so will do this. It also checks if it is necessary to
1925 advance panels, and whether they need to be erased.
1926 _thread_options
1928 This function is a cludgy utility function that expands an options hash
1929 to an array of hashes looping over options. This is mainly of use for
1930 "threaded" interfaces to standard plotting routines.
1931 options
1933 Access the options used when originally opening the window. At the
1934 moment this is not updated when the window is changed later.
1935 id
1937 Access the window ID that PGPLOT uses for the present window.
1938 device
1940 This function returns the device type of the present window.
1941 name
1943 Accessor to set and examine the name of a window.
1944 focus
1946 Set focus for subsequent PGPLOT commands to this window.
1947 info
1949 Get general information about the PGPLOT environment.
1950 @ans = $self->info( @item );
1952 The valid values of @item are as below, where case is not important:
1954 VERSION - What PGPLOT version is in use.
1956 STATE - The status of the output device, this is returns 'OPEN'.
1957 if the device is open and 'CLOSED' otherwise.
1958 USER - The username of the owner of the spawning program.
1959 NOW - The current date and time in the format
1960 'dd-MMM-yyyy hh:mm'. Most people are likely to use Perl
1961 functions instead.
1962 DEVICE * - The current PGPLOT device or file, see also device().
1963 FILE * - The filename for the current device.
1964 TYPE * - And the device type for the current device.
1965 DEV/TYPE * - This combines DEVICE and TYPE in a form that can be used
1966 as input to new.
1967 HARDCOPY * - This is flag which is set to 'YES' if the current device is
1968 a hardcopy device and 'NO' otherwise.
1969 TERMINAL * - This flag is set to 'YES' if the current device is the
1970 user's terminal and 'NO' otherwise.
1971 CURSOR * - A flag ('YES' or 'NO') to inform whether the current device
1972 has a cursor.
1973 Those items marced with a "*" only return a valid answer if the window
1975 is open. A question mark ("?") is returned if the item is not
1976 recognised or the information is not available.
1977 _extract_hash
1979 This routine takes and array and returns the first hash reference found
1980 as well as those elements that are not hashes. Note the latter point
1981 because all other references to hashes in the array will be lost.
1982 _parse_unit
1984 Convert a unit string or number into a PGPLOT-certified length unit
1985 specification, or return undef if it won't go.
1986 _parse_options
1988 This is a convenience routine for parsing a set of options. It returns
1989 both the full set of options and those that the user has set.
1990 _save_status
1992 Saves the PGPLOT state so that changes to settings can be made and then
1993 the present state restored by "_restore_status".
1994 _restore_status
1996 Restore the PGPLOT state. See "_save_status".
1997 _checkarg
1999 This routine checks and optionally alters the arguments given to it.
2000 _set_colour
2002 This is an internal routine that encapsulates all the nastiness of
2003 setting colours depending on the different PGPLOT colour models
2004 (although HLS is not supported).
2005 The routine works in the following way:
2007 · At initialisation of the plot device the work colour index is
2009 set to 16. The work index is the index the routine will modify
2010 unless the user has specified something else.
2011 · The routine should be used after standard interpretation and
2013 synonym matching has been used. So if the colour is given as
2014 input is an integer that colour index is used.
2015 · If the colour is a reference the routine checks whether it is
2017 an "ARRAY" or a "PDL" reference. If it is not an error message
2018 is given. If it is a "PDL" reference it will be converted to
2019 an array ref.
2020 · If the array has four elements the first element is interpreted
2022 as the colour index to modify and this overrules the setting
2023 for the work index used internally. Otherwise the work index is
2024 used and incremented until the maximum number of colours for
2025 the output device is reached (as indicated by "pgqcol"). Should
2026 you wish to change that you need to read the PGPLOT
2027 documentation - it is somewhat device dependent.
2028 · When the array has been recognised the R,G and B colours of the
2030 user-set index or work index is set using the "pgscr" command
2031 and we are finished.
2032 · If the input colour instead is a string we try to set the
2034 colour using the PGPLOT routine "pgscrn" with no other error-
2035 checking. This should be ok, as that routine returns a rather
2036 sensible error-message.
2037 _standard_options_parser
2039 This internal routine is the default routine for parsing options. This
2040 routine deals with a subset of options that most routines will accept.
2041 _image_xyrange
2043 Given a PGPLOT tr matrix and an image size, calculate the data world
2044 coordinates over which the image ranges. This is used in imag and
2045 cont. It keeps track of the required half-pixel offset to display
2046 images properly -- eg feeding in no tr matrix at all, nx=20, and ny=20
2047 will will return (-0.5,19.5,-0.5,19.5). It also checks the options
2048 hash for XRange/YRange specifications and, if they are present, it
2049 overrides the appropriate output with the exact ranges in those fields.
2050 _FITS_tr
2052 Given a FITS image, return the PGPLOT transformation matrix to convert
2053 pixel coordinates to scientific coordinates. Used by fits_imag,
2054 fits_rgbi, and fits_cont, but may come in handy for other methods.
2055 my $tr = _FITS_tr( $win, $img );
2057 my $tr = _FITS_tr( $win, $img, $opts );
2058 The return value ($tr in the examples above) is the same as returned by
2060 the transform() routine, with values set up to convert the pixel to
2061 scientific coordinate values for the two-dimensional image $img. The
2062 $opts argument is optional and should be a HASH reference; currently it
2063 only understands one key (any others are ignored):
2064 WCS => undef (default), "", or "A" to "Z"
2066 Both the key name and value are case insensitive. If left as "undef" or
2068 "" then the primary coordinate mapping from the header is used,
2069 otherwise use the additional WCS mapping given by the appropriate
2070 letter. We make no checks that the given mapping is available; the
2071 routine falls back to the unit mapping if the specified system is not
2072 available.
2073 The WCS option has only been tested on images from the Chandra X-ray
2075 satellite (<http://chandra.harvard.edu/>) created by the CIAO software
2076 package (<http://cxc.harvard.edu/ciao/>), for which you should set "WCS
2077 => "P"" to use the "PHYSICAL" coordinate system.
2078 See <http://fits.cv.nrao.edu/documents/wcs/wcs.html> for further
2080 information on the Representation of World Coordinate Systems in FITS.
2081
2083 The coding tries to follow reasonable standards, so that all functions
2084 starting with an underscore should be considered as internal and should
2085 not be called from outside the package. In addition most routines have
2086 a set of options. These are encapsulated and are not accessible outside
2087 the routine. This is to avoid collisions between different variables.
2088
2090 Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann
2091 (jarle@astro.ox.ac.uk) who is also responsible for the OO interface,
2092 docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian
2093 Soeller (c.soeller@auckland.ac.nz). Further contributions and bugfixes
2094 from Kaj Wiik, Doug Burke, Craig DeForest, and many others.
2095 All rights reserved. There is no warranty. You are allowed to
2097 redistribute this software / documentation under certain conditions.
2098 For details, see the file COPYING in the PDL distribution. If this file
2099 is separated from the PDL distribution, the copyright notice should be
2100 included in the file.
2101perl v5.30.0 2019-09-05 Window(3)