1Window(3) User Contributed Perl Documentation Window(3)
2
6 PDL::Graphics::PGPLOT::Window - A OO interface to PGPLOT windows
7
9 perldl> use PDL::Graphics::PGPLOT::Window
10 perldl> $win = pgwin(Device => '/xs');
11 perldl> $a = pdl [1..100]
12 perldl> $b = sqrt($a)
13 perldl> $win->line($b)
14 perldl> $win->hold()
15 perldl> $c = sin($a/10)*2 + 4
16 perldl> $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 PDL::Graph‐
25 ics::PGPLOT and contains interfaces to a large number of PGPLOT rou‐
26 tines. Below the usage examples for each function tend to be given in
27 the non-OO version for historical reasons. This will slowly be changed,
28 but in the meantime refer to the section on OO-interface below to see
29 how to convert the usage information below to OO usage (it is totally
30 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, fortu‐
85 nately, zero-offset. The transform() routine can be used to create this
86 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
97 "get_dataref" to get the reference to the values. Before passing to
98 pgplot routines however, the data are checked to see if they are in
99 accordance with the format (typically dimensionality) required by the
100 PGPLOT routines. This is done using the routine "checkarg" (internal
101 to PGPLOT). This routine checks the dimensionality of the input data.
102 If there are superfluous dimensions of size 1 they will be trimmed away
103 until the dimensionality is correct. Example:
104 Assume a piddle with dimensions (1,100,1,1) is passed to "line", which
106 expects its inputs to be vectors. "checkarg" will then return a piddle
107 with dimensions (100). If instead the same piddle was passed to "imag",
108 which requires 2D piddles as output, "checkarg" would return a piddle
109 with dimensionality (100, 1) (Dimensions are removed from the start)
110 Thus, if you want to provide support for another PGPLOT function, the
112 structure currently look like this (there are plans to use the Options
113 package to simplify the options parsing):
114 # Extract the hash(es) on the commandline
116 ($arg, $opt)=_extract_hash(@_);
117 <Check the number of input parameters>
118 <deal with $arg>
119 checkarg($x, 3); # For a hypothetical 3D routine.
120 &catch_signals;
121 ...
122 pgcube($n, $x->get_dataref);
123 &release_signals;
124 1;
125 (the catch_signals/release_signals pair prevent problems with the perl-
127 PGPLOT interface if the user hits c-C during an operation).
128 Setting options
130 All routines in this package take a hash with options as an optional
132 input. This options hash can be used to set parameters for the subse‐
133 quent plotting without going via the PGPLOT commands.
134 This is implemented such that the plotting settings (such as line
136 width, line style etc.) are affected only for that plot, any global
137 changes made, say, with "pgslw()" are preserved. Some modifications
138 apply when using the OO interface, see below.
139 Alphabetical listing of standard options
141 The following options are always parsed. Whether they have any impor‐
143 tance depend on the routine invoked - e.g. line style is irrelevant for
144 "imag", or the "justify" option is irrelevant if the display is on
145 'hold'. This is indicated in the help text for the commands below.
146 The options are not case sensitive and will match for unique sub‐
148 strings, but this is not encouraged as obscure options might invalidate
149 what you thought was a unique substring.
150 In the listing below examples are given of each option. The actual
152 option can then be used in a plot command by specifying it as an argu‐
153 ment to the function wanted (it can be placed anywhere in the command
154 list).
155 E.g:
157 $opt={COLOR=>2};
159 line $x, $y, $opt; # This will plot a line with red color
160 If you are plotting to a hardcopy device then a number of options use a
162 different name:
163 HardLW instead of LineWidth
165 HardCH instead of CharSize
166 HardFont instead of Font
167 HardAxisColour instead of AxisColour
169 HardColour instead of Colour
170 [although I'm not sure when HardColour is actually used]
172 align
174 If "pix" is set, then images and plots are not stretched to fill
175 the plot area. the "align" string tells how to align them within
176 the available area. 'L' and 'R' shove the plot against the left
177 and right edges, respectively; 'B' and 'T' shove the plot against
178 the bottom and top edges. The default is to center the image.
179 e.g. 'BL' puts the image on the bottom left corner, while 'CT' cen‐
180 ters the image horizontally while placing it at the top of the
181 available plot area. This defaults to 'BT' for non-justified
182 images, to 'CC' for justified images.
183 arrow
185 This options allows you to set the arrow shape, and optionally size
186 for arrows for the vect routine. The arrow shape is specified as a
187 hash with the key FS to set fill style, ANGLE to set the opening
188 angle of the arrow head, VENT to set how much of the arrow head is
189 cut out and SIZE to set the arrowsize.
190 The following
192 $opt = {ARROW => {FS=>1, ANGLE=>60, VENT=>0.3, SIZE=>5}};
194 will make a broad arrow of five times the normal size.
196 Alternatively the arrow can be specified as a set of numbers corre‐
198 sponding to an extention to the syntax for pgsah. The equivalent to
199 the above is
200 $opt = {ARROW => pdl([1, 60, 0.3, 5})};
202 For the latter the arguments must be in the given order, and if any
204 are not given the default values of 1, 45, 0.3 and 1.0 respectively
205 will be used.
206 arrowsize
208 The arrowsize can be specified separately using this option to the
209 options hash. It is useful if an arrowstyle has been set up and one
210 wants to plot the same arrow with several sizes. Please note that
211 it is not possible to set arrowsize and character size in the same
212 call to a plotting function. This should not be a problem in most
213 cases.
214 $opt = {ARROWSIZE => 2.5};
216 axis
218 Set the axis value (see "env"). If you pass in a scalar you set
219 the axis for the whole plot. You can also pass in an array ref for
220 finer control of the axes.
221 If you set the option to a scalar value, you get one of a few stan‐
223 dard layouts. You can specify them by name or by number:
224 EMPTY (-2) draw no box, axes or labels
226 BOX (-1) draw box only
227 NORMAL (0) draw box and label it with coordinates
228 AXES (1) same as NORMAL, but also draw (X=0,Y=0) axes
229 GRID (2) same as AXES, but also draw grid lines
230 LOGX (10) draw box and label X-axis logarithmically
231 LOGY (20) draw box and label Y-axis logarithmically
232 LOGXY (30) draw box and label both axes logarithmically
233 When using logarithmic axes ("LOGX", "LOGY" and "LOGXY") you nor‐
235 mally need to log the data yourself, e.g.
236 line $x->log10, $y, {axis=>'LOGX'};
238 For your convenience you can put PDL::Graphics::PGPLOT into autolog
240 mode. In this mode a call to "line" or "points" will log the data
241 for you and you can pass in the unmodified data, e.g.
242 autolog(1); # enable automatic logarithm calculation
244 line $x, $y, {axis=>'LOGX'}; # automatically displays logged x data
245 You can use the function interface to enable autologging:
247 autolog(1);
249 or use it with a window reference (mode switching on a per window
251 basis)
252 $win->autolog(1);
254 "autolog" without arguments returns the current autolog setting
256 (0=off, 1=on).
257 If you set the "AXIS" option to an array ref, then you can specify
259 the box/axis options separately for the horizontal (ordinate; X
260 coordinate; 0th element) and vertical (abscissa; Y coordinate; 1st
261 element)) axes. Each element of the array ref should contain a
262 PGPLOT format string. Presence or absence of specific characters
263 flags particular options. For normal numeric labels, the options
264 are:
265 A : draw axis for this dimension.
267 B : draw bottom (X) or left (Y) edge of frame.
268 C : draw top (X) or right (Y) edge of frame.
269 G : draw Grid of vertical (X) or horizontal (Y) lines.
270 I : Invert ticks: draw them outside the plot rather than inside.
271 L : Label the axis Logarithmically.
272 P : Extend ("Project") major tick marks outside the box.
273 M : Numeric labels go in the alternate place above (X) or to the
274 right (Y) of the viewport.
275 N : Numeric labels go in the usual location below (X) or to the
276 left (Y) of the viewport
277 T : Draw major tick marks at the major coordinate interval.
278 S : Draw minor tick marks (subticks).
279 V : Orient numeric labels Vertically. Only applicable to Y.
280 (The default is to write them parallel to the axis.)
281 1 : Force decimal labelling, instead of automatic choice
282 2 : Force exponential labeling, instead of automatic.
283 If you don't specify any axis value at all, the default is
285 ['BCNST','BCNST'] for plots and ['BCINST','BCINST'] for images.
286 (These list ref elements are handed on directly to the low-level
287 PGPLOT routines).
288 In addition, you can specify that your axis labels should be
290 printed as days, hours, minutes, and seconds (ideal for julian
291 dates and delta-t, or for angular quantities). You do that by set‐
292 ting additional character flags on the affected axis:
293 X : Use HH MM SS.S time labeling rather than conventional numeric
295 labels. The ordinate is in secsonds. Hours roll over at 24.
296 Y : Like 'X' but the hour field runs past 24 if necessary.
297 Z : Like 'X' but with a days field too (only shown where nonzero).
298 H : Label the numbers with superscript d, h, m, and s symbols.
299 D : Label the numbers with superscript o, ', and '' symbols.
300 F : Omit first (lowest/leftmost) label; useful for tight layouts.
301 O : Omit leading zeroes in numbers under 10 (e.g. " 3h 3m 1.2s"
302 rather than "03h 03m 01.2s").
303 For example, to plot a numeric quantity versus Julian day of the
305 year in a standard boxed plot with tick marks, you can use ["BNC‐
306 STZHO","BCNST"].
307 border
309 Normally the limits are chosen so that the plot just fits; with
310 this option you can increase (or decrease) the limits by either a
311 relative (ie a fraction of the original axis width) or an absolute
312 amount. Either specify a hash array, where the keys are "TYPE"
313 (set to 'relative' or 'absolute') and "VALUE" (the amount to change
314 the limits by), or set to 1, which is equivalent to
315 BORDER => { TYPE => 'rel', VALUE => 0.05 }
317 charsize
319 Set the character/symbol size as a multiple of the standard size.
320 $opt = {CHARSIZE => 1.5}
322 The HardCH option should be used if you are plotting to a hardcopy
324 device.
325 colour (or color)
327 Set the colour to be used for the subsequent plotting. This can be
328 specified as a number, and the most used colours can also be speci‐
329 fied with name, according to the following table (note that this
330 only works for the default colour map):
331 0 - WHITE 1 - BLACK 2 - RED 3 - GREEN 4 - BLUE
333 5 - CYAN 6 - MAGENTA 7 - YELLOW 8 - ORANGE 14 - DARKGRAY
334 16 - LIGHTGRAY
335 However there is a much more flexible mechanism to deal with
337 colour. The colour can be set as a 3 or 4 element anonymous array
338 (or piddle) which gives the RGB colours. If the array has four ele‐
339 ments the first element is taken to be the colour index to change.
340 For normal work you might want to simply use a 3 element array with
341 R, G and B values and let the package deal with the details. The
342 R,G and B values go from 0 to 1.
343 In addition the package will also try to interpret non-recognised
345 colour names using the default X11 lookup table, normally using the
346 "rgb.txt" that came with PGPLOT.
347 For more details on the handling of colour it is best that the user
349 consults the PGPLOT documentation. Further details on the handling
350 of colour can be found in the documentation for the internal rou‐
351 tine "_set_colour".
352 The HardColour option should be used if you are plotting to a hard‐
354 copy device [this may be untrue?].
355 diraxis
357 This sets the direction of the axes of a plot or image, when you
358 don't explitly set them with the XRange and YRange options. It's
359 particularly useful when you want (for example) to put long wave‐
360 lengths (larger numbers) on the left hand side of your plot, or
361 when you want to plot an image in (RA,dec) coordinates.
362 You can use either a scalar or a two-element perl array. If you
364 set it to 0 (the default) then PDL will guess which direction you
365 want to go. If you set it to a positive number, the axis will
366 always increase to the right. If you set it to a negative number,
367 the axis will always increase to the left.
368 For example, [0,0] is the default, which is usually right. [1,1]
370 tells PGPLOT to always increase the axis values up and to the
371 right. For a plot of intensity (y-axis) versus wavelength (x-axis)
372 you could say [-1,1].
373 This option is really only useful if you want to allow autoranging
375 but need to set the direction that the axis goes. If you use the
376 ranging options ("XRange" and "YRange"), you can change the direc‐
377 tion by changing the order of the maximum and minimum values. That
378 direction will override "DirAxis".
379 filltype
381 Set the fill type to be used by "poly", "circle", "ellipse", and
382 "rectangle" The fill can either be specified using numbers or name,
383 according to the following table, where the recognised name is
384 shown in capitals - it is case-insensitive, but the whole name must
385 be specified.
386 1 - SOLID
388 2 - OUTLINE
389 3 - HATCHED
390 4 - CROSS_HATCHED
391 $opt = {FILLTYPE => 'SOLID'};
393 (see below for an example of hatched fill)
395 font
397 Set the character font. This can either be specified as a number
398 following the PGPLOT numbering or name as follows (name in capi‐
399 tals):
400 1 - NORMAL
402 2 - ROMAN
403 3 - ITALIC
404 4 - SCRIPT
405 (Note that in a string, the font can be changed using the escape
407 sequences "\fn", "\fr", "\fi" and "\fs" respectively)
408 $opt = {FONT => 'ROMAN'};
410 gives the same result as
412 $opt = {FONT => 2};
414 The HardFont option should be used if you are plotting to a hard‐
416 copy device.
417 hatching
419 Set the hatching to be used if either fillstyle 3 or 4 is selected
420 (see above) The specification is similar to the one for specifying
421 arrows. The arguments for the hatching is either given using a
422 hash with the key ANGLE to set the angle that the hatch lines will
423 make with the horizontal, SEPARATION to set the spacing of the
424 hatch lines in units of 1% of "min(height, width)" of the view sur‐
425 face, and PHASE to set the offset the hatching. Alternatively this
426 can be specified as a 1x3 piddle "$hatch=pdl[$angle, $sep,
427 $phase]".
428 $opt = {FILLTYPE => 'HATCHED',
430 HATCHING => {ANGLE=>30, SEPARATION=>4}};
431 Can also be specified as
433 $opt = {FILL=> 'HATCHED', HATCH => pdl [30,4,0.0]};
435 For another example of hatching, see "poly".
437 justify
439 If "justify" is set true, then the plot axes are shrunk to fit the
440 plot or image and it specifies the aspect ratio of pixel coordi‐
441 nates in the plot or image. Setting justify=>1 will produce a cor‐
442 rect-aspect-ratio, shrink-wrapped image or plot; setting jus‐
443 tify=>0.5 will do the same thing but with a short and fat plot.
444 The difference between "justify" and "pix" is that "pix" does not
445 affect the shape of the axes themselves.
446 linestyle
448 Set the line style. This can either be specified as a number fol‐
449 lowing the PGPLOT numbering:
450 1 - SOLID line
452 2 - DASHED
453 3 - DOT-DASH-dot-dash
454 4 - DOTTED
455 5 - DASH-DOT-DOT-dot
456 or using name (as given in capitals above). Thus the following two
458 specifications both specify the line to be dotted:
459 $opt = {LINESTYLE => 4};
461 $varopt = {LINESTYLE => 'DOTTED'};
462 The names are not case sensitive, but the full name is required.
464 linewidth
466 Set the line width. It is specified as a integer multiple of 0.13
467 mm.
468 $opt = {LINEWIDTH => 10}; # A rather fat line
470 The HardLW option should be used if you are plotting to a hardcopy
472 device.
473 pitch
475 Sets the number of data pixels per inch on the output device. You
476 can set the "unit" (see below) to change this to any other PGPLOT
477 unit (millimeters, pixels, etc.). Pitch is device independent, so
478 an image should appear exactly the same size (e.g. "Pitch=>100" is
479 100 dpi) regardless of output device.
480 pix Sets the pixel aspect ratio height/width. The height is adjusted
482 to the correct ratio, while maintaining any otherwise-set pitch or
483 scale in the horizontal direction. Larger numbers yield tall,
484 skinny pixels; smaller numbers yield short, fat pixels.
485 scale
487 Sets the number of output display pixels per data pixel. You can
488 set the "unit" (see below) to change this to number of PGPLOT units
489 (inches, millimeters, etc.) per data pixel. "scale" is deprecated,
490 as it is not device-independent; but it does come in handy for
491 quick work on digital displays, where aliasing might otherwise
492 interfere with image interpretation. For example, "scale=>1" dis‐
493 plays images at their native resolution.
494 Panel
496 It is possible to define multiple plot ``panels'' with in a single
497 window (see the NXPanel and NYPanel options in the constructor).
498 You can explicitly set in which panel most plotting commands occur,
499 by passing either a scalar or an array ref into the "Panel" option.
500 There is also a panel method, but its use is deprecated because of
501 a wart with the PGPLOT interface.
502 plotting & imaging range
504 Explicitly set the plot range in x and y. X-range and Y-range are
505 set separately via the aptly named options "XRange" and "YRange".
506 If omitted PGPLOT selects appropriate defaults (minimum and maximum
507 of the data range in general). These options are ignored if the
508 window is on hold.
509 line $x, $y, {xr => [0,5]}; # y-range uses default
511 line $x, $y, {XRange => [0,5], YRange => [-1,3]}; # fully specified range
512 imag $im, {XRange => [30,50], YRange=>[-10,30]};
513 fits_imag $im, {XRange=>[-2,2], YRange=>[0,1]};
514 Imaging requires some thought if you don't want to lose a pixel off
516 the edge of the image. Pixels are value-centered (they are cen‐
517 tered on the coordinate whose value they represent), so the appro‐
518 priate range to plot the entirety of a 100x100 pixel image is
519 "[-0.5,99.5]" on each axis.
520
522 This section will briefly describe how the PDL::Graphics::PGPLOT::Win‐
523 dow package can be used in an object-oriented (OO) approach and what
524 the advantages of this would be. We will start with the latter
525 Multiple windows.
527 For the common user it is probably most interesting to use the OO
528 interface when handling several open devices at the same time. If
529 you have one variable for each plot device it is easier to distrib‐
530 ute commands to the right device at the right time. This is the
531 angle we will take in the rest of this description.
532 Coding and abstraction
534 At a more fundamental level it is desirable to approach a situation
535 where it is possible to have a generic plotting interface which
536 gives access to several plotting libraries, much as PGPLOT gives
537 access to different output devices. Thus in such a hypothetical
538 package one would say:
539 my $win1 = Graphics::new('PGPLOT', {Device => '/xs'});
541 my $win2 = Graphics::new('gnuplot', {Background => 'Gray'};
542 From a more practical point of of view such abstraction also comes
544 in handy when you write a large program package and you do not want
545 to import routines nilly-willy in which case an OO approach with
546 method calls is a lot cleaner.
547 The pgwin exported constructor, arguably, breaks this philosophy;
549 hopefully it will ``wither away'' when other compatible modules are
550 available.
551 Anyway, enough philosophizing, let us get down to Earth and give some
553 examples of the use of OO PGPLOT. As an example we will take Odd (which
554 happens to be a common Norwegian name) who is monitoring the birth of
555 rabbits in O'Fib-o-nachy's farm (alternatively he can of course be mon‐
556 itoring processes or do something entirely different). Odd wants the
557 user to be able to monitor both the birth rates and accumulated number
558 of rabbits and the spatial distribution of the births. Since these are
559 logically different he chooses to have two windows open:
560 $rate_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw',
562 Aspect => 1, WindowWidth => 5, NXPanel => 2);
563 $area_win = PDL::Graphics::PGPLOT::Window->new(Device => '/xw',
565 Aspect => 1, WindowWidth => 5);
566 See the documentation for new below for a full overview of the options
568 you can pass to the constructor.
569 Next, Odd wants to create plotting areas for subsequent plots and maybe
571 show the expected theoretical trends
572 $rate_win->env(0, 10, 0, 1000, {XTitle => 'Days', YTitle => '#Rabbits'});
574 $rate_win->env(0, 10, 0, 100, {Xtitle=>'Days', Ytitle => 'Rabbits/day'});
575 $area_win->env(0, 1, 0, 1, {XTitle => 'Km', Ytitle => 'Km'});
577 # And theoretical prediction.
578 $rate_win->line(sequence(10), fibonacci(10), {Panel => [1, 1]});
579 That is basically it. The commands should automatically focus the rele‐
581 vant window. Due to the limitations of PGPLOT this might however lead
582 you to plot in the wrong panel... The package tries to be smart and do
583 this correctly, but might get it wrong at times.
584
586 A new addition to the graphics interface is the ability to record plot
587 commands. This can be useful when you create a nice-looking plot on the
588 screen that you want to re-create on paper for instance. Or if you want
589 to redo it with slightly changed variables for instance. This is still
590 under development and views on the interface are welcome.
591 The functionality is somewhat detached from the plotting functions
593 described below so I will discuss them and their use here.
594 Recording is off by default. To turn it on when you create a new device
596 you can set the "Recording" option to true, or you can set the
597 $PDL::Graphics::PGPLOT::RECORDING variable to 1. I recommend doing the
598 latter in your ".perldlrc" file at least since you will often have use
599 for recording in the perldl script.
600 Use of recording
602 The recording is meant to help you recreate a plot with new data or to
604 a different device. The most typical situation is that you have created
605 a beautiful plot on screen and want to have a Postscript file with it.
606 In the dreary old world you needed to go back and execute all commands
607 manually, but with this wonderful new contraption, the recorder, you
608 can just replay your commands:
609 dev '/xs', {Recording => 1}
611 $x = sequence(10)
612 line $x, $x**2, {Linestyle => 'Dashed'}
613 $s = retrieve_state() # Get the current tape out of the recorder.
614 dev '/cps'
615 replay $s
616 This should result in a "pgplot.ps" file with a parabola drawn with a
618 dashed line. Note the command "retrieve_state" which retrieves the cur‐
619 rent state of the recorder and return an object (of type PDL::Graph‐
620 ics::State) that is used to replay commands later.
621 Controlling the recording
623 Like any self-respecting recorder you can turn the recorder on and off
625 using the "turn_on_recording" and "turn_off_recording" respectively.
626 Likewise you can clear the state using the "clear_state" command.
627 $w=PDL::Graphics::PGPLOT::Window->new(Device => '/xs');
629 $w->turn_on_recording;
630 $x=sequence(10); $y=$x*$x;
631 $w->line($x, $y);
632 $w->turn_off_recording;
633 $w->line($y, $x);
634 $w->turn_on_recording;
635 $w->line($x, $y*$x);
636 $state = $w->retrieve_state();
637 We can then replay $state and get a parabola and a cubic plot.
639 $w->replay($state);
641 Tips and Gotchas!
643 The data are stored in the state object as references to the real data.
645 This leads to one good and one potentially bad consequence:
646 The good is that you can create the plot and then subsequently redo the
648 same plot using a different set of data. This is best explained by an
649 example. Let us first create a simple gradient image and get a copy of
650 the recording:
651 $im = sequence(10,10)
652 imag $im
653 $s=retrieve_state
654 Now this was a rather dull plot, and in reality we wanted to show
656 an image using "rvals". Instead of re-creating the plot (which of
657 course here would be the simplest option) we just change $im:
658 $im -= sequence(10,10)
660 $im += rvals(10,10)
661 Now replay the commands
663 replay $s
665 And hey presto! A totally different plot. Note however the trickery
667 required to avoid losing reference to $im
668 This takes us immediately to the major problem with the recording
670 though. Memory leakage! Since the recording keeps references to the
671 data it can keep data from being freed (zero reference count) when you
672 expect it to be. For instance, in this example, we lose totally track
673 of the original $im variable, but since there is a reference to it in
674 the state it will not be freed
675 $im = sequence(1000,1000)
676 imag $im
677 $s = retrieve_state
678 $im = rvals(10,10)
679 Thus after the execution of these commands we still have a refer‐
681 ence to a 1000x1000 array which takes up a lot of memory...
682 The solution is to call "clear" on the state variable:
684 $s->clear()
686 (This is done automatically if the variable goes out of scope). I
688 forsee this problem to most acute when working on the "perldl" com‐
689 mand line, but since this is exactly where the recording is most
690 useful the best advice is just to be careful and call clear on
691 state variables.
692 If you are working with scripts and use large images for instance I
694 would instead recommend that you do not turn on recording unless
695 you need it.
696
698 A more detailed listing of the functions and their usage follows. For
699 all functions we specify which options take effect and what other
700 options exist for the given function. The function descriptions below
701 are all given for the non-OO usage for historical reasons, but since
702 the conversion to an OO method is trivial there is no major need for
703 concern. Whenever you see a function example of the form
704 Usage: a_simple_function($x, $y, $z [, $opt]);
706 and you wish to use the OO version, just let your mind read the above
708 line as:
709 Usage: $win->a_simple_function($x, $y, $z [, $opt]);
711 where $win is a PDL::Graphics::PGPLOT::Window object. That is all.
713 Window control functions.
715 pgwin
717 Exported constructor for PGPLOT object/device/plot window.
719 Usage: pgwin($opt);
721 Usage: pgwin($option->$value,...);
722 Usage: pgwin($device);
723 Parameters are passed on to new() and can either be specified by hash
725 reference or as a list.
726 See the documentation fo PDL::Graphics::PGPLOT::Window::new for
728 details.
729 Because pgwin is a convenience function, you can specify the device by
731 passing in a single non-ref parameter. For even further convenience,
732 you can even omit the '/' in the device specifier, so these two lines
733 deliver the same result:
734 $a = pgwin(gif);
736 $a = new PDL::Graphics::PGPLOT::Window({Dev=>'/gif'});
737 new
739 Constructor for PGPLOT object/device/plot window.
741 Usage: PDL::Graphics::PGPLOT::Window->new($opt);
743 Usage: PDL::Graphics::PGPLOT::Window->new($option=>$value,...);
744 Options to new() can either be specified via a reference to a hash
746 $win = PDL::Graphics::PGPLOT::Window->new({Dev=>'/xserve',ny=>2});
748 or directly, as an array
750 # NOTE: no more {} !
752 $win = PDL::Graphics::PGPLOT::Window->new(Dev=>'/xserve',ny=>2);
753 The following lists the recognised options:
755 AspectRatio
757 The aspect ratio of the image, in the sense vertical/horizontal.
758 See the discussion on size setting.
759 Device
761 The type of device to use. The syntax of this is the one used by
762 PGPLOT.
763 Hold
765 Hold the plot window so that subsequent plots can plot over exist‐
766 ing plots. This can be adjusted with the "hold()" and "release()"
767 methods.
768 NXPanel
770 The number of panels in the X-direction
771 NYPanel
773 The number of panels in the Y-direction
774 Size
776 Yet another way to identify the plot window size -- this takes a
777 scalar or an array ref containing one, two, or three numbers. One
778 number gives you a square window. Two gives you a rectangular win‐
779 dow "(X,Y)". Three lets you specify the unit compactly (e.g.
780 "[<X>,<Y>,1]" for inches, "[<X>,<Y>,2]" for mm) but is deprecated
781 in favor of using the "Unit" option. See the discussion on size
782 setting.
783 Unit
785 The unit to use for size setting. PGPLOT accepts inch, mm, or
786 pixel. The default unit is inches for historical reasons, but you
787 can choose millimeters or (God forbid) pixels as well. String or
788 numeric specifications are OK (0=normalized, 1=inches, 2=mm, 3=pix‐
789 els). Normalized units make no sense here and are not accepted.
790 Ideally someone will one day hook this into the CPAN units parser
791 so you can specify window size in rods or attoparsecs.
792 WindowName
794 The name to give to the window. No particular use is made of this
795 at present. It would be great if it was possible to change the
796 title of the window frame.
797 WindowWidth
799 The width of the window in inches (or the specified Unit). See the
800 discussion on size setting.
801 WindowXSize and WindowYSize
803 The width and height of the window in inches (or the specified
804 Unit). See the discussion on size setting.
805 An important point to note is that the default values of most options
807 can be specified by passing these to the constructor. All general
808 options (common to several functions) can be adjusted in such a way,
809 but function specific options can not be set in this way (this is a
810 design limitation which is unlikely to be changed).
811 Thus the following call will set up a window where the default axis
813 colour will be yellow and where plot lines normally have red colour and
814 dashed linestyle.
815 $win = PDL::Graphics::PGPLOT::Window->new(Device => '/xs',
817 AxisColour => 'Yellow', Colour => 'Red', LineStyle => 'Dashed');
818 Size setting: There are a gazillion ways to set window size, in keeping
820 with TIMTOWTDI. In general you can get away with passing any unique
821 combination of an "<X>" size, a "<Y>"size, and/or an aspect ratio. In
822 increasing order of precedence, the options are: ("Units", "AspectRa‐
823 tio", "WindowWidth", "Window<X,Y>Size", "Size").
824 So if you specify an AspectRatio *and* an X and a Y coordinate, the
826 AspectRatio is ignored. Likewise, if you specify Units and a three-
827 component Size, the Units option is ignored in favor of the numeric
828 unit in the Size.
829 If you don't specify enough information to set the size of the window,
831 you get the default pane size and shape for that device.
832 close
834 Close a plot window
836 Usage: $win->close()
838 Close the current window. This does not necessarily mean that the win‐
840 dow is removed from your screen, but it does ensure that the device is
841 closed.
842 A message will be printed to STDOUT giving the name of the file created
844 if the plot was made to a hardcopy device and $PDL::verbose is true.
845 held
847 Check if a window is on hold
849 $is_held = $win->held();
851 Function to check whether the window is held or not.
853 hold
855 Hold the present window.
857 Usage: $win->hold()
859 Holds the present window so that subsequent plot commands overplots.
861 panel
863 Switch to a different panel
865 $win->panel(<num>);
867 Move to a different panel on the plotting surface. Note that you will
869 need to erase it manually if that is what you require.
870 This routine currently does something you probably don't want, and
872 hence is deprecated for most use: if you say
873 $win->panel(1);
875 $win->imag($image);
876 then $image will actually be displayed in panel 2. That's because the
878 main plotting routines such as line and imag all advance the panel when
879 necessary. Instead, it's better to use the Panel option within plot‐
880 ting commands, if you want to set the panel explicitly.
881 release
883 Release a plot window.
885 $win->release()
887 Release a plot window so that subsequent plot commands move to the next
889 panel or erase the plot and create a new plot.
890 erase
892 Erase plot
894 $win->erase($opt);
896 Erase a plot area. This accepts the option "Panel" or alternatively a
898 number or array reference which makes it possible to specify the panel
899 to erase when working with several panels.
900 Plotting functions
902 env
904 Define a plot window, and put graphics on 'hold'
906 $win->env( $xmin, $xmax, $ymin, $ymax, [$justify, $axis] );
908 $win->env( $xmin, $xmax, $ymin, $ymax, [$options] );
909 $xmin, $xmax, $ymin, $ymax are the plot boundaries. $justify is a
911 boolean value (default is 0); if true the axes scales will be the same
912 (see "justify"). $axis describes how the axes should be drawn (see
913 "axis") and defaults to 0.
914 If the second form is used, $justify and $axis can be set in the
916 options hash, for example:
917 $win->env( 0, 100, 0, 50, {JUSTIFY => 1, AXIS => 'GRID',
919 CHARSIZE => 0.7} );
920 In addition the following options can also be set for "env":
922 PlotPosition
924 The position of the plot on the page relative to the view surface
925 in normalised coordinates as an anonymous array. The array should
926 contain the lower and upper X-limits and then the lower and upper
927 Y-limits. To place two plots above each other with no space between
928 them you could do
929 $win->env(0, 1, 0, 1, {PlotPosition => [0.1, 0.5, 0.1, 0.5]});
931 $win->env(5, 9, 0, 8, {PlotPosition => [0.1, 0.5, 0.5, 0.9]});
932 Axis, Justify, Border
934 See the description of general options for these options.
935 AxisColour
937 Set the colour of the coordinate axes.
938 XTitle, YTitle, Title, Font, CharSize
940 Axes titles and the font and size to print them.
941 label_axes
943 Label plot axes
945 $win->label_axes(<xtitle>, <ytitle>, <plot title>, $options);
947 Draw labels for each axis on a plot.
949 imag
951 Display an image (uses "pgimag()"/"pggray()" as appropriate)
953 $win->imag ( $image, [$min, $max, $transform], [$opt] )
955 NOTES
957 $transform for image/cont etc. is used in the same way as the "TR()"
959 array in the underlying PGPLOT FORTRAN routine but is, fortunately,
960 zero-offset. The transform() routine can be used to create this piddle.
961 If $image is two-dimensional, you get a grey or pseudocolor image using
963 the scalar values at each X,Y point. If $image is three-dimensional
964 and the third dimension has order 3, then it is treated as an RGB true-
965 color image via rgbi.
966 There are several options related to scaling. By default, the image is
968 scaled to fit the PGPLOT default viewport on the screen. Scaling,
969 aspect ratio preservation, and 1:1 pixel mapping are available. (1:1
970 pixel mapping is useful for avoiding display artifacts, but it's not
971 recommended for final output as it's not device-independent.)
972 Here's an additional complication: the "pixel" stuff refers not (neces‐
974 sarily) to normal image pixels, but rather to transformed image pixels.
975 That is to say, if you feed in a transform matrix via the "TRANSFORM"
976 option, the "PIX", "SCALE", etc. options all refer to the transformed
977 coordinates and not physical image pixels. That is a Good Thing
978 because it, e.g., lets you specify plate scales of your output plots
979 directly! See fits_imag for an example application. If you do not
980 feed in a transform matrix, then the identity matrix is applied so that
981 the scaling options refer to original data pixels.
982 To draw a colour bar (or wedge), either use the "DrawWedge" option, or
984 the "draw_wedge()" routine (once the image has been drawn).
985 Options recognised:
987 ITF
989 the image transfer function applied to the pixel values. It may be
990 one of 'LINEAR', 'LOG', 'SQRT' (lower case is acceptable). It
991 defaults to 'LINEAR'.
992 MIN
994 Sets the minimum value to be used for calculation of the color-table
995 stretch.
996 MAX
998 Sets the maximum value for the same.
999 RANGE
1001 A more compact way to specify MIN and MAX, as a list: you can say
1002 "Range=>[0,10]" to scale the color table for brightness values
1003 between 0 and 10 in the iamge data.
1004 CRANGE
1006 Image values between MIN and MAX are scaled to an interval in nor‐
1007 malized color domain space, on the interval [0,1], before lookup in
1008 the window's color table. CRANGE lets you use only a part of the
1009 color table by specifying your own range -- e.g. if you say
1010 "CRange=>[0.25,0.75]" then only the middle half of the pseudocolor
1011 space will be used. (See the writeup on ctab().)
1012 TRANSFORM
1014 The PGPLOT transform 'matrix' as a 6x1 vector for display
1015 DrawWedge
1017 set to 1 to draw a colour bar (default is 0)
1018 Wedge
1020 see the draw_wedge() routine
1021 The following standard options influence this command:
1023 AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN, XRANGE, YRANGE
1025 To see an image with maximum size in the current window, but square
1027 pixels, say:
1028 $win->imag( $a, { PIX=>1 } );
1029 An alternative approach is to try:
1030 $win->imag( $a, { JUSTIFY=>1 } );
1031 To see the same image, scaled 1:1 with device pixels, say:
1032 $win->imag( $a, { SCALE=>1 } );
1033 To see an image made on a device with 1:2 pixel aspect ratio, with
1034 X pixels the same as original image pixels, say
1035 $win->imag( $a, { PIX=>0.5, SCALE=>2 } );
1036 To display an image at 100 dpi on any device, say:
1037 $win->imag( $a, { PITCH=>100 } );
1038 To display an image with 100 micron pixels, say:
1039 $win->imag( $a, { PITCH=>10, UNIT=>'mm' } );
1040 imag1
1042 Display an image with correct aspect ratio
1044 $win->imag1 ( $image, [$min, $max, $transform], [$opt] )
1046 This is syntactic sugar for
1048 $win->imag( { PIX=>1, ALIGN=>'CC' } );
1050 rgbi
1052 Display an RGB color image
1054 The calling sequence is exactly like "imag", except that the input
1056 image must have three dimensions: "N x M x 3". The last dimension is
1057 the (R,G,B) color value. This routine requires pgplot 5.3devel or
1058 later. Calling rgbi explicitly is not necessary, as calling image with
1059 an appropriately dimensioned RGB triplet makes it fall through to rgbi.
1060 fits_imag
1062 Display a FITS image with correct axes
1064 $win->fits_imag( image, [$min, $max], [$opt] );
1066 NOTES
1068 Titles:
1070 Currently fits_imag also generates titles for you by default and
1071 appends the FITS header scientific units if they're present. So if
1072 you say
1073 $pdl->hdr->{CTYPE1} = "Flamziness";
1075 $pdl->hdr->{CUNIT1} = "milliBleems";
1076 $win->fits_imag($pdl);
1077 then you get an X title of "Flamziness (milliBleems)". But you can
1079 (of course) override that by specifying the XTitle and YTitle
1080 switches:
1081 $win->fits_imag($pdl,{Xtitle=>"Arbitrary"});
1083 will give you "Arbitrary" as an X axis title, regardless of what's
1085 in the header.
1086 Scaling and aspect ratio:
1088 If CUNIT1 and CUNIT2 (or, if they're missing, CTYPE1 and CTYPE2)
1089 agree, then the default pixel aspect ratio is 1 (in scientific
1090 units, NOT in original pixels). If they don't agree (as for a spec‐
1091 trum) then the default pixel aspect ratio is adjusted automatically
1092 to match the plot viewport and other options you've specified.
1093 You can override the image scaling using the SCALE, PIX, or PITCH
1095 options just as with the imag() method -- but those parameters refer
1096 to the scientific coordinate system rather than to the pixel coordi‐
1097 nate system (e.g. "PITCH=>100" means "100 scientific units per
1098 inch", and "SCALE=>1" means "1 scientific unit per device pixel".
1099 See the imag() writeup for more info on these options.
1100 The default value of the "ALIGN" option is 'CC' -- centering the
1102 image both vertically and horizontally.
1103 Axis direction:
1105 By default, fits_imag tries to guess which direction your axes are
1106 meant to go (left-to-right or right-to-left) using the CDELT key‐
1107 words: if "CDEL1" is negative, then rather than reflecting the image
1108 fits_imag will plot the X axis so that the highest values are on the
1109 left.
1110 This is the most convenient behavior for folks who use calibrated
1112 (RA,DEC) images, but it is technically incorrect. To force the
1113 direction, use the DirAxis option. Setting "DirAxis=>1" (abbrevi‐
1114 ated "di=>1") will force the scientific axes to increase to the
1115 right, reversing the image as necessary.
1116 Color wedge:
1118 By default fits_imag draws a color wedge on the right; you can
1119 explicitly set the "DrawWedge" option to 0 to avoid this. Use the
1120 "WTitle" option to set the wedge title.
1121 Alternate WCS coordinates:
1123 The default behaviour is to use the primary/default WCS information
1124 in the FITS header (i.e. the "CRVAL1","CRPIX1",... keywords). The
1125 Greisen et al. standard (<http://fits.cv.nrao.edu/docu‐
1126 ments/wcs/wcs.html>) allows alternative/additional mappings to be
1127 included in a header; these are denoted by the letters "A" to "Z".
1128 If you know that your image contains such a mapping then you can use
1129 the "WCS" option to select the appropriate letter. For example, if
1130 you had read in a Chandra image created by the CIAO software package
1131 then you can display the image in the "physical" coordinate system
1132 by saying:
1133 $win->fits_imag( $pdl, { wcs => 'p' } );
1135 The identity transform is used if you select a mapping for which
1137 there is no information in the header. Please note that this suport
1138 is experimental and is not guaranteed to work correctly; please see
1139 the documentation for the _FITS_tr routine for more information.
1140 fits_rgbi
1142 Display an RGB FITS image with correct axes
1144 $win->fits_rgbi( image, [$min,$max], [$opt] );
1146 Works exactly like fits_imag, but the image must be in (X,Y,RGB) form.
1148 Only the first two axes of the FITS header are examined.
1149 fits_cont
1151 Draw contours of an image, labelling the axes using the WCS information
1153 in the FITS header of the image.
1154 $win->fits_cont( image, [$contours, $transform, $misval], [$opt] )
1156 Does the same thing for the cont routine that fits_imag does for the
1158 imag routins.
1159 draw_wedge
1161 Add a wedge (colour bar) to an image.
1163 $win->draw_wedge( [$opt] )
1165 Adds a wedge - shows the mapping between colour and value for a pixel -
1167 to the current image. This can also be achieved by setting "DrawWedge"
1168 to 1 when calling the "imag" routine.
1169 The colour and font size are the same as used to draw the image axes
1171 (although this will probably fail if you did it yourself). To control
1172 the size and location of the wedge, use the "Wedge" option, giving it a
1173 hash reference containing any of the following:
1174 Side
1176 Which side of the image to draw the wedge: can be one of 'B', 'L',
1177 'T', or 'R'. Default is 'R'.
1178 Displacement
1180 How far from the egde of the image should the wedge be drawn, in
1181 units of character size. To draw within the image use a negative
1182 value. Default is 1.5.
1183 Width
1185 How wide should the wedge be, in units of character size. Default
1186 is 2.
1187 Label
1189 A text label to be added to the wedge. If set, it is probably
1190 worth increasing the "Width" value by about 1 to keep the text
1191 readable. Default is ''. This is equivalent to the "WTitle"
1192 option to imag, fits_imag, and similar methods.
1193 ForeGround (synonym Fg)
1195 The pixel value corresponding to the "maximum" colour. If "undef",
1196 uses the value used by "imag" (recommended choice). Default is
1197 "undef".
1198 BackGround (synonym Bg)
1200 The pixel value corresponding to the "minimum" colour. If "undef",
1201 uses the value used by "imag" (recommended choice). Default is
1202 "undef".
1203 $a = rvals(50,50);
1205 $win = PDL::Graphics::PGPLOT::Window->new();
1206 $win->imag( $a, { Justify => 1, ITF => 'sqrt' } );
1207 $win->draw_wedge( { Wedge => { Width => 4, Label => 'foo' } } );
1208 # although the following might be more sensible
1209 $win->imag( $a, { Justify => 1, ITF => 'sqrt', DrawWedge => 1,
1210 Wedge => { Width => 4, Label => 'foo'} } );
1211 ctab
1213 Load an image colour table.
1215 Usage:
1217 ctab ( $name, [$contrast, $brightness] ) # Builtin col table
1219 ctab ( $ctab, [$contrast, $brightness] ) # $ctab is Nx4 array
1220 ctab ( $levels, $red, $green, $blue, [$contrast, $brightness] )
1221 ctab ( '', $contrast, $brightness ) # use last color table
1222 Note: See PDL::Graphics::LUT for access to a large number of colour
1224 tables.
1225 Notionally, all non-RGB images and vectors have their colors looked up
1227 in the window's color table. Colors in images and such are scaled to a
1228 normalized pseudocolor domain on the line segment [0,1]; the color ta‐
1229 ble is a piecewise linear function that maps this one-dimensional scale
1230 to the three-dimensional normalized RGB color space [0,1]^3.
1231 You can specify specific indexed colors by appropriate use of the (lev‐
1233 els,red,green,blue) syntax -- but that is deprecated, since the actual
1234 available number of colors can change depending on the output device.
1235 (Someone needs to write a specific hardware-dependent lookup table
1236 interface).
1237 See also imag for a description of how to use only part of the color
1239 table for a particular image.
1240 ctab_info
1242 Return information about the currently loaded color table
1244 autolog
1246 Turn on automatic logarithmic scaling in "line" and "points"
1248 Usage: autolog([0⎪1]);
1250 Setting the argument to 1 turns on automatic log scaling and setting it
1252 to zero turns it off again. The function can be used in both the object
1253 oriented and standard interface. To learn more, see the documentation
1254 for PDL::Graphics::PGPLOT::Window.
1255 my $win = PDL::Graphics::PGPLOT::Window->new(dev=>'/xserve');
1257 my $x=sequence(10);
1258 my $y=$x*$x+1;
1259 $win->autolog(1);
1261 $win->line($x,$y, {Axis => 'LogY'});
1262 line
1264 Plot vector as connected points
1266 If the 'MISSING' option is specified, those points in the $y vector
1268 which are equal to the MISSING value are not plotted, but are skipped
1269 over. This allows one to quickly draw multiple lines with one call to
1270 "line", for example to draw coastlines for maps.
1271 Usage: line ( [$x,] $y, [$opt] )
1273 The following standard options influence this command:
1275 AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING,
1277 JUSTIFY, SCALE, PITCH, PIX, ALIGN
1278 $x = sequence(10)/10.;
1280 $y = sin($x)**2;
1281 # Draw a red dot-dashed line
1282 line $x, $y, {COLOR => 'RED', LINESTYLE=>3};
1283 lines
1285 Plot a list of vectors as discrete sets of connected points
1287 This works much like line, but for discrete sets of connected points.
1289 There are two ways to break lines: you can pass in x/y coordinates just
1290 like in line, but with an additional "pen" piddle that indicates
1291 whether the pen is up or down on the line segment following each point
1292 (so you set it to zero at the end of each line segment you want to
1293 draw); or you can pass in an array ref containing a list of single
1294 polylines to draw.
1295 Happily, there's extra meaning packed into the "pen" piddle: it multi‐
1297 plies the COLO(U)R that you set, so if you feed in boolean values you
1298 get what you expect -- but you can also feed in integer or floating-
1299 point values to get multicolored lines.
1300 Furthermore, the sign bit of "pen" can be used to draw hairline seg‐
1302 ments: if "pen" is negative, then the segment is drawn as though it
1303 were positive but with LineWidth and HardLW set to 1 (the minimum).
1304 Equally happily, even if you are using the array ref mechanism to break
1306 your polylines you can feed in an array ref of "pen" values to take
1307 advantage of the color functionality or further dice your polylines.
1308 Note that, unlike line, "lines" has no no specify-$y-only calling path.
1310 That's because "lines" is intended more for line art than for plotting,
1311 so you always have to specify both $x and $y.
1312 Infinite or bad values are ignored -- that is to say, if your vector
1314 contains a non-finite point, that point breaks the vector just as if
1315 you set pen=0 for both that point and the point before it.
1316 Usage: $w->( $x, $y, [$pen], [$opt] );
1318 $w->( $xy, [$pen], [$opt] );
1319 $w->( \@xvects, \@yvects, [\@pen], [$opt] );
1320 $w->( \@xyvects, [\@pen], [$opt] );
1321 The following standard options influence this command:
1323 AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING,
1324 JUSTIFY, SCALE, PITCH, PIX, ALIGN
1325 CAVEAT:
1327 Setting "pen" elements to 0 prevents drawing altogether, so you can't
1329 use that to draw in the background color.
1330 points
1332 Plot vector as points
1334 Usage: points ( [$x,] $y, [$symbol(s)], [$opt] )
1336 Options recognised:
1338 SYMBOL - Either a piddle with the same dimensions as $x, containing
1340 the symbol associated to each point or a number specifying
1341 the symbol to use for every point, or a name specifying the
1342 symbol to use according to the following (recognised name in
1343 capital letters):
1344 0 - SQUARE 1 - DOT 2 - PLUS 3 - ASTERISK
1345 4 - CIRCLE 5 - CROSS 7 - TRIANGLE 8 - EARTH
1346 9 - SUN 11 - DIAMOND 12- STAR
1347 PLOTLINE - If this is >0 a line will be drawn through the points.
1348 The following standard options influence this command:
1350 AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH,
1352 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1353 "SymbolSize" allows to adjust the symbol size, it defaults to CharSize.
1355 The "ColorValues" option allows one to plot XYZ data with the Z axis
1357 mapped to a color value. For example:
1358 use PDL::Graphics::LUT;
1360 ctab(lut_data('idl5')); # set up color palette to 'idl5'
1361 points ($x, $y, {ColorValues => $z});
1362 $y = sequence(10)**2+random(10);
1364 # Plot blue stars with a solid line through:
1365 points $y, {PLOTLINE => 1, COLOUR => BLUE, symbol => STAR}; # case insensitive
1366 errb
1368 Plot error bars (using "pgerrb()")
1370 Usage:
1372 errb ( $y, $yerrors, [$opt] )
1374 errb ( $x, $y, $yerrors, [$opt] )
1375 errb ( $x, $y, $xerrors, $yerrors, [$opt] )
1376 errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt])
1377 Any of the error bar parameters may be "undef" to omit those error
1379 bars.
1380 Options recognised:
1382 TERM - Length of terminals in multiples of the default length
1384 SYMBOL - Plot the datapoints using the symbol value given, either
1385 as name or number - see documentation for 'points'
1386 The following standard options influence this command:
1388 AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH,
1390 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1391 $y = sequence(10)**2+random(10);
1393 $sigma=0.5*sqrt($y);
1394 errb $y, $sigma, {COLOUR => RED, SYMBOL => 18};
1395 # plot X bars only
1397 errb( $x, $y, $xerrors, undef );
1398 # plot negative going bars only
1400 errb( $x, $y, $xloerr, undef, $yloerr, undef );
1401 cont
1403 Display image as contour map
1405 Usage: cont ( $image, [$contours, $transform, $misval], [$opt] )
1407 Notes: $transform for image/cont etc. is used in the same way as the
1409 "TR()" array in the underlying PGPLOT FORTRAN routine but is, fortu‐
1410 nately, zero-offset. The transform() routine can be used to create this
1411 piddle.
1412 Options recognised:
1414 CONTOURS - A piddle with the contour levels
1416 FOLLOW - Follow the contour lines around (uses pgcont rather than
1417 pgcons) If this is set >0 the chosen linestyle will be
1418 ignored and solid line used for the positive contours
1419 and dashed line for the negative contours.
1420 LABELS - An array of strings with labels for each contour
1421 LABELCOLOUR - The colour of labels if different from the draw colour
1422 This will not interfere with the setting of draw colour
1423 using the colour keyword.
1424 MISSING - The value to ignore for contouring
1425 NCONTOURS - The number of contours wanted for automatical creation,
1426 overridden by CONTOURS
1427 TRANSFORM - The pixel-to-world coordinate transform vector
1428 The following standard options influence this command:
1430 AXIS, BORDER, COLOUR, LINESTYLE, LINEWIDTH,
1432 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1433 $x=sequence(10,10);
1435 $ncont = 4;
1436 $labels= ['COLD', 'COLDER', 'FREEZING', 'NORWAY']
1437 # This will give four blue contour lines labelled in red.
1438 cont $x, {NCONT => $ncont, LABELS => $labels, LABELCOLOR => RED,
1439 COLOR => BLUE}
1440 bin
1442 Plot vector as histogram (e.g. "bin(hist($data))")
1444 Usage: bin ( [$x,] $data )
1446 Options recognised:
1448 CENTRE - if true, the x values denote the centre of the bin
1450 otherwise they give the lower-edge (in x) of the bin
1451 CENTER - as CENTRE
1452 The following standard options influence this command:
1454 AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH
1456 hi2d
1458 Plot image as 2d histogram (not very good IMHO...)
1460 Usage: hi2d ( $image, [$x, $ioff, $bias], [$opt] )
1462 Options recognised:
1464 IOFFSET - The offset for each array slice. >0 slants to the right
1466 <0 to the left.
1467 BIAS - The bias to shift each array slice up by.
1468 The following standard options influence this command:
1470 AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN
1472 Note that meddling with the "ioffset" and "bias" often will require you
1474 to change the default plot range somewhat. It is also worth noting that
1475 if you have TriD working you will probably be better off using mesh3d
1476 or a similar command - see the PDL::Graphics::TriD module.
1477 $r=sequence(100)/50-1.0;
1479 $y=exp(-$r**2)*transpose(exp(-$r**2))
1480 hi2d $y, {IOFF => 1.5, BIAS => 0.07};
1481 arrow
1483 Plot an arrow
1485 Usage: arrow($x1, $y1, $x2, $y2, [, $opt]);
1487 Plot an arrow from "$x1, $y1" to "$x2, $y2". The arrow shape can be set
1489 using the option "Arrow". See the documentation for general options for
1490 details about this option (and the example below):
1491 Example:
1493 arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 1, Vent => 0.3, Size => 5}});
1495 which draws a broad, large arrow from (0, 1) to (1, 2).
1497 rect
1499 Draw a non-rotated rectangle
1501 Usage: rect ( $x1, $x2, $y1, $y2 )
1503 Options recognised:
1505 The following standard options influence this command:
1507 AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH
1509 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1510 poly
1512 Draw a polygon
1514 Usage: poly ( $x, $y )
1516 Options recognised:
1518 The following standard options influence this command:
1520 AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH
1522 JUSTIFY, SCALE, PIX, PITCH, ALIGN
1523 # Fill with hatching in two different colours
1525 $x=sequence(10)/10;
1526 # First fill with cyan hatching
1527 poly $x, $x**2, {COLOR=>5, FILL=>3};
1528 hold;
1529 # Then do it over again with the hatching offset in phase:
1530 poly $x, $x**2, {COLOR=>6, FILL=>3, HATCH=>{PHASE=>0.5}};
1531 release;
1532 circle
1534 Plot a circle on the display using the fill setting.
1536 Usage: circle($x, $y, $radius [, $opt]);
1538 All arguments can alternatively be given in the options hash using the
1540 following options:
1541 XCenter and YCenter
1543 The position of the center of the circle
1544 Radius
1546 The radius of the circle.
1547 ellipse
1549 Plot an ellipse, optionally using fill style.
1551 Usage: ellipse($x, $y, $a, $b, $theta [, $opt]);
1553 All arguments can alternatively be given in the options hash using the
1555 following options:
1556 MajorAxis
1558 The major axis of the ellipse - this must be defined or $a must be
1559 given.
1560 MinorAxis
1562 The minor axis, like A this is required.
1563 Theta (synonym Angle)
1565 The orientation of the ellipse - defaults to 0.0. This is given in
1566 radians.
1567 XCenter and YCenter
1569 The coordinates of the center of the ellipse. These must be speci‐
1570 fied or $x and $y must be given.
1571 NPoints
1573 The number of points used to draw the ellipse. This defaults to 100
1574 and might need changing in the case of very large ellipses.
1575 The routine also recognises the same standard options as accepted by
1577 poly.
1578 rectangle
1580 Draw a rectangle.
1582 Usage: rectangle($xcenter, $ycenter, $xside, $yside, [, $angle, $opt]);
1584 This routine draws a rectangle with the chosen fill style. Internally
1586 it calls poly which is somewhat slower than "pgrect" but which allows
1587 for rotated rectangles as well. The routine recognises the same options
1588 as "poly" and in addition the following:
1589 XCenter and YCenter
1591 The position of the center of the rectangle. XCentre and YCentre
1592 are valid synonyms.
1593 XSide and YSide
1595 The length of the X and Y sides. If only one is specified the shape
1596 is taken to be square with that as the side-length, alternatively
1597 the user can set Side
1598 Side
1600 The length of the sides of the rectangle (in this case a square) -
1601 syntactic sugar for setting XSide and YSide identical. This is
1602 overridden by XSide or YSide if any of those are set.
1603 Angle (synonym Theta)
1605 The angle at which the rectangle is to be drawn. This defaults to
1606 0.0 and is given in radians.
1607 vect
1609 Display 2 images as a vector field
1611 Usage: vect ( $w, $a, $b, [$scale, $pos, $transform, $misval], { opt } );
1613 $w->vect($a,$b,[$scale,$pos,$transform,$misval], { opt });
1614 Notes: $transform for image/cont etc. is used in the same way as the
1616 "TR()" array in the underlying PGPLOT FORTRAN routine but is, fortu‐
1617 nately, zero-offset. The transform() routine can be used to create this
1618 piddle.
1619 This routine will plot a vector field. $a is the horizontal component
1621 and $b the vertical component. The scale factor converts between vec‐
1622 tor length units and scientific positional units. You can set the
1623 scale, position, etc. either by passing in parameters in the normal
1624 parameter list or by passing in options.
1625 Options recognised:
1627 SCALE - Set the scale factor for vector lengths.
1629 POS - Set the position of vectors.
1630 <0 - vector head at coordinate
1631 >0 - vector base at coordinate
1632 =0 - vector centered on the coordinate
1633 TRANSFORM - The pixel-to-world coordinate transform vector
1634 MISSING - Elements with this value are ignored.
1635 The following standard options influence this command:
1637 ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR,
1639 LINESTYLE, LINEWIDTH,
1640 $a=rvals(11,11,{Centre=>[5,5]});
1642 $b=rvals(11,11,{Centre=>[0,0]});
1643 vect $a, $b, {COLOR=>YELLOW, ARROWSIZE=>0.5, LINESTYLE=>dashed};
1644 fits_vect
1646 Display a pair of 2-D piddles as vectors, with FITS header interpreta‐
1648 tion
1649 Usage: fits_vect ($a, $b, [$scale, $pos, $transform, $misval] )
1651 "fits_vect" is to vect as fits_imag is to imag.
1653 transform
1655 Create transform array for contour and image plotting
1657 $win->transform([$xdim,$ydim], $options);
1659 (For information on coordinate transforms, try PDL::Transform.) This
1661 function creates a transform array in the format required by the image
1662 and contouring routines. You must call it with the dimensions of your
1663 image as arguments or pass these as an anonymous hash - see the example
1664 below.
1665 Angle
1667 The rotation angle of the transform, in radians. Positive numbers
1668 rotate the image clockwise on the screen.
1669 ImageDimensions
1671 The dimensions of the image the transform is required for. The
1672 dimensions should be passed as a reference to an array.
1673 Pixinc
1675 The increment in output coordinate per pixel.
1676 ImageCenter (or ImageCentre)
1678 The centre of the image as an anonymous array or as a scalar, in
1679 scientific coordinates. In the latter case the x and y value for
1680 the center will be set equal to this scalar. This is particularly
1681 useful in the common case when the center is (0, 0). (ImageCenter
1682 overrides RefPos if both are specified).
1683 RefPos (or ReferencePosition)
1685 If you wish to set a pixel other than the image centre to a given
1686 value, use this option. It should be supplied with a reference to
1687 an array containing 2 2-element array references, e.g.
1688 RefPos => [ [ $xpix, $ypix ], [ $xplot, $yplot ] ]
1690 This will label pixel "($xpix,$ypix)" as being at position
1692 "($xplot,$yplot)". For example
1693 RefPos => [ [100,74], [ 0, 0 ] ]
1695 sets the scientific coordinate origin to be at the center of the
1697 (100,74) pixel coordinate. The pixel coordinates are pixel-cen‐
1698 tered, and start counting from 0 (as all good pixel coordinates
1699 should).
1700 Example:
1702 $im = rvals(100, 100);
1704 $w = PDL::Graphics::PGPLOT::Window->new(Device => '/xs');
1705 $t = $w->transform(dims($im), {ImageCenter => 0, Pixinc => 5});
1706 $w->imag($im, {Transform => $t});
1707 tline
1709 Threaded line plotting
1711 $win->tline($x, $y, $options);
1713 This is a threaded interface to "line". This is convenient if you have
1715 a 2D array and want to plot out every line in one go. The routine will
1716 apply any options you apply in a "reasonable" way. In the sense that it
1717 will loop over the options wrapping over if there are less options than
1718 lines.
1719 Example:
1721 $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']};
1723 $tx=zeroes(100,5)->xlinvals(-5,5);
1724 $ty = $tx + $tx->yvals;
1725 $win->tline($tx, $ty, $h);
1726 tpoints
1728 A threaded interface to points
1730 Usage: tpoints($x, $y, $options);
1732 This is a threaded interface to "points". This is convenient if you
1734 have a 2D array and want to plot out every line in one go. The routine
1735 will apply any options you apply in a "reasonable" way. In the sense
1736 that it will loop over the options wrapping over if there are less
1737 options than lines.
1738 Example:
1740 $h={Colour => ['Red', '1', 4], Linestyle => ['Solid' ,'Dashed']};
1742 $tx=zeroes(100,5)->xlinvals(-5,5);
1743 $ty = $tx + $tx->yvals;
1744 tpoints($tx, $ty, $h);
1745 tcircle
1747 A threaded interface to circle
1749 Usage: tcircle($x, $y, $r, $options);
1751 This is a threaded interface to "circle". This is convenient if you
1753 have a list of circle centers and radii and want to draw every circle
1754 in one go. The routine will apply any options you apply in a "reason‐
1755 able" way, in the sense that it will loop over the options wrapping
1756 over if there are less options than circles.
1757 Example:
1759 $x=sequence(5);
1761 $y=random(5);
1762 $r=sequence(5)/10 + 0.1;
1763 $h={justify => 1,Color => ['red','green','blue'], filltype => ['solid','outline','hatched','cross_hatched']};
1764 tcircle($x, $y, $r, $h);
1765 Note that $x and $y must be the same size (>1D is OK, though meaning‐
1767 less as far as "tcircle" is concerned). $r can be the same size as $x
1768 OR a 1-element piddle OR a single perl scalar.
1769 Text routines
1771 text
1773 Write text in a plot window at a specified position.
1775 Usage: text ($text, $x, $y [, $opt])
1777 Options recognised:
1779 "ANGLE"
1781 The angle in degrees between the baseline of the text and the
1782 horisontal (increasing counter-clockwise). This defaults to 0.
1783 "JUSTIFICATION"
1785 The justification of the text relative to the position specified.
1786 It defaults to 0.0 which gives left-justified text. A value of 0.5
1787 gives centered text and a value of 1.0 gives right-justified text.
1788 "XPos", "YPos", "Text"
1790 These gives alternative ways to specify the text and position.
1791 "BackgroundColour"
1793 This sets the background colour for the text in case an opaque
1794 background is desired. You can also use the synonyms "Bg" and
1795 "BackgroundColor".
1796 The following standard options influence this command:
1798 COLOUR, CHARSIZE
1800 line sequence(10), sequence(10)**2;
1802 text 'A parabola', 3, 9, {Justification => 1, Angle=>atan2(6,1)};
1803 legend
1805 Add a legend to a plot
1807 Usage: legend($text, $x, $y, [, $width], $opt]);
1809 This function adds a legend to an existing plot. The action is primar‐
1811 ily controlled by information in the options hash, and the basic idea
1812 is that $x and $y determines the upper left hand corner of the box in
1813 which the legend goes. If the width is specified either as an argument
1814 or as an option in the option hash this is used to determine the opti‐
1815 mal character size to fit the text into part of this width (defaults to
1816 0.5 - see the description of "TextFraction" below). The rest of the
1817 width is filled out with either lines or symbols according to the con‐
1818 tent of the "LineStyle", "Symbol", "Colour" and "LineWidth" options.
1819 The local options recognised are as follows:
1821 "Text"
1823 An anonymous array of annotations, can also be specified directly.
1824 "XPos" and "YPos"
1826 The X and Y position of the upper left-hand corner of the text.
1827 "Width" and "Height"
1829 The width and/or height of each line (including symbol/line). This
1830 is used to determine the character size. If any of these are set to
1831 'Automatic' the current character size will be used.
1832 "TextFraction"
1834 The text and the symbol/line is set inside a box. "TextFraction"
1835 determines how much of this box should be devoted to text. This
1836 defaults to 0.5. You can also use "Fraction" as a synonym to this.
1837 "TextShift"
1839 This option allows for fine control of the spacing between the text
1840 and the start of the line/symbol. It is given in fractions of the
1841 total width of the legend box. The default value is 0.1.
1842 "VertSpace" or "VSpace"
1844 By default the text lines are separated by one character height (in
1845 the sense that if the separation were 0 then they would lie on top
1846 of each other). The "VertSpace" option allows you to increase (or
1847 decrease) this gap in units of the character height; a value of 0.5
1848 would add half a character height to the gap between lines, and
1849 -0.5 would remove the same distance. The default value is 0.
1850 "BackgroundColour"
1852 This sets the background colour for the text in case an opaque
1853 background is desired. You can also use the synonyms "Bg" and
1854 "BackgroundColor".
1855 line $x, $y, {Color => 'Red', LineStyle => 'Solid'};
1857 line $x2, $y2, {Color => 'Blue', 'LineStyle' => 'Dashed', LineWidth => 10};
1858 legend ['A red line', 'A blue line'], 5, 5,
1860 {LineStyle => ['Solid', 'Dashed'], Colour => ['Red', 'Blue']
1861 LineWidth => [undef, 10]}; # undef gives default.
1862 Cursor routines
1864 cursor
1866 Interactively read cursor positions.
1868 Usage: ($x, $y, $ch, $xref, $yref) = cursor($opt)
1870 This routine has no standard input parameters, but the type of cursor
1872 can be set by setting the option "Type" as a key in the anonymous hash
1873 $opt. The first three return values from the function are always
1874 defined and gives the position selected by the user and the character
1875 pressed.
1876 Depending on the cursor type selected the last two arguments might also
1878 be defined and these give a reference position. For instance if the
1879 cursor is selected to be "Rectangle" then the reference position gives
1880 one of the corners of the rectangle and $x and $y the diagonally oppo‐
1881 site one.
1882 Options recognised:
1884 XRef, YRef
1886 The reference position to be used
1887 Type
1889 The type of cursor. This can be selected using a number between 0
1890 and 7 as in PGPLOT, or alternatively you can specify these as,
1891 "Default" (0), "RadialLine" (1), "Rectangle" (2), "TwoHorizon‐
1892 talLines" (3), "TwoVerticalLines" (4), "HorizontalLine" (5), "Ver‐
1893 ticalLine" (6) and "CrossHair" (7) respectively. The default cursor
1894 is just the normal mouse cursor.
1895 For the "RadialLine" you must specify the reference point, whereas
1897 for the "Two(Vertical⎪Horizontal)Lines" cursor the X or Y reference
1898 point, respectively, must be specified.
1899 To select a region on a plot, use the rectangle cursor:
1901 ($x, $y, $ch, $xref, $yref) = cursor({Type => 'Rectangle'});
1903 poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y);
1904 To select a region of the X-axis:
1906 ($x1, $y1, $ch) = cursor({Type => 'VerticalLine'});
1908 ($x2, $y2, $ch) = cursor({Type => 'TwoVerticalLines', XRef => $x1});
1909 Internal routines
1911 signal_catcher, catch_signals, release_signals
1913 To prevent pgplot from doing a fandango on core, we have to block
1915 interrupts during PGPLOT calls. Specifically, INT needs to get caught.
1916 These internal routines provide a mechanism for that.
1917 You simply bracket any PGPLOT calls with &catch_signals above and
1919 &release_signals below, and the signal_catcher will queue up any sig‐
1920 nals (like INT -- the control-C interrupt) until the &release_signals
1921 call.
1922 Any exit path from your hot code must include &release_signals, or
1924 interrupts could be deferred indefinitely (which would be a bug). This
1925 includes calls to &barf -- even barfs from someone you called! So
1926 avoid calling out of the local module if possible, and use
1927 release_and_barf() instead of barf() from within this module.
1928 Perl 5.6.1 interrupt handling has a bug that this code tickles -- some‐
1930 times the re-emitted signals vanish into hyperspace. Perl 5.8 seems
1931 NOT to have that problem.
1932 _open_new_window
1934 Open a new window. This sets the window ID, which is the one used when
1936 accessing a window later using "pgslct". It also sets the window name
1937 to something easily remembered if it has not been set before.
1938 _setup_window
1940 This routine sets up a new window with its shape and size. This is also
1942 where the size options are actually parsed. These are then forgotten
1943 (well, they are stored in $self->{Options}) and the corresponding
1944 aspect ratio and window width is stored. See the discussion under
1945 new() for the logic.
1946 Finally the subpanels are set up using "pgsubp" and colours and
1948 linewidth are adjusted according to whether we have a hardcopy device
1949 or not.
1950 _status
1952 This routine checks PGPLOT's status for the window. It returns OPEN if
1954 the window is open and CLOSED if it is closed. (Windows can be closed
1955 but still exist).
1956 _reopen
1958 This functions reopens a window. Since this is an internal function it
1960 does not have a lot of error-checking. Make sure the device is closed
1961 before calling this routine.
1962 There is an unfortunate problem which pops up viz. that the window name
1964 cannot be changed at this point since we are offering that to the rest
1965 of the world. That might be sensible, but it means that the window name
1966 will not reflect the id of the window - use "id()" for that (this is
1967 also why we do not call "open_new_window" )
1968 _advance_panel
1970 This routine advances one plot panel, updating the CurrentPanel as
1972 well. If the advance will proceed past the page the page will be
1973 erased. Also note that when you advance one panel the hold value will
1974 be changed.
1975 _check_move_or_erase
1977 This routine is a utility routine which checks if we need to move
1979 panel, and if so will do this. It also checks if it is necessary to
1980 advance panels, and whether they need to be erased.
1981 _thread_options
1983 This function is a cludgy utility function that expands an options hash
1985 to an array of hashes looping over options. This is mainly of use for
1986 "threaded" interfaces to standard plotting routines.
1987 options
1989 Access the options used when originally opening the window. At the
1991 moment this is not updated when the window is changed later.
1992 id
1994 Access the window ID that PGPLOT uses for the present window.
1996 device
1998 This function returns the device type of the present window.
2000 name
2002 Accessor to set and examine the name of a window.
2004 focus
2006 Set focus for subsequent PGPLOT commands to this window.
2008 info
2010 Get general information about the PGPLOT environment.
2012 @ans = $self->info( @item );
2014 The valid values of @item are as below, where case is not important:
2016 VERSION - What PGPLOT version is in use.
2018 STATE - The status of the output device, this is returns 'OPEN'.
2019 if the device is open and 'CLOSED' otherwise.
2020 USER - The username of the owner of the spawning program.
2021 NOW - The current date and time in the format
2022 'dd-MMM-yyyy hh:mm'. Most people are likely to use Perl
2023 functions instead.
2024 DEVICE * - The current PGPLOT device or file, see also device().
2025 FILE * - The filename for the current device.
2026 TYPE * - And the device type for the current device.
2027 DEV/TYPE * - This combines DEVICE and TYPE in a form that can be used
2028 as input to new.
2029 HARDCOPY * - This is flag which is set to 'YES' if the current device is
2030 a hardcopy device and 'NO' otherwise.
2031 TERMINAL * - This flag is set to 'YES' if the current device is the
2032 user's terminal and 'NO' otherwise.
2033 CURSOR * - A flag ('YES' or 'NO') to inform whether the current device
2034 has a cursor.
2035 Those items marced with a "*" only return a valid answer if the window
2037 is open. A question mark ("?") is returned if the item is not recog‐
2038 nised or the information is not available.
2039 _extract_hash
2041 This routine takes and array and returns the first hash reference found
2043 as well as those elements that are not hashes. Note the latter point
2044 because all other references to hashes in the array will be lost.
2045 _parse_unit
2047 Convert a unit string or number into a PGPLOT-certified length unit
2049 specification, or return undef if it won't go.
2050 _parse_options
2052 This is a convenience routine for parsing a set of options. It returns
2054 both the full set of options and those that the user has set.
2055 _save_status
2057 Saves the PGPLOT state so that changes to settings can be made and then
2059 the present state restored by "_restore_status".
2060 _restore_status
2062 Restore the PGPLOT state. See "_save_status".
2064 _checkarg
2066 This routine checks and optionally alters the arguments given to it.
2068 _set_colour
2070 This is an internal routine that encapsulates all the nastiness of set‐
2072 ting colours depending on the different PGPLOT colour models (although
2073 HLS is not supported).
2074 The routine works in the following way:
2076 · At initialisation of the plot device the work colour index is
2078 set to 16. The work index is the index the routine will modify
2079 unless the user has specified something else.
2080 · The routine should be used after standard interpretation and
2082 synonym matching has been used. So if the colour is given as
2083 input is an integer that colour index is used.
2084 · If the colour is a reference the routine checks whether it is
2086 an "ARRAY" or a "PDL" reference. If it is not an error message
2087 is given. If it is a "PDL" reference it will be converted to
2088 an array ref.
2089 · If the array has four elements the first element is interpreted
2091 as the colour index to modify and this overrules the setting
2092 for the work index used internally. Otherwise the work index is
2093 used and incremented until the maximum number of colours for
2094 the output device is reached (as indicated by "pgqcol"). Should
2095 you wish to change that you need to read the PGPLOT documenta‐
2096 tion - it is somewhat device dependent.
2097 · When the array has been recognised the R,G and B colours of the
2099 user-set index or work index is set using the "pgscr" command
2100 and we are finished.
2101 · If the input colour instead is a string we try to set the
2103 colour using the PGPLOT routine "pgscrn" with no other
2104 error-checking. This should be ok, as that routine returns a
2105 rather sensible error-message.
2106 _standard_options_parser
2108 This internal routine is the default routine for parsing options. This
2110 routine deals with a subset of options that most routines will accept.
2111 _image_xyrange
2113 Given a PGPLOT tr matrix and an image size, calculate the data world
2115 coordinates over which the image ranges. This is used in imag and
2116 cont. It keeps track of the required half-pixel offset to display
2117 images properly -- eg feeding in no tr matrix at all, nx=20, and ny=20
2118 will will return (-0.5,19.5,-0.5,19.5). It also checks the options
2119 hash for XRange/YRange specifications and, if they are present, it
2120 overrides the appropriate output with the exact ranges in those fields.
2121 _FITS_tr
2123 Given a FITS image, return the PGPLOT transformation matrix to convert
2125 pixel coordinates to scientific coordinates. Used by fits_imag,
2126 fits_rgbi, and fits_cont, but may come in handy for other methods.
2127 my $tr = _FITS_tr( $win, $img );
2129 my $tr = _FITS_tr( $win, $img, $opts );
2130 The return value ($tr in the examples above) is the same as returned by
2132 the transform() routine, with values set up to convert the pixel to
2133 scientific coordinate values for the two-dimensional image $img. The
2134 $opts argument is optional and should be a HASH reference; currently it
2135 only understands one key (any others are ignored):
2136 WCS => undef (default), "", or "A" to "Z"
2138 Both the key name and value are case insensitive. If left as "undef" or
2140 "" then the primary coordinate mapping from the header is used, other‐
2141 wise use the additional WCS mapping given by the appropriate letter.
2142 We make no checks that the given mapping is available; the routine
2143 falls back to the unit mapping if the specified system is not avail‐
2144 able.
2145 The WCS option has only been tested on images from the Chandra X-ray
2147 satellite (<http://chandra.harvard.edu/>) created by the CIAO software
2148 package (<http://cxc.harvard.edu/ciao/>), for which you should set "WCS
2149 => "P"" to use the "PHYSICAL" coordinate system.
2150 See <http://fits.cv.nrao.edu/documents/wcs/wcs.html> for further infor‐
2152 mation on the Representation of World Coordinate Systems in FITS.
2153
2155 The coding tries to follow reasonable standards, so that all functions
2156 starting with an underscore should be considered as internal and should
2157 not be called from outside the package. In addition most routines have
2158 a set of options. These are encapsulated and are not accessible outside
2159 the routine. This is to avoid collisions between different variables.
2160
2162 Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann
2163 (jarle@astro.ox.ac.uk) who is also responsible for the OO interface,
2164 docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian
2165 Soeller (c.soeller@auckland.ac.nz). Further contributions and bugfixes
2166 from Kaj Wiik, Doug Burke, Craig DeForest, and many others.
2167 All rights reserved. There is no warranty. You are allowed to redis‐
2169 tribute this software / documentation under certain conditions. For
2170 details, see the file COPYING in the PDL distribution. If this file is
2171 separated from the PDL distribution, the copyright notice should be
2172 included in the file.
2173perl v5.8.8 2006-01-13 Window(3)