.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Window 3pm" .TH Window 3pm "2023-06-17" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" PDL::Graphics::PGPLOT::Window \- A OO interface to PGPLOT windows .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 8 \& pdl> use PDL::Graphics::PGPLOT::Window \& pdl> $win = pgwin(Device => \*(Aq/xs\*(Aq); \& pdl> $x = pdl [1..100] \& pdl> $y = sqrt($x) \& pdl> $win\->line($y) \& pdl> $win\->hold() \& pdl> $c = sin($x/10)*2 + 4 \& pdl> $win\->line($c) .Ve .PP In the following documentation the commands are not shown in their \s-1OO\s0 versions. This is for historical reasons and should not cause too much trouble. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package offers a \s-1OO\s0 interface to the \s-1PGPLOT\s0 plotting package. This is intended to replace the traditional interface in PDL::Graphics::PGPLOT and contains interfaces to a large number of \s-1PGPLOT\s0 routines. Below the usage examples for each function tend to be given in the non-OO version for historical reasons. This will slowly be changed, but in the meantime refer to the section on OO-interface below to see how to convert the usage information below to \s-1OO\s0 usage (it is totally trivial). .PP PDL::Graphics::PGPLOT::Window is an interface to the \s-1PGPLOT\s0 graphical libraries. It currently supports \s-1PGPLOT\-5.2\s0 and \s-1PGPLOT\-5\s0.2\-cd2. The \&\-cd2 version includes \s-1RGB\s0 output and anti-aliasing. .PP High-level plotting commands: .PP .Vb 10 \& imag \- Display an image (uses pgimag/pggray/pgrgbi as appropriate) \& fits_imag \- Display a FITS image in scientific coordinates \& cont \- Display image as contour map \& fits_cont \- Display a FITS image in scientific coordinates as a contour map \& vect \- Display 2 images as a vector field \& fits_vect \- Display 2 FITS images in sci. coordinates as a vector field \& ctab \- Load an image colour table \& ctab_info \- Get information about currently loaded colour table \& line \- Plot vector as connected points \& tline \- Plot a collection of vectors as lines \& lines \- Plot a polyline, multicolor vector [broadcastable] \& points \- Plot vector as points \& tpoints \- Plot a collection of vectors as points [broadcastable] \& errb \- Plot error bars \& bin \- Plot vector as histogram (e.g. bin(hist($data)) ) \& hi2d \- Plot image as 2d histogram (not very good IMHO...) \& tcircle \- Plot vectors as circles [broadcastable] \& label_axes \- Print axis titles \& legend \- Create a legend with different texts, linestyles etc. .Ve .PP Low-level plotting commands: .PP .Vb 7 \& arrow \- Draw an arrow \& poly \- Draw a polygon \& rectangle \- Draw a rectangle \& text \- Write text in the plot area \& cursor \- Interactively read cursor positions. \& circle \- Draw a circle \& ellipse \- Draw an ellipse. .Ve .PP Device manipulation commands: .PP .Vb 12 \& new \- Construct a new output device \& pgwin \- Exported hook to new() \& close \- Close a PGPLOT output device. \& hold \- Hold current plot window range \- allows overlays etc. \& release \- Release back to freshly autoscaling for each command. \& held \- Indicates whether the current window is held. \& focus \- Set focus to the given device. \& erase \- Erase the current window (or panel). \& options \- Get the options set for the present output device. \& id \- The ID for the device. \& device \- The device type. \& name \- The window name. .Ve .PP Notes: \f(CW$transform\fR for image/cont etc. is used in the same way as the \&\f(CW\*(C`TR()\*(C'\fR array in the underlying \s-1PGPLOT FORTRAN\s0 routine but is, fortunately, zero-offset. The \fBtransform()\fR routine can be used to create this ndarray. .PP For completeness: The transformation array connect the pixel index to a world coordinate such that: .PP .Vb 2 \& X = tr[0] + tr[1]*i + tr[2]*j \& Y = tr[3] + tr[4]*i + tr[5]*j .Ve .SS "Variable passing and extensions" .IX Subsection "Variable passing and extensions" In general variables are passed to the pgplot routines by using \&\f(CW\*(C`get_dataref\*(C'\fR to get the reference to the values. Before passing to pgplot routines however, the data are checked to see if they are in accordance with the format (typically dimensionality) required by the \s-1PGPLOT\s0 routines. This is done using the routine \f(CW\*(C`checkarg\*(C'\fR (internal to \s-1PGPLOT\s0). This routine checks the dimensionality of the input data. If there are superfluous dimensions of size 1 they will be trimmed away until the dimensionality is correct. Example: .PP Assume an ndarray with dimensions (1,100,1,1) is passed to \f(CW\*(C`line\*(C'\fR, which expects its inputs to be vectors. \f(CW\*(C`checkarg\*(C'\fR will then return an ndarray with dimensions (100). If instead the same ndarray was passed to \f(CW\*(C`imag\*(C'\fR, which requires 2D ndarrays as output, \f(CW\*(C`checkarg\*(C'\fR would return an ndarray with dimensionality (100, 1) (Dimensions are removed from the \fIstart\fR) .PP Thus, if you want to provide support for another \s-1PGPLOT\s0 function, the structure currently look like this (there are plans to use the Options package to simplify the options parsing): .PP .Vb 10 \& # Extract the hash(es) on the commandline \& ($arg, $opt)=_extract_hash(@_); \& \& \& checkarg($x, 3); # For a hypothetical 3D routine. \& catch_signals { \& ... \& pgcube($n, $x\->get_dataref); \& }; \& 1; .Ve .PP (the catch_signals block prevents problems with the perl-PGPLOT interface if the user hits Ctrl-C during an operation). .SS "Setting options" .IX Subsection "Setting options" All routines in this package take a hash with options as an optional input. This options hash can be used to set parameters for the subsequent plotting without going via the \s-1PGPLOT\s0 commands. .PP This is implemented such that the plotting settings (such as line width, line style etc.) are affected only for that plot, any global changes made, say, with \f(CW\*(C`pgslw()\*(C'\fR are preserved. Some modifications apply when using the \s-1OO\s0 interface, see below. .SS "Alphabetical listing of standard options" .IX Subsection "Alphabetical listing of standard options" The following options are always parsed. Whether they have any importance depend on the routine invoked \- e.g. line style is irrelevant for \f(CW\*(C`imag\*(C'\fR, or the \f(CW\*(C`justify\*(C'\fR option is irrelevant if the display is on 'hold'. This is indicated in the help text for the commands below. .PP The options are not case sensitive and will match for unique substrings, but this is not encouraged as obscure options might invalidate what you thought was a unique substring. .PP In the listing below examples are given of each option. The actual option can then be used in a plot command by specifying it as an argument to the function wanted (it can be placed anywhere in the command list). .PP E.g: .PP .Vb 2 \& $opt={COLOR=>2}; \& line $x, $y, $opt; # This will plot a line with red color .Ve .PP If you are plotting to a hardcopy device then a number of options use a different name: .PP .Vb 3 \& HardLW instead of LineWidth \& HardCH instead of CharSize \& HardFont instead of Font \& \& HardAxisColour instead of AxisColour \& HardColour instead of Colour .Ve .PP [although I'm not sure when HardColour is actually used] .IP "align" 4 .IX Item "align" If \f(CW\*(C`pix\*(C'\fR is set, then images and plots are not stretched to fill the plot area. the \f(CW\*(C`align\*(C'\fR string tells how to align them within the available area. 'L' and 'R' shove the plot against the left and right edges, respectively; 'B' and 'T' shove the plot against the bottom and top edges. The default is to center the image. e.g. '\s-1BL\s0' puts the image on the bottom left corner, while '\s-1CT\s0' centers the image horizontally while placing it at the top of the available plot area. This defaults to '\s-1BT\s0' for non-justified images, to '\s-1CC\s0' for justified images. .IP "arrow" 4 .IX Item "arrow" This options allows you to set the arrow shape, and optionally size for arrows for the vect routine. The arrow shape is specified as a hash with the key \s-1FS\s0 to set fill style, \s-1ANGLE\s0 to set the opening angle of the arrow head, \s-1VENT\s0 to set how much of the arrow head is cut out and \&\s-1SIZE\s0 to set the arrowsize. .Sp The following .Sp .Vb 1 \& $opt = {ARROW => {FS=>1, ANGLE=>60, VENT=>0.3, SIZE=>5}}; .Ve .Sp will make a broad arrow of five times the normal size. .Sp Alternatively the arrow can be specified as a set of numbers corresponding to an extension to the syntax for pgsah. The equivalent to the above is .Sp .Vb 1 \& $opt = {ARROW => pdl([1, 60, 0.3, 5})}; .Ve .Sp For the latter the arguments must be in the given order, and if any are not given the default values of 1, 45, 0.3 and 1.0 respectively will be used. .IP "arrowsize" 4 .IX Item "arrowsize" The arrowsize can be specified separately using this option to the options hash. It is useful if an arrowstyle has been set up and one wants to plot the same arrow with several sizes. Please note that it is \&\fBnot\fR possible to set arrowsize and character size in the same call to a plotting function. This should not be a problem in most cases. .Sp .Vb 1 \& $opt = {ARROWSIZE => 2.5}; .Ve .IP "axis" 4 .IX Item "axis" Set the axis value (see \*(L"env\*(R"). If you pass in a scalar you set the axis for the whole plot. You can also pass in an array ref for finer control of the axes. .Sp If you set the option to a scalar value, you get one of a few standard layouts. You can specify them by name or by number: .Sp .Vb 8 \& EMPTY (\-2) draw no box, axes or labels \& BOX (\-1) draw box only \& NORMAL (0) draw box and label it with coordinates \& AXES (1) same as NORMAL, but also draw (X=0,Y=0) axes \& GRID (2) same as AXES, but also draw grid lines \& LOGX (10) draw box and label X\-axis logarithmically \& LOGY (20) draw box and label Y\-axis logarithmically \& LOGXY (30) draw box and label both axes logarithmically .Ve .Sp When using logarithmic axes (\f(CW\*(C`LOGX\*(C'\fR, \f(CW\*(C`LOGY\*(C'\fR and \f(CW\*(C`LOGXY\*(C'\fR) you normally need to log the data yourself, e.g. .Sp .Vb 1 \& line $x\->log10, $y, {axis=>\*(AqLOGX\*(Aq}; .Ve .Sp For your convenience you can put PDL::Graphics::PGPLOT into autolog mode. In this mode a call to \f(CW\*(C`line\*(C'\fR or \f(CW\*(C`points\*(C'\fR will log the data for you and you can pass in the unmodified data, e.g. .Sp .Vb 2 \& autolog(1); # enable automatic logarithm calculation \& line $x, $y, {axis=>\*(AqLOGX\*(Aq}; # automatically displays logged x data .Ve .Sp You can use the function interface to enable autologging: .Sp .Vb 1 \& autolog(1); .Ve .Sp or use it with a window reference (mode switching on a per window basis) .Sp .Vb 1 \& $win\->autolog(1); .Ve .Sp \&\f(CW\*(C`autolog\*(C'\fR without arguments returns the current autolog setting (0=off, 1=on). .Sp If you set the \f(CW\*(C`AXIS\*(C'\fR option to an array ref, then you can specify the box/axis options separately for the horizontal (ordinate; X coordinate; 0th element) and vertical (abscissa; Y coordinate; 1st element)) axes. Each element of the array ref should contain a \s-1PGPLOT\s0 format string. Presence or absence of specific characters flags particular options. For normal numeric labels, the options are: .Sp .Vb 10 \& A : draw axis for this dimension. \& B : draw bottom (X) or left (Y) edge of frame. \& C : draw top (X) or right (Y) edge of frame. \& G : draw Grid of vertical (X) or horizontal (Y) lines. \& I : Invert ticks: draw them outside the plot rather than inside. \& L : Label the axis Logarithmically. \& P : Extend ("Project") major tick marks outside the box. \& M : Numeric labels go in the alternate place above (X) or to the \& right (Y) of the viewport. \& N : Numeric labels go in the usual location below (X) or to the \& left (Y) of the viewport \& T : Draw major tick marks at the major coordinate interval. \& S : Draw minor tick marks (subticks). \& V : Orient numeric labels Vertically. Only applicable to Y. \& (The default is to write them parallel to the axis.) \& 1 : Force decimal labelling, instead of automatic choice \& 2 : Force exponential labeling, instead of automatic. .Ve .Sp If you don't specify any axis value at all, the default is ['\s-1BCNST\s0','\s-1BCNST\s0'] for plots and ['\s-1BCINST\s0','\s-1BCINST\s0'] for images. (These list ref elements are handed on directly to the low-level \s-1PGPLOT\s0 routines). .Sp In addition, you can specify that your axis labels should be printed as days, hours, minutes, and seconds (ideal for julian dates and delta-t, or for angular quantities). You do that by setting additional character flags on the affected axis: .Sp .Vb 9 \& X : Use HH MM SS.S time labeling rather than conventional numeric \& labels. The ordinate is in secsonds. Hours roll over at 24. \& Y : Like \*(AqX\*(Aq but the hour field runs past 24 if necessary. \& Z : Like \*(AqX\*(Aq but with a days field too (only shown where nonzero). \& H : Label the numbers with superscript d, h, m, and s symbols. \& D : Label the numbers with superscript o, \*(Aq, and \*(Aq\*(Aq symbols. \& F : Omit first (lowest/leftmost) label; useful for tight layouts. \& O : Omit leading zeroes in numbers under 10 (e.g. " 3h 3m 1.2s" \& rather than "03h 03m 01.2s"). .Ve .Sp For example, to plot a numeric quantity versus Julian day of the year in a standard boxed plot with tick marks, you can use [\*(L"\s-1BNCSTZHO\*(R",\*(L"BCNST\*(R"\s0]. .IP "border" 4 .IX Item "border" Normally the limits are chosen so that the plot just fits; with this option you can increase (or decrease) the limits by either a relative (ie a fraction of the original axis width) or an absolute amount. Either specify a hash array, where the keys are \f(CW\*(C`TYPE\*(C'\fR (set to \&'relative' or 'absolute') and \f(CW\*(C`VALUE\*(C'\fR (the amount to change the limits by), or set to 1, which is equivalent to .Sp .Vb 1 \& BORDER => { TYPE => \*(Aqrel\*(Aq, VALUE => 0.05 } .Ve .IP "charsize" 4 .IX Item "charsize" Set the character/symbol size as a multiple of the standard size. .Sp .Vb 1 \& $opt = {CHARSIZE => 1.5} .Ve .Sp The HardCH option should be used if you are plotting to a hardcopy device. .IP "colour (or color)" 4 .IX Item "colour (or color)" Set the colour to be used for the subsequent plotting. This can be specified as a number, and the most used colours can also be specified with name, according to the following table (note that this only works for the default colour map): .Sp .Vb 3 \& 0 \- WHITE 1 \- BLACK 2 \- RED 3 \- GREEN 4 \- BLUE \& 5 \- CYAN 6 \- MAGENTA 7 \- YELLOW 8 \- ORANGE 14 \- DARKGRAY \& 16 \- LIGHTGRAY .Ve .Sp However there is a much more flexible mechanism to deal with colour. The colour can be set as a 3 or 4 element anonymous array (or ndarray) which gives the \s-1RGB\s0 colours. If the array has four elements the first element is taken to be the colour index to change. For normal work you might want to simply use a 3 element array with R, G and B values and let the package deal with the details. The R,G and B values go from 0 to 1. .Sp In addition the package will also try to interpret non-recognised colour names using the default X11 lookup table, normally using the \&\f(CW\*(C`rgb.txt\*(C'\fR that came with \s-1PGPLOT.\s0 .Sp For more details on the handling of colour it is best that the user consults the \s-1PGPLOT\s0 documentation. Further details on the handling of colour can be found in the documentation for the internal routine \&\*(L"_set_colour\*(R". .Sp The HardColour option should be used if you are plotting to a hardcopy device [this may be untrue?]. .IP "diraxis" 4 .IX Item "diraxis" This sets the direction of the axes of a plot or image, when you don't explicitly set them with the XRange and YRange options. It's particularly useful when you want (for example) to put long wavelengths (larger numbers) on the left hand side of your plot, or when you want to plot an image in (\s-1RA\s0,dec) coordinates. .Sp You can use either a scalar or a two-element perl array. If you set it to 0 (the default) then \s-1PDL\s0 will guess which direction you want to go. If you set it to a positive number, the axis will always increase to the right. If you set it to a negative number, the axis will always increase to the left. .Sp For example, [0,0] is the default, which is usually right. [1,1] tells \&\s-1PGPLOT\s0 to always increase the axis values up and to the right. For a plot of intensity (y\-axis) versus wavelength (x\-axis) you could say [\-1,1]. .Sp This option is really only useful if you want to allow autoranging but need to set the direction that the axis goes. If you use the ranging options (\f(CW\*(C`XRange\*(C'\fR and \f(CW\*(C`YRange\*(C'\fR), you can change the direction by changing the order of the maximum and minimum values. That direction will override \f(CW\*(C`DirAxis\*(C'\fR. .IP "filltype" 4 .IX Item "filltype" Set the fill type to be used by \*(L"poly\*(R", \*(L"circle\*(R", \&\*(L"ellipse\*(R", and \*(L"rectangle\*(R" The fill can either be specified using numbers or name, according to the following table, where the recognised name is shown in capitals \- it is case-insensitive, but the whole name must be specified. .Sp .Vb 4 \& 1 \- SOLID \& 2 \- OUTLINE \& 3 \- HATCHED \& 4 \- CROSS_HATCHED \& \& $opt = {FILLTYPE => \*(AqSOLID\*(Aq}; .Ve .Sp (see below for an example of hatched fill) .IP "font" 4 .IX Item "font" Set the character font. This can either be specified as a number following the \s-1PGPLOT\s0 numbering or name as follows (name in capitals): .Sp .Vb 4 \& 1 \- NORMAL \& 2 \- ROMAN \& 3 \- ITALIC \& 4 \- SCRIPT .Ve .Sp (Note that in a string, the font can be changed using the escape sequences \&\f(CW\*(C`\efn\*(C'\fR, \f(CW\*(C`\efr\*(C'\fR, \f(CW\*(C`\efi\*(C'\fR and \f(CW\*(C`\efs\*(C'\fR respectively) .Sp .Vb 1 \& $opt = {FONT => \*(AqROMAN\*(Aq}; .Ve .Sp gives the same result as .Sp .Vb 1 \& $opt = {FONT => 2}; .Ve .Sp The HardFont option should be used if you are plotting to a hardcopy device. .IP "hatching" 4 .IX Item "hatching" Set the hatching to be used if either fillstyle 3 or 4 is selected (see above) The specification is similar to the one for specifying arrows. The arguments for the hatching is either given using a hash with the key \s-1ANGLE\s0 to set the angle that the hatch lines will make with the horizontal, \s-1SEPARATION\s0 to set the spacing of the hatch lines in units of 1% of \f(CW\*(C`min(height, width)\*(C'\fR of the view surface, and \s-1PHASE\s0 to set the offset the hatching. Alternatively this can be specified as a 1x3 ndarray \f(CW\*(C`$hatch=pdl[$angle, $sep, $phase]\*(C'\fR. .Sp .Vb 2 \& $opt = {FILLTYPE => \*(AqHATCHED\*(Aq, \& HATCHING => {ANGLE=>30, SEPARATION=>4}}; .Ve .Sp Can also be specified as .Sp .Vb 1 \& $opt = {FILL=> \*(AqHATCHED\*(Aq, HATCH => pdl [30,4,0.0]}; .Ve .Sp For another example of hatching, see \*(L"poly\*(R". .IP "justify" 4 .IX Item "justify" If \f(CW\*(C`justify\*(C'\fR is set true, then the plot axes are shrunk to fit the plot or image and it specifies the aspect ratio of pixel coordinates in the plot or image. Setting justify=>1 will produce a correct-aspect-ratio, shrink-wrapped image or plot; setting justify=>0.5 will do the same thing but with a short and fat plot. The difference between \f(CW\*(C`justify\*(C'\fR and \f(CW\*(C`pix\*(C'\fR is that \&\f(CW\*(C`pix\*(C'\fR does not affect the shape of the axes themselves. .IP "linestyle" 4 .IX Item "linestyle" Set the line style. This can either be specified as a number following the \s-1PGPLOT\s0 numbering: .Sp .Vb 5 \& 1 \- SOLID line \& 2 \- DASHED \& 3 \- DOT\-DASH\-dot\-dash \& 4 \- DOTTED \& 5 \- DASH\-DOT\-DOT\-dot .Ve .Sp or using name (as given in capitals above). Thus the following two specifications both specify the line to be dotted: .Sp .Vb 2 \& $opt = {LINESTYLE => 4}; \& $varopt = {LINESTYLE => \*(AqDOTTED\*(Aq}; .Ve .Sp The names are not case sensitive, but the full name is required. .IP "linewidth" 4 .IX Item "linewidth" Set the line width. It is specified as a integer multiple of 0.13 mm. .Sp .Vb 1 \& $opt = {LINEWIDTH => 10}; # A rather fat line .Ve .Sp The HardLW option should be used if you are plotting to a hardcopy device. .IP "pitch" 4 .IX Item "pitch" Sets the number of data pixels per inch on the output device. You can set the \f(CW\*(C`unit\*(C'\fR (see below) to change this to any other \&\s-1PGPLOT\s0 unit (millimeters, pixels, etc.). Pitch is device independent, so an image should appear exactly the same size (e.g. \f(CW\*(C`Pitch=>100\*(C'\fR is 100 dpi) regardless of output device. .IP "pix" 4 .IX Item "pix" Sets the pixel aspect ratio height/width. The height is adjusted to the correct ratio, while maintaining any otherwise-set pitch or scale in the horizontal direction. Larger numbers yield tall, skinny pixels; smaller numbers yield short, fat pixels. .IP "scale" 4 .IX Item "scale" Sets the number of output display pixels per data pixel. You can set the \f(CW\*(C`unit\*(C'\fR (see below) to change this to number of \s-1PGPLOT\s0 units (inches, millimeters, etc.) per data pixel. \f(CW\*(C`scale\*(C'\fR is deprecated, as it is not device-independent; but it does come in handy for quick work on digital displays, where aliasing might otherwise interfere with image interpretation. For example, \f(CW\*(C`scale=>1\*(C'\fR displays images at their native resolution. .IP "Panel" 4 .IX Item "Panel" It is possible to define multiple plot ``panels'' with in a single window (see the NXPanel and NYPanel options in the constructor). You can explicitly set in which panel most plotting commands occur, by passing either a scalar or an array ref into the \f(CW\*(C`Panel\*(C'\fR option. There is also a panel method, but its use is deprecated because of a wart with the \s-1PGPLOT\s0 interface. .IP "plotting & imaging range" 4 .IX Item "plotting & imaging range" Explicitly set the plot range in x and y. X\-range and Y\-range are set separately via the aptly named options \f(CW\*(C`XRange\*(C'\fR and \f(CW\*(C`YRange\*(C'\fR. If omitted \&\s-1PGPLOT\s0 selects appropriate defaults (minimum and maximum of the data range in general). These options are ignored if the window is on hold. .Sp .Vb 4 \& line $x, $y, {xr => [0,5]}; # y\-range uses default \& line $x, $y, {XRange => [0,5], YRange => [\-1,3]}; # fully specified range \& imag $im, {XRange => [30,50], YRange=>[\-10,30]}; \& fits_imag $im, {XRange=>[\-2,2], YRange=>[0,1]}; .Ve .Sp Imaging requires some thought if you don't want to lose a pixel off the edge of the image. Pixels are value-centered (they are centered on the coordinate whose value they represent), so the appropriate range to plot the entirety of a 100x100 pixel image is \f(CW\*(C`[\-0.5,99.5]\*(C'\fR on each axis. .SH "OBJECT-ORIENTED INTERFACE" .IX Header "OBJECT-ORIENTED INTERFACE" This section will briefly describe how the PDL::Graphics::PGPLOT::Window package can be used in an object-oriented (\s-1OO\s0) approach and what the advantages of this would be. We will start with the latter .IP "Multiple windows." 4 .IX Item "Multiple windows." For the common user it is probably most interesting to use the \s-1OO\s0 interface when handling several open devices at the same time. If you have one variable for each plot device it is easier to distribute commands to the right device at the right time. This is the angle we will take in the rest of this description. .IP "Coding and abstraction" 4 .IX Item "Coding and abstraction" At a more fundamental level it is desirable to approach a situation where it is possible to have a generic plotting interface which gives access to several plotting libraries, much as \s-1PGPLOT\s0 gives access to different output devices. Thus in such a hypothetical package one would say: .Sp .Vb 2 \& my $win1 = Graphics::new(\*(AqPGPLOT\*(Aq, {Device => \*(Aq/xs\*(Aq}); \& my $win2 = Graphics::new(\*(Aqgnuplot\*(Aq, {Background => \*(AqGray\*(Aq}; .Ve .Sp From a more practical point of view such abstraction also comes in handy when you write a large program package and you do not want to import routines nilly-willy in which case an \s-1OO\s0 approach with method calls is a lot cleaner. .Sp The pgwin exported constructor, arguably, breaks this philosophy; hopefully it will ``wither away'' when other compatible modules are available. .PP Anyway, enough philosophizing, let us get down to Earth and give some examples of the use of \s-1OO PGPLOT.\s0 As an example we will take Odd (which happens to be a common Norwegian name) who is monitoring the birth of rabbits in O'Fib-o-nachy's farm (alternatively they can of course be monitoring processes or do something entirely different). Odd wants the user to be able to monitor both the birth rates and accumulated number of rabbits and the spatial distribution of the births. Since these are logically different they chooses to have two windows open: .PP .Vb 2 \& $rate_win = PDL::Graphics::PGPLOT::Window\->new(Device => \*(Aq/xw\*(Aq, \& Aspect => 1, WindowWidth => 5, NXPanel => 2); \& \& $area_win = PDL::Graphics::PGPLOT::Window\->new(Device => \*(Aq/xw\*(Aq, \& Aspect => 1, WindowWidth => 5); .Ve .PP See the documentation for \*(L"new\*(R" below for a full overview of the options you can pass to the constructor. .PP Next, Odd wants to create plotting areas for subsequent plots and maybe show the expected theoretical trends .PP .Vb 2 \& $rate_win\->env(0, 10, 0, 1000, {XTitle => \*(AqDays\*(Aq, YTitle => \*(Aq#Rabbits\*(Aq}); \& $rate_win\->env(0, 10, 0, 100, {Xtitle=>\*(AqDays\*(Aq, Ytitle => \*(AqRabbits/day\*(Aq}); \& \& $area_win\->env(0, 1, 0, 1, {XTitle => \*(AqKm\*(Aq, Ytitle => \*(AqKm\*(Aq}); \& # And theoretical prediction. \& $rate_win\->line(sequence(10), fibonacci(10), {Panel => [1, 1]}); .Ve .PP That is basically it. The commands should automatically focus the relevant window. Due to the limitations of \s-1PGPLOT\s0 this might however lead you to plot in the wrong panel... The package tries to be smart and do this correctly, but might get it wrong at times. .SH "STATE and RECORDING" .IX Header "STATE and RECORDING" A new addition to the graphics interface is the ability to record plot commands. This can be useful when you create a nice-looking plot on the screen that you want to re-create on paper for instance. Or if you want to redo it with slightly changed variables for instance. This is still under development and views on the interface are welcome. .PP The functionality is somewhat detached from the plotting functions described below so I will discuss them and their use here. .PP Recording is off by default. To turn it on when you create a new device you can set the \f(CW\*(C`Recording\*(C'\fR option to true, or you can set the \f(CW$PDL::Graphics::PGPLOT::RECORDING\fR variable to 1. I recommend doing the latter in your \f(CW\*(C`.perldlrc\*(C'\fR file at least since you will often have use for recording in the perldl or pdl2 script. .SS "Use of recording" .IX Subsection "Use of recording" The recording is meant to help you recreate a plot with new data or to a different device. The most typical situation is that you have created a beautiful plot on screen and want to have a Postscript file with it. In the dreary old world you needed to go back and execute all commands manually, but with this wonderful new contraption, the recorder, you can just replay your commands: .PP .Vb 6 \& dev \*(Aq/xs\*(Aq, {Recording => 1} \& $x = sequence(10) \& line $x, $x**2, {Linestyle => \*(AqDashed\*(Aq} \& $s = retrieve_state() # Get the current tape out of the recorder. \& dev \*(Aq/cps\*(Aq \& replay $s .Ve .PP This should result in a \f(CW\*(C`pgplot.ps\*(C'\fR file with a parabola drawn with a dashed line. Note the command \f(CW\*(C`retrieve_state\*(C'\fR which retrieves the current state of the recorder and return an object (of type PDL::Graphics::State) that is used to replay commands later. .SS "Controlling the recording" .IX Subsection "Controlling the recording" Like any self-respecting recorder you can turn the recorder on and off using the \f(CW\*(C`turn_on_recording\*(C'\fR and \f(CW\*(C`turn_off_recording\*(C'\fR respectively. Likewise you can clear the state using the \f(CW\*(C`clear_state\*(C'\fR command. .PP .Vb 9 \& $w=PDL::Graphics::PGPLOT::Window\->new(Device => \*(Aq/xs\*(Aq); \& $w\->turn_on_recording; \& $x=sequence(10); $y=$x*$x; \& $w\->line($x, $y); \& $w\->turn_off_recording; \& $w\->line($y, $x); \& $w\->turn_on_recording; \& $w\->line($x, $y*$x); \& $state = $w\->retrieve_state(); .Ve .PP We can then replay \f(CW$state\fR and get a parabola and a cubic plot. .PP .Vb 1 \& $w\->replay($state); .Ve .SS "Tips and Gotchas!" .IX Subsection "Tips and Gotchas!" The data are stored in the state object as references to the real data. This leads to one good and one potentially bad consequence: .IP "The good is that you can create the plot and then subsequently redo the same plot using a different set of data. This is best explained by an example. Let us first create a simple gradient image and get a copy of the recording:" 4 .IX Item "The good is that you can create the plot and then subsequently redo the same plot using a different set of data. This is best explained by an example. Let us first create a simple gradient image and get a copy of the recording:" .Vb 3 \& $im = sequence(10,10) \& imag $im \& $s=retrieve_state .Ve .Sp Now this was a rather dull plot, and in reality we wanted to show an image using \f(CW\*(C`rvals\*(C'\fR. Instead of re-creating the plot (which of course here would be the simplest option) we just change \f(CW$im\fR: .Sp .Vb 2 \& $im \-= sequence(10,10) \& $im += rvals(10,10) .Ve .Sp Now replay the commands .Sp .Vb 1 \& replay $s .Ve .Sp And hey presto! A totally different plot. Note however the trickery required to avoid losing reference to \f(CW$im\fR .ie n .IP "This takes us immediately to the major problem with the recording though. Memory leakage! Since the recording keeps references to the data it can keep data from being freed (zero reference count) when you expect it to be. For instance, in this example, we lose totally track of the original $im variable, but since there is a reference to it in the state it will not be freed" 4 .el .IP "This takes us immediately to the major problem with the recording though. Memory leakage! Since the recording keeps references to the data it can keep data from being freed (zero reference count) when you expect it to be. For instance, in this example, we lose totally track of the original \f(CW$im\fR variable, but since there is a reference to it in the state it will not be freed" 4 .IX Item "This takes us immediately to the major problem with the recording though. Memory leakage! Since the recording keeps references to the data it can keep data from being freed (zero reference count) when you expect it to be. For instance, in this example, we lose totally track of the original $im variable, but since there is a reference to it in the state it will not be freed" .Vb 4 \& $im = sequence(1000,1000) \& imag $im \& $s = retrieve_state \& $im = rvals(10,10) .Ve .Sp Thus after the execution of these commands we still have a reference to a 1000x1000 array which takes up a lot of memory... .Sp The solution is to call \f(CW\*(C`clear\*(C'\fR on the state variable: .Sp .Vb 1 \& $s\->clear() .Ve .Sp (This is done automatically if the variable goes out of scope). I forsee this problem to most acute when working on the \f(CW\*(C`perldl\*(C'\fR or \f(CW\*(C`pdl2\*(C'\fR command line, but since this is exactly where the recording is most useful the best advice is just to be careful and call clear on state variables. .Sp If you are working with scripts and use large images for instance I would instead recommend that you do not turn on recording unless you need it. .SH "FUNCTIONS" .IX Header "FUNCTIONS" A more detailed listing of the functions and their usage follows. For all functions we specify which options take effect and what other options exist for the given function. The function descriptions below are all given for the non-OO usage for historical reasons, but since the conversion to an \s-1OO\s0 method is trivial there is no major need for concern. Whenever you see a function example of the form .PP .Vb 1 \& Usage: a_simple_function($x, $y, $z [, $opt]); .Ve .PP and you wish to use the \s-1OO\s0 version, just let your mind read the above line as: .PP .Vb 1 \& Usage: $win\->a_simple_function($x, $y, $z [, $opt]); .Ve .PP where \f(CW$win\fR is a PDL::Graphics::PGPLOT::Window object. That is all. .SS "Window control functions." .IX Subsection "Window control functions." .SS "pgwin" .IX Subsection "pgwin" Exported constructor for \s-1PGPLOT\s0 object/device/plot window. .PP .Vb 3 \& Usage: pgwin($opt); \& Usage: pgwin($option\->$value,...); \& Usage: pgwin($device); .Ve .PP Parameters are passed on to \fBnew()\fR and can either be specified by hash reference or as a list. .PP See the documentation fo PDL::Graphics::PGPLOT::Window::new for details. .PP Because pgwin is a convenience function, you can specify the device by passing in a single non-ref parameter. For even further convenience, you can even omit the '/' in the device specifier, so these two lines deliver the same result: .PP .Vb 2 \& $win = pgwin(gif); \& $win = PDL::Graphics::PGPLOT::Window\->new({Dev=>\*(Aq/gif\*(Aq}); .Ve .SS "new" .IX Subsection "new" Constructor for \s-1PGPLOT\s0 object/device/plot window. .PP .Vb 2 \& Usage: PDL::Graphics::PGPLOT::Window\->new($opt); \& Usage: PDL::Graphics::PGPLOT::Window\->new($option=>$value,...); .Ve .PP Options to \fBnew()\fR can either be specified via a reference to a hash .PP .Vb 1 \& $win = PDL::Graphics::PGPLOT::Window\->new({Dev=>\*(Aq/xserve\*(Aq,ny=>2}); .Ve .PP or directly, as an array .PP .Vb 2 \& # NOTE: no more {} ! \& $win = PDL::Graphics::PGPLOT::Window\->new(Dev=>\*(Aq/xserve\*(Aq,ny=>2); .Ve .PP The following lists the recognised options: .IP "AspectRatio" 4 .IX Item "AspectRatio" The aspect ratio of the image, in the sense vertical/horizontal. See the discussion on size setting. .IP "Device" 4 .IX Item "Device" The type of device to use. The syntax of this is the one used by \s-1PGPLOT.\s0 .IP "Hold" 4 .IX Item "Hold" Hold the plot window so that subsequent plots can plot over existing plots. This can be adjusted with the \f(CW\*(C`hold()\*(C'\fR and \f(CW\*(C`release()\*(C'\fR methods. .IP "NXPanel" 4 .IX Item "NXPanel" The number of panels in the X\-direction .IP "NYPanel" 4 .IX Item "NYPanel" The number of panels in the Y\-direction .IP "Size" 4 .IX Item "Size" Yet another way to identify the plot window size \*(-- this takes a scalar or an array ref containing one, two, or three numbers. One number gives you a square window. Two gives you a rectangular window \f(CW\*(C`(X,Y)\*(C'\fR. Three lets you specify the unit compactly (e.g. \f(CW\*(C`[,,1]\*(C'\fR for inches, \&\f(CW\*(C`[,,2]\*(C'\fR for mm) but is deprecated in favor of using the \&\f(CW\*(C`Unit\*(C'\fR option. See the discussion on size setting. .IP "Unit" 4 .IX Item "Unit" The unit to use for size setting. \s-1PGPLOT\s0 accepts inch, mm, or pixel. The default unit is inches for historical reasons, but you can choose millimeters or (God forbid) pixels as well. String or numeric specifications are \s-1OK\s0 (0=normalized, 1=inches, 2=mm, 3=pixels). Normalized units make no sense here and are not accepted. Ideally someone will one day hook this into the \s-1CPAN\s0 units parser so you can specify window size in rods or attoparsecs. .IP "WindowName" 4 .IX Item "WindowName" The name to give to the window. No particular use is made of this at present. It would be great if it was possible to change the title of the window frame. .IP "WindowWidth" 4 .IX Item "WindowWidth" The width of the window in inches (or the specified Unit). See the discussion on size setting. .IP "WindowXSize and WindowYSize" 4 .IX Item "WindowXSize and WindowYSize" The width and height of the window in inches (or the specified Unit). See the discussion on size setting. .PP An important point to note is that the default values of most options can be specified by passing these to the constructor. All general options (common to several functions) can be adjusted in such a way, but function specific options can not be set in this way (this is a design limitation which is unlikely to be changed). .PP Thus the following call will set up a window where the default axis colour will be yellow and where plot lines normally have red colour and dashed linestyle. .PP .Vb 2 \& $win = PDL::Graphics::PGPLOT::Window\->new(Device => \*(Aq/xs\*(Aq, \& AxisColour => \*(AqYellow\*(Aq, Colour => \*(AqRed\*(Aq, LineStyle => \*(AqDashed\*(Aq); .Ve .PP Size setting: There are a gazillion ways to set window size, in keeping with \s-1TIMTOWTDI.\s0 In general you can get away with passing any unique combination of an \f(CW\*(C`\*(C'\fR size, a \f(CW\*(C`\*(C'\fRsize, and/or an aspect ratio. In increasing order of precedence, the options are: (\f(CW\*(C`Units\*(C'\fR, \&\f(CW\*(C`AspectRatio\*(C'\fR, \f(CW\*(C`WindowWidth\*(C'\fR, \f(CW\*(C`WindowSize\*(C'\fR, \f(CW\*(C`Size\*(C'\fR). .PP So if you specify an AspectRatio *and* an X and a Y coordinate, the AspectRatio is ignored. Likewise, if you specify Units and a three-component Size, the Units option is ignored in favor of the numeric unit in the Size. .PP If you don't specify enough information to set the size of the window, you get the default pane size and shape for that device. .SS "close" .IX Subsection "close" Close a plot window .PP .Vb 1 \& Usage: $win\->close() .Ve .PP Close the current window. This does not necessarily mean that the window is removed from your screen, but it does ensure that the device is closed. .PP A message will be printed to \s-1STDOUT\s0 giving the name of the file created if the plot was made to a hardcopy device and \&\f(CW$PDL::verbose\fR is true. .SS "held" .IX Subsection "held" Check if a window is on hold .PP .Vb 1 \& $is_held = $win\->held(); .Ve .PP Function to check whether the window is held or not. .SS "hold" .IX Subsection "hold" Hold the present window. .PP .Vb 1 \& Usage: $win\->hold() .Ve .PP Holds the present window so that subsequent plot commands overplots. .SS "panel" .IX Subsection "panel" Switch to a different panel .PP .Vb 1 \& $win\->panel(); .Ve .PP Move to a different panel on the plotting surface. Note that you will need to erase it manually if that is what you require. .PP This routine currently does something you probably don't want, and hence is deprecated for most use: if you say .PP .Vb 2 \& $win\->panel(1); \& $win\->imag($image); .Ve .PP then \f(CW$image\fR will actually be displayed in panel \fB2\fR. That's because the main plotting routines such as line and imag all advance the panel when necessary. Instead, it's better to use the Panel option within plotting commands, if you want to set the panel explicitly. .SS "release" .IX Subsection "release" Release a plot window. .PP .Vb 1 \& $win\->release() .Ve .PP Release a plot window so that subsequent plot commands move to the next panel or erase the plot and create a new plot. .SS "erase" .IX Subsection "erase" Erase plot .PP .Vb 1 \& $win\->erase($opt); .Ve .PP Erase a plot area. This accepts the option \f(CW\*(C`Panel\*(C'\fR or alternatively a number or array reference which makes it possible to specify the panel to erase when working with several panels. .SS "Plotting functions" .IX Subsection "Plotting functions" .SS "env" .IX Subsection "env" Define a plot window, and put graphics on 'hold' .PP .Vb 2 \& $win\->env( $xmin, $xmax, $ymin, $ymax, [$justify, $axis] ); \& $win\->env( $xmin, $xmax, $ymin, $ymax, [$options] ); .Ve .PP \&\f(CW$xmin\fR, \f(CW$xmax\fR, \f(CW$ymin\fR, \f(CW$ymax\fR are the plot boundaries. \&\f(CW$justify\fR is a boolean value (default is \fB0\fR); if true the axes scales will be the same (see \f(CW\*(C`justify\*(C'\fR). \&\f(CW$axis\fR describes how the axes should be drawn (see \&\f(CW\*(C`axis\*(C'\fR) and defaults to \fB0\fR. .PP If the second form is used, \f(CW$justify\fR and \f(CW$axis\fR can be set in the options hash, for example: .PP .Vb 2 \& $win\->env( 0, 100, 0, 50, {JUSTIFY => 1, AXIS => \*(AqGRID\*(Aq, \& CHARSIZE => 0.7} ); .Ve .PP In addition the following options can also be set for \f(CW\*(C`env\*(C'\fR: .IP "PlotPosition" 4 .IX Item "PlotPosition" The position of the plot on the page relative to the view surface in normalised coordinates as an anonymous array. The array should contain the lower and upper X\-limits and then the lower and upper Y\-limits. To place two plots above each other with no space between them you could do .Sp .Vb 2 \& $win\->env(0, 1, 0, 1, {PlotPosition => [0.1, 0.5, 0.1, 0.5]}); \& $win\->env(5, 9, 0, 8, {PlotPosition => [0.1, 0.5, 0.5, 0.9]}); .Ve .IP "Axis, Justify, Border" 4 .IX Item "Axis, Justify, Border" See the description of general options for these options. .IP "AxisColour" 4 .IX Item "AxisColour" Set the colour of the coordinate axes. .IP "XTitle, YTitle, Title, Font, CharSize" 4 .IX Item "XTitle, YTitle, Title, Font, CharSize" Axes titles and the font and size to print them. .SS "label_axes" .IX Subsection "label_axes" Label plot axes .PP .Vb 1 \& $win\->label_axes(, , , $options); .Ve .PP Draw labels for each axis on a plot. .SS "imag" .IX Subsection "imag" Display an image (uses \f(CW\*(C`pgimag()\*(C'\fR/\f(CW\*(C`pggray()\*(C'\fR as appropriate) .PP .Vb 1 \& $win\->imag ( $image, [$min, $max, $transform], [$opt] ) .Ve .PP \&\s-1NOTES\s0 .PP \&\f(CW$transform\fR for image/cont etc. is used in the same way as the \&\f(CW\*(C`TR()\*(C'\fR array in the underlying \s-1PGPLOT FORTRAN\s0 routine but is, fortunately, zero-offset. The \fBtransform()\fR routine can be used to create this ndarray. .PP If \f(CW$image\fR is two-dimensional, you get a grey or pseudocolor image using the scalar values at each X,Y point. If \f(CW$image\fR is three-dimensional and the third dimension has order 3, then it is treated as an \s-1RGB\s0 true-color image via \*(L"rgbi\*(R". .PP There are several options related to scaling. By default, the image is scaled to fit the \s-1PGPLOT\s0 default viewport on the screen. Scaling, aspect ratio preservation, and 1:1 pixel mapping are available. (1:1 pixel mapping is useful for avoiding display artifacts, but it's not recommended for final output as it's not device-independent.) .PP Here's an additional complication: the \*(L"pixel\*(R" stuff refers not (necessarily) to normal image pixels, but rather to \fItransformed\fR image pixels. That is to say, if you feed in a transform matrix via the \f(CW\*(C`TRANSFORM\*(C'\fR option, the \f(CW\*(C`PIX\*(C'\fR, \f(CW\*(C`SCALE\*(C'\fR, etc. options all refer to the transformed coordinates and not physical image pixels. That is a Good Thing because it, e.g., lets you specify plate scales of your output plots directly! See fits_imag for an example application. If you do not feed in a transform matrix, then the identity matrix is applied so that the scaling options refer to original data pixels. .PP To draw a colour bar (or wedge), either use the \f(CW\*(C`DrawWedge\*(C'\fR option, or the \f(CW\*(C`draw_wedge()\*(C'\fR routine (once the image has been drawn). .PP Options recognised: .IP "\s-1ITF\s0" 3 .IX Item "ITF" the image transfer function applied to the pixel values. It may be one of '\s-1LINEAR\s0', '\s-1LOG\s0', '\s-1SQRT\s0' (lower case is acceptable). It defaults to '\s-1LINEAR\s0'. .IP "\s-1MIN\s0" 3 .IX Item "MIN" Sets the minimum value to be used for calculation of the color-table stretch. .IP "\s-1MAX\s0" 3 .IX Item "MAX" Sets the maximum value for the same. .IP "\s-1RANGE\s0" 3 .IX Item "RANGE" A more compact way to specify \s-1MIN\s0 and \s-1MAX,\s0 as a list: you can say \*(L"Range=>[0,10]\*(R" to scale the color table for brightness values between 0 and 10 in the iamge data. .IP "\s-1CRANGE\s0" 3 .IX Item "CRANGE" Image values between \s-1MIN\s0 and \s-1MAX\s0 are scaled to an interval in normalized color domain space, on the interval [0,1], before lookup in the window's color table. \s-1CRANGE\s0 lets you use only a part of the color table by specifying your own range \*(-- e.g. if you say \*(L"CRange=>[0.25,0.75]\*(R" then only the middle half of the pseudocolor space will be used. (See the writeup on \fBctab()\fR.) .IP "\s-1TRANSFORM\s0" 3 .IX Item "TRANSFORM" The \s-1PGPLOT\s0 transform 'matrix' as a 6x1 vector for display .IP "DrawWedge" 3 .IX Item "DrawWedge" set to 1 to draw a colour bar (default is 0) .IP "Wedge" 3 .IX Item "Wedge" see the \fBdraw_wedge()\fR routine .PP The following standard options influence this command: .PP .Vb 1 \& AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN, XRANGE, YRANGE .Ve .PP .Vb 10 \& To see an image with maximum size in the current window, but square \& pixels, say: \& $win\->imag( $x, { PIX=>1 } ); \& An alternative approach is to try: \& $win\->imag( $x, { JUSTIFY=>1 } ); \& To see the same image, scaled 1:1 with device pixels, say: \& $win\->imag( $x, { SCALE=>1 } ); \& To see an image made on a device with 1:2 pixel aspect ratio, with \& X pixels the same as original image pixels, say \& $win\->imag( $x, { PIX=>0.5, SCALE=>2 } ); \& To display an image at 100 dpi on any device, say: \& $win\->imag( $x, { PITCH=>100 } ); \& To display an image with 100 micron pixels, say: \& $win\->imag( $x, { PITCH=>10, UNIT=>\*(Aqmm\*(Aq } ); .Ve .SS "imag1" .IX Subsection "imag1" Display an image with correct aspect ratio .PP .Vb 1 \& $win\->imag1 ( $image, [$min, $max, $transform], [$opt] ) .Ve .PP This is syntactic sugar for .PP .Vb 1 \& $win\->imag( { PIX=>1, ALIGN=>\*(AqCC\*(Aq } ); .Ve .SS "rgbi" .IX Subsection "rgbi" Display an \s-1RGB\s0 color image .PP The calling sequence is exactly like \*(L"imag\*(R", except that the input image must have three dimensions: \f(CW\*(C`N x M x 3\*(C'\fR. The last dimension is the (R,G,B) color value. This routine requires \fBpgplot 5.3devel\fR or later. Calling rgbi explicitly is not necessary, as calling image with an appropriately dimensioned \s-1RGB\s0 triplet makes it fall through to rgbi. .SS "fits_imag" .IX Subsection "fits_imag" Display a \s-1FITS\s0 image with correct axes .PP .Vb 1 \& $win\->fits_imag( image, [$min, $max], [$opt] ); .Ve .PP \&\s-1NOTES\s0 .IP "Titles:" 3 .IX Item "Titles:" Currently fits_imag also generates titles for you by default and appends the \&\s-1FITS\s0 header scientific units if they're present. So if you say .Sp .Vb 3 \& $pdl\->hdr\->{CTYPE1} = "Flamziness"; \& $pdl\->hdr\->{CUNIT1} = "milliBleems"; \& $win\->fits_imag($pdl); .Ve .Sp then you get an X title of \*(L"Flamziness (milliBleems)\*(R". But you can (of course) override that by specifying the XTitle and YTitle switches: .Sp .Vb 1 \& $win\->fits_imag($pdl,{Xtitle=>"Arbitrary"}); .Ve .Sp will give you \*(L"Arbitrary\*(R" as an X axis title, regardless of what's in the header. .IP "Scaling and aspect ratio:" 3 .IX Item "Scaling and aspect ratio:" If \s-1CUNIT1\s0 and \s-1CUNIT2\s0 (or, if they're missing, \s-1CTYPE1\s0 and \s-1CTYPE2\s0) agree, then the default pixel aspect ratio is 1 (in scientific units, \&\s-1NOT\s0 in original pixels). If they don't agree (as for a spectrum) then the default pixel aspect ratio is adjusted automatically to match the plot viewport and other options you've specified. .Sp You can override the image scaling using the \s-1SCALE, PIX,\s0 or \s-1PITCH\s0 options just as with the \fBimag()\fR method \*(-- but those parameters refer to the scientific coordinate system rather than to the pixel coordinate system (e.g. \f(CW\*(C`PITCH=>100\*(C'\fR means \*(L"100 scientific units per inch\*(R", and \f(CW\*(C`SCALE=>1\*(C'\fR means \*(L"1 scientific unit per device pixel\*(R"). See the \fBimag()\fR writeup for more info on these options. .Sp The default value of the \f(CW\*(C`ALIGN\*(C'\fR option is '\s-1CC\s0' \*(-- centering the image both vertically and horizontally. .IP "Axis direction:" 3 .IX Item "Axis direction:" By default, fits_imag tries to guess which direction your axes are meant to go (left-to-right or right-to-left) using the \s-1CDELT\s0 keywords: if \f(CW\*(C`CDELT\*(C'\fR is negative, then rather than reflecting the image fits_imag will plot the X axis so that the highest values are on the left. .Sp This is the most convenient behavior for folks who use calibrated (\s-1RA,DEC\s0) images, but it is technically incorrect. To force the direction, use the DirAxis option. Setting \&\f(CW\*(C`DirAxis=>1\*(C'\fR (abbreviated \f(CW\*(C`di=>1\*(C'\fR) will force the scientific axes to increase to the right, reversing the image as necessary. .IP "Color wedge:" 3 .IX Item "Color wedge:" By default fits_imag draws a color wedge on the right; you can explicitly set the \f(CW\*(C`DrawWedge\*(C'\fR option to 0 to avoid this. Use the \f(CW\*(C`WTitle\*(C'\fR option to set the wedge title. .IP "Alternate \s-1WCS\s0 coordinates:" 3 .IX Item "Alternate WCS coordinates:" The default behaviour is to use the primary/default \s-1WCS\s0 information in the \s-1FITS\s0 header (i.e. the \f(CW\*(C`CRVAL1\*(C'\fR,\f(CW\*(C`CRPIX1\*(C'\fR,... keywords). The Greisen et al. standard () allows alternative/additional mappings to be included in a header; these are denoted by the letters \f(CW\*(C`A\*(C'\fR to \f(CW\*(C`Z\*(C'\fR. If you know that your image contains such a mapping then you can use the \f(CW\*(C`WCS\*(C'\fR option to select the appropriate letter. For example, if you had read in a Chandra image created by the \s-1CIAO\s0 software package then you can display the image in the \f(CW\*(C`physical\*(C'\fR coordinate system by saying: .Sp .Vb 1 \& $win\->fits_imag( $pdl, { wcs => \*(Aqp\*(Aq } ); .Ve .Sp The identity transform is used if you select a mapping for which there is no information in the header. Please note that this support is \fBexperimental\fR and is not guaranteed to work correctly; please see the documentation for the \*(L"_FITS_tr\*(R" routine for more information. .SS "fits_rgbi" .IX Subsection "fits_rgbi" Display an \s-1RGB FITS\s0 image with correct axes .PP .Vb 1 \& $win\->fits_rgbi( image, [$min,$max], [$opt] ); .Ve .PP Works exactly like \*(L"fits_imag\*(R", but the image must be in (X,Y,RGB) form. Only the first two axes of the \s-1FITS\s0 header are examined. .SS "fits_cont" .IX Subsection "fits_cont" Draw contours of an image, labelling the axes using the \s-1WCS\s0 information in the \s-1FITS\s0 header of the image. .PP .Vb 1 \& $win\->fits_cont( image, [$contours, $transform, $misval], [$opt] ) .Ve .PP Does the same thing for the \*(L"cont\*(R" routine that \&\*(L"fits_imag\*(R" does for the \*(L"imag\*(R" routines. .SS "draw_wedge" .IX Subsection "draw_wedge" Add a wedge (colour bar) to an image. .PP .Vb 1 \& $win\->draw_wedge( [$opt] ) .Ve .PP Adds a wedge \- shows the mapping between colour and value for a pixel \- to the current image. This can also be achieved by setting \f(CW\*(C`DrawWedge\*(C'\fR to 1 when calling the \f(CW\*(C`imag\*(C'\fR routine. .PP The colour and font size are the same as used to draw the image axes (although this will probably fail if you did it yourself). To control the size and location of the wedge, use the \f(CW\*(C`Wedge\*(C'\fR option, giving it a hash reference containing any of the following: .IP "Side" 4 .IX Item "Side" Which side of the image to draw the wedge: can be one of 'B', 'L', 'T', or \&'R'. Default is \fB'R'\fR. .IP "Displacement" 4 .IX Item "Displacement" How far from the edge of the image should the wedge be drawn, in units of character size. To draw within the image use a negative value. Default is \fB1.5\fR. .IP "Width" 4 .IX Item "Width" How wide should the wedge be, in units of character size. Default is \fB2\fR. .IP "Label" 4 .IX Item "Label" A text label to be added to the wedge. If set, it is probably worth increasing the \f(CW\*(C`Width\*(C'\fR value by about 1 to keep the text readable. Default is \fB''\fR. This is equivalent to the \f(CW\*(C`WTitle\*(C'\fR option to \&\*(L"imag\*(R", \*(L"fits_imag\*(R", and similar methods. .IP "ForeGround (synonym Fg)" 4 .IX Item "ForeGround (synonym Fg)" The pixel value corresponding to the \*(L"maximum\*(R" colour. If \f(CW\*(C`undef\*(C'\fR, uses the value used by \f(CW\*(C`imag\*(C'\fR (recommended choice). Default is \f(CW\*(C`undef\*(C'\fR. .IP "BackGround (synonym Bg)" 4 .IX Item "BackGround (synonym Bg)" The pixel value corresponding to the \*(L"minimum\*(R" colour. If \f(CW\*(C`undef\*(C'\fR, uses the value used by \f(CW\*(C`imag\*(C'\fR (recommended choice). Default is \f(CW\*(C`undef\*(C'\fR. .PP .Vb 7 \& $x = rvals(50,50); \& $win = PDL::Graphics::PGPLOT::Window\->new(); \& $win\->imag( $x, { Justify => 1, ITF => \*(Aqsqrt\*(Aq } ); \& $win\->draw_wedge( { Wedge => { Width => 4, Label => \*(Aqfoo\*(Aq } } ); \& # although the following might be more sensible \& $win\->imag( $x, { Justify => 1, ITF => \*(Aqsqrt\*(Aq, DrawWedge => 1, \& Wedge => { Width => 4, Label => \*(Aqfoo\*(Aq} } ); .Ve .SS "ctab" .IX Subsection "ctab" Load an image colour table. .PP .Vb 1 \& Usage: .Ve .PP .Vb 4 \& ctab ( $name, [$contrast, $brightness] ) # Builtin col table \& ctab ( $ctab, [$contrast, $brightness] ) # $ctab is Nx4 array \& ctab ( $levels, $red, $green, $blue, [$contrast, $brightness] ) \& ctab ( \*(Aq\*(Aq, $contrast, $brightness ) # use last color table .Ve .PP Note: See PDL::Graphics::LUT for access to a large number of colour tables. .PP Notionally, all non-RGB images and vectors have their colors looked up in the window's color table. Colors in images and such are scaled to a normalized pseudocolor domain on the line segment [0,1]; the color table is a piecewise linear function that maps this one-dimensional scale to the three-dimensional normalized \s-1RGB\s0 color space [0,1]^3. .PP You can specify specific indexed colors by appropriate use of the (levels,red,green,blue) syntax \*(-- but that is deprecated, since the actual available number of colors can change depending on the output device. (Someone needs to write a specific hardware-dependent lookup table interface). .PP See also \*(L"imag\*(R" for a description of how to use only part of the color table for a particular image. .SS "ctab_info" .IX Subsection "ctab_info" Return information about the currently loaded color table .SS "autolog" .IX Subsection "autolog" Turn on automatic logarithmic scaling in \f(CW\*(C`line\*(C'\fR and \f(CW\*(C`points\*(C'\fR .PP .Vb 1 \& Usage: autolog([0|1]); .Ve .PP Setting the argument to 1 turns on automatic log scaling and setting it to zero turns it off again. The function can be used in both the object oriented and standard interface. To learn more, see the documentation for the axis option. .PP .Vb 3 \& my $win = PDL::Graphics::PGPLOT::Window\->new(dev=>\*(Aq/xserve\*(Aq); \& my $x=sequence(10); \& my $y=$x*$x+1; \& \& $win\->autolog(1); \& $win\->line($x,$y, {Axis => \*(AqLogY\*(Aq}); .Ve .SS "line" .IX Subsection "line" Plot vector as connected points .PP If the '\s-1MISSING\s0' option is specified, those points in the \f(CW$y\fR vector which are equal to the \s-1MISSING\s0 value are not plotted, but are skipped over. This allows one to quickly draw multiple lines with one call to \&\f(CW\*(C`line\*(C'\fR, for example to draw coastlines for maps. .PP .Vb 1 \& Usage: line ( [$x,] $y, [$opt] ) .Ve .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, COLO(U)R, LINESTYLE, LINEWIDTH, MISSING, \& JUSTIFY, SCALE, PITCH, PIX, ALIGN .Ve .PP .Vb 4 \& $x = sequence(10)/10.; \& $y = sin($x)**2; \& # Draw a red dot\-dashed line \& line $x, $y, {COLOR => \*(AqRED\*(Aq, LINESTYLE=>3}; .Ve .SS "lines" .IX Subsection "lines" Plot a list of vectors as discrete sets of connected points .PP This works much like \*(L"line\*(R", but for discrete sets of connected points. There are two ways to break lines: you can pass in x/y coordinates just like in \*(L"line\*(R", but with an additional \f(CW\*(C`pen\*(C'\fR ndarray that indicates whether the pen is up or down on the line segment following each point (so you set it to zero at the end of each line segment you want to draw); or you can pass in an array ref containing a list of single polylines to draw. .PP Happily, there's extra meaning packed into the \f(CW\*(C`pen\*(C'\fR ndarray: it multiplies the \s-1COLO\s0(U)R that you set, so if you feed in boolean values you get what you expect \*(-- but you can also feed in integer or floating-point values to get multicolored lines. .PP Furthermore, the sign bit of \f(CW\*(C`pen\*(C'\fR can be used to draw hairline segments: if \f(CW\*(C`pen\*(C'\fR is negative, then the segment is drawn as though it were positive but with LineWidth and HardLW set to 1 (the minimum). .PP Equally happily, even if you are using the array ref mechanism to break your polylines you can feed in an array ref of \f(CW\*(C`pen\*(C'\fR values to take advantage of the color functionality or further dice your polylines. .PP Note that, unlike \*(L"line\*(R", \f(CW\*(C`lines\*(C'\fR has no no specify\-$y\-only calling path. That's because \f(CW\*(C`lines\*(C'\fR is intended more for line art than for plotting, so you always have to specify both \f(CW$x\fR and \f(CW$y\fR. .PP Infinite or bad values are ignored \*(-- that is to say, if your vector contains a non-finite point, that point breaks the vector just as if you set pen=0 for both that point and the point before it. .PP .Vb 4 \& Usage: $w\->lines( $x, $y, [$pen], [$opt] ); \& $w\->lines( $xy, [$pen], [$opt] ); \& $w\->lines( \e@xvects, \e@yvects, [\e@pen], [$opt] ); \& $w\->lines( \e@xyvects, [\e@pen], [$opt] ); .Ve .PP The following standard options influence this command: \s-1AXIS, BORDER, COLO\s0(U)R, \s-1LINESTYLE, LINEWIDTH, MISSING,\s0 \s-1JUSTIFY, SCALE, PITCH, PIX, ALIGN\s0 .PP \&\s-1CAVEAT:\s0 .PP Setting \f(CW\*(C`pen\*(C'\fR elements to 0 prevents drawing altogether, so you can't use that to draw in the background color. .SS "points" .IX Subsection "points" Plot vector as points .PP .Vb 1 \& Usage: points ( [$x,] $y, [$symbol(s)], [$opt] ) .Ve .PP Options recognised: .PP .Vb 9 \& SYMBOL \- Either an ndarray with the same dimensions as $x, containing \& the symbol associated to each point or a number specifying \& the symbol to use for every point, or a name specifying the \& symbol to use according to the following (recognised name in \& capital letters): \& 0 \- SQUARE 1 \- DOT 2 \- PLUS 3 \- ASTERISK \& 4 \- CIRCLE 5 \- CROSS 7 \- TRIANGLE 8 \- EARTH \& 9 \- SUN 11 \- DIAMOND 12\- STAR \& PLOTLINE \- If this is >0 a line will be drawn through the points. .Ve .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH, \& JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .PP \&\f(CW\*(C`SymbolSize\*(C'\fR allows adjusting the symbol size, it defaults to CharSize. .PP The \f(CW\*(C`ColorValues\*(C'\fR option allows one to plot \s-1XYZ\s0 data with the Z axis mapped to a color value. For example: .PP .Vb 3 \& use PDL::Graphics::LUT; \& ctab(lut_data(\*(Aqidl5\*(Aq)); # set up color palette to \*(Aqidl5\*(Aq \& points ($x, $y, {ColorValues => $z}); .Ve .PP .Vb 3 \& $y = sequence(10)**2+random(10); \& # Plot blue stars with a solid line through: \& points $y, {PLOTLINE => 1, COLOUR => BLUE, symbol => STAR}; # case insensitive .Ve .SS "errb" .IX Subsection "errb" Plot error bars (using \f(CW\*(C`pgerrb()\*(C'\fR) .PP Usage: .PP .Vb 4 \& errb ( $y, $yerrors, [$opt] ) \& errb ( $x, $y, $yerrors, [$opt] ) \& errb ( $x, $y, $xerrors, $yerrors, [$opt] ) \& errb ( $x, $y, $xloerr, $xhierr, $yloerr, $yhierr, [$opt]) .Ve .PP Any of the error bar parameters may be \f(CW\*(C`undef\*(C'\fR to omit those error bars. .PP Options recognised: .PP .Vb 3 \& TERM \- Length of terminals in multiples of the default length \& SYMBOL \- Plot the datapoints using the symbol value given, either \& as name or number \- see documentation for \*(Aqpoints\*(Aq .Ve .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, CHARSIZE, COLOUR, LINESTYLE, LINEWIDTH, \& JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .PP .Vb 3 \& $y = sequence(10)**2+random(10); \& $sigma=0.5*sqrt($y); \& errb $y, $sigma, {COLOUR => RED, SYMBOL => 18}; \& \& # plot X bars only \& errb( $x, $y, $xerrors, undef ); \& \& # plot negative going bars only \& errb( $x, $y, $xloerr, undef, $yloerr, undef ); .Ve .SS "cont" .IX Subsection "cont" Display image as contour map .PP .Vb 1 \& Usage: cont ( $image, [$contours, $transform, $misval], [$opt] ) .Ve .PP Notes: \f(CW$transform\fR for image/cont etc. is used in the same way as the \&\f(CW\*(C`TR()\*(C'\fR array in the underlying \s-1PGPLOT FORTRAN\s0 routine but is, fortunately, zero-offset. The \fBtransform()\fR routine can be used to create this ndarray. .PP Options recognised: .PP .Vb 10 \& CONTOURS \- A ndarray with the contour levels \& FOLLOW \- Follow the contour lines around (uses pgcont rather than \& pgcons) If this is set >0 the chosen linestyle will be \& ignored and solid line used for the positive contours \& and dashed line for the negative contours. \& LABELS \- An array of strings with labels for each contour \& LABELCOLOUR \- The colour of labels if different from the draw colour \& This will not interfere with the setting of draw colour \& using the colour keyword. \& MISSING \- The value to ignore for contouring \& NCONTOURS \- The number of contours wanted for automatical creation, \& overridden by CONTOURS \& TRANSFORM \- The pixel\-to\-world coordinate transform vector .Ve .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, COLOUR, LINESTYLE, LINEWIDTH, \& JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .PP .Vb 6 \& $x=sequence(10,10); \& $ncont = 4; \& $labels= [\*(AqCOLD\*(Aq, \*(AqCOLDER\*(Aq, \*(AqFREEZING\*(Aq, \*(AqNORWAY\*(Aq] \& # This will give four blue contour lines labelled in red. \& cont $x, {NCONT => $ncont, LABELS => $labels, LABELCOLOR => RED, \& COLOR => BLUE} .Ve .SS "bin" .IX Subsection "bin" Plot vector as histogram (e.g. \f(CW\*(C`bin(hist($data))\*(C'\fR) .PP .Vb 1 \& Usage: bin ( [$x,] $data ) .Ve .PP Options recognised: .PP .Vb 3 \& CENTRE \- (default=1) if true, the x values denote the centre of the \& bin otherwise they give the lower\-edge (in x) of the bin \& CENTER \- as CENTRE .Ve .PP The following standard options influence this command: .PP .Vb 1 \& AXIS, BORDER, COLOUR, JUSTIFY, LINESTYLE, LINEWIDTH .Ve .SS "hi2d" .IX Subsection "hi2d" Plot image as 2d histogram (not very good \s-1IMHO...\s0) .PP .Vb 1 \& Usage: hi2d ( $image, [$x, $ioff, $bias], [$opt] ) .Ve .PP Options recognised: .PP .Vb 3 \& IOFFSET \- The offset for each array slice. >0 slants to the right \& <0 to the left. \& BIAS \- The bias to shift each array slice up by. .Ve .PP The following standard options influence this command: .PP .Vb 1 \& AXIS, BORDER, JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .PP Note that meddling with the \f(CW\*(C`ioffset\*(C'\fR and \f(CW\*(C`bias\*(C'\fR often will require you to change the default plot range somewhat. It is also worth noting that if you have TriD working you will probably be better off using mesh3d or a similar command \- see the PDL::Graphics::TriD module. .PP .Vb 3 \& $r=sequence(100)/50\-1.0; \& $y=exp(\-$r**2)*transpose(exp(\-$r**2)) \& hi2d $y, {IOFF => 1.5, BIAS => 0.07}; .Ve .SS "arrow" .IX Subsection "arrow" Plot an arrow .PP .Vb 1 \& Usage: arrow($x1, $y1, $x2, $y2, [, $opt]); .Ve .PP Plot an arrow from \f(CW\*(C`$x1, $y1\*(C'\fR to \f(CW\*(C`$x2, $y2\*(C'\fR. The arrow shape can be set using the option \f(CW\*(C`Arrow\*(C'\fR. See the documentation for general options for details about this option (and the example below): .PP Example: .PP .Vb 1 \& arrow(0, 1, 1, 2, {Arrow => {FS => 1, Angle => 1, Vent => 0.3, Size => 5}}); .Ve .PP which draws a broad, large arrow from (0, 1) to (1, 2). .SS "rect" .IX Subsection "rect" Draw a non-rotated rectangle .PP Usage: rect ( \f(CW$x1\fR, \f(CW$x2\fR, \f(CW$y1\fR, \f(CW$y2\fR ) .PP Options recognised: .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH \& JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .SS "poly" .IX Subsection "poly" Draw a polygon .PP .Vb 1 \& Usage: poly ( $x, $y ) .Ve .PP Options recognised: .PP The following standard options influence this command: .PP .Vb 2 \& AXIS, BORDER, COLOUR, FILLTYPE, HATCHING, LINESTYLE, LINEWIDTH \& JUSTIFY, SCALE, PIX, PITCH, ALIGN .Ve .PP .Vb 8 \& # Fill with hatching in two different colours \& $x=sequence(10)/10; \& # First fill with cyan hatching \& poly $x, $x**2, {COLOR=>5, FILL=>3}; \& hold; \& # Then do it over again with the hatching offset in phase: \& poly $x, $x**2, {COLOR=>6, FILL=>3, HATCH=>{PHASE=>0.5}}; \& release; .Ve .SS "circle" .IX Subsection "circle" Plot a circle on the display using the fill setting. .PP .Vb 1 \& Usage: circle($x, $y, $radius [, $opt]); .Ve .PP All arguments can alternatively be given in the options hash using the following options: .IP "XCenter and YCenter" 4 .IX Item "XCenter and YCenter" The position of the center of the circle .IP "Radius" 4 .IX Item "Radius" The radius of the circle. .SS "ellipse" .IX Subsection "ellipse" Plot an ellipse, optionally using fill style. .PP .Vb 1 \& Usage: ellipse($x, $y, $smaj, $smin, $theta [, $opt]); .Ve .PP All arguments can alternatively be given in the options hash using the following options (for historical reasons the names MajorAxis and MinorAxis have been preserved though they really refer to the semi-axes): .IP "MajorAxis" 4 .IX Item "MajorAxis" The semi-major axis of the ellipse \- this must be defined or \f(CW$smaj\fR must be given. .IP "MinorAxis" 4 .IX Item "MinorAxis" The semi-minor axis, like \f(CW\*(C`MajorAxis\*(C'\fR this is required or \f(CW$smin\fR must be given. .IP "Theta (synonym Angle)" 4 .IX Item "Theta (synonym Angle)" The orientation of the ellipse \- defaults to 0.0. This is given in radians. .IP "XCenter and YCenter" 4 .IX Item "XCenter and YCenter" The coordinates of the center of the ellipse. These must be specified or \&\f(CW$x\fR and \f(CW$y\fR must be given. .IP "NPoints" 4 .IX Item "NPoints" The number of points used to draw the ellipse. This defaults to 100 and might need changing in the case of very large ellipses. .PP The routine also recognises the same standard options as accepted by \*(L"poly\*(R". .SS "rectangle" .IX Subsection "rectangle" Draw a rectangle. .PP .Vb 1 \& Usage: rectangle($xcenter, $ycenter, $xside, $yside, [, $angle, $opt]); .Ve .PP This routine draws a rectangle with the chosen fill style. Internally it calls \*(L"poly\*(R" which is somewhat slower than \f(CW\*(C`pgrect\*(C'\fR but which allows for rotated rectangles as well. The routine recognises the same options as \f(CW\*(C`poly\*(C'\fR and in addition the following: .IP "XCenter and YCenter" 4 .IX Item "XCenter and YCenter" The position of the center of the rectangle. XCentre and YCentre are valid synonyms. .IP "XSide and YSide" 4 .IX Item "XSide and YSide" The length of the X and Y sides. If only one is specified the shape is taken to be square with that as the side-length, alternatively the user can set Side .IP "Side" 4 .IX Item "Side" The length of the sides of the rectangle (in this case a square) \- syntactic sugar for setting XSide and YSide identical. This is overridden by XSide or YSide if any of those are set. .IP "Angle (synonym Theta)" 4 .IX Item "Angle (synonym Theta)" The angle at which the rectangle is to be drawn. This defaults to 0.0 and is given in radians. .SS "vect" .IX Subsection "vect" Display 2 images as a vector field .PP .Vb 2 \& Usage: vect ( $w, $x, $y, [$scale, $pos, $transform, $misval], { opt } ); \& $w\->vect($x,$y,[$scale,$pos,$transform,$misval], { opt }); .Ve .PP Notes: \f(CW$transform\fR for image/cont etc. is used in the same way as the \&\f(CW\*(C`TR()\*(C'\fR array in the underlying \s-1PGPLOT FORTRAN\s0 routine but is, fortunately, zero-offset. The \fBtransform()\fR routine can be used to create this ndarray. .PP This routine will plot a vector field. \f(CW$x\fR is the horizontal component and \f(CW$y\fR the vertical component. The scale factor converts between vector length units and scientific positional units. You can set the scale, position, etc. either by passing in parameters in the normal parameter list or by passing in options. .PP Options recognised: .PP .Vb 7 \& SCALE \- Set the scale factor for vector lengths. \& POS \- Set the position of vectors. \& <0 \- vector head at coordinate \& >0 \- vector base at coordinate \& =0 \- vector centered on the coordinate \& TRANSFORM \- The pixel\-to\-world coordinate transform vector \& MISSING \- Elements with this value are ignored. .Ve .PP The following standard options influence this command: .PP .Vb 2 \& ARROW, ARROWSIZE, AXIS, BORDER, CHARSIZE, COLOUR, \& LINESTYLE, LINEWIDTH, .Ve .PP .Vb 3 \& $x=rvals(11,11,{Centre=>[5,5]}); \& $y=rvals(11,11,{Centre=>[0,0]}); \& vect $x, $y, {COLOR=>YELLOW, ARROWSIZE=>0.5, LINESTYLE=>dashed}; .Ve .SS "fits_vect" .IX Subsection "fits_vect" Display a pair of 2\-D ndarrays as vectors, with \s-1FITS\s0 header interpretation .PP .Vb 1 \& Usage: fits_vect ($x, $y, [$scale, $pos, $transform, $misval] ) .Ve .PP \&\f(CW\*(C`fits_vect\*(C'\fR is to \*(L"vect\*(R" as \*(L"fits_imag\*(R" is to \*(L"imag\*(R". .SS "transform" .IX Subsection "transform" Create transform array for contour and image plotting .PP .Vb 1 \& $win\->transform([$xdim,$ydim], $options); .Ve .PP (For information on coordinate transforms, try PDL::Transform.) This function creates a transform array in the format required by the image and contouring routines. You must call it with the dimensions of your image as arguments or pass these as an anonymous hash \- see the example below. .IP "Angle" 4 .IX Item "Angle" The rotation angle of the transform, in radians. Positive numbers rotate the image clockwise on the screen. .IP "ImageDimensions" 4 .IX Item "ImageDimensions" The dimensions of the image the transform is required for. The dimensions should be passed as a reference to an array. .IP "Pixinc" 4 .IX Item "Pixinc" The increment in output coordinate per pixel. .IP "ImageCenter (or ImageCentre)" 4 .IX Item "ImageCenter (or ImageCentre)" The centre of the image as an anonymous array \fBor\fR as a scalar, in scientific coordinates. In the latter case the x and y value for the center will be set equal to this scalar. This is particularly useful in the common case when the center is (0, 0). (ImageCenter overrides RefPos if both are specified). .IP "RefPos (or ReferencePosition)" 4 .IX Item "RefPos (or ReferencePosition)" If you wish to set a pixel other than the image centre to a given value, use this option. It should be supplied with a reference to an array containing 2 2\-element array references, e.g. .Sp .Vb 1 \& RefPos => [ [ $xpix, $ypix ], [ $xplot, $yplot ] ] .Ve .Sp This will label pixel \f(CW\*(C`($xpix,$ypix)\*(C'\fR as being at position \&\f(CW\*(C`($xplot,$yplot)\*(C'\fR. For example .Sp .Vb 1 \& RefPos => [ [100,74], [ 0, 0 ] ] .Ve .Sp sets the scientific coordinate origin to be at the center of the (100,74) pixel coordinate. The pixel coordinates are pixel-centered, and start counting from 0 (as all good pixel coordinates should). .PP Example: .PP .Vb 4 \& $im = rvals(100, 100); \& $w = PDL::Graphics::PGPLOT::Window\->new(Device => \*(Aq/xs\*(Aq); \& $t = $w\->transform(dims($im), {ImageCenter => 0, Pixinc => 5}); \& $w\->imag($im, {Transform => $t}); .Ve .SS "tline" .IX Subsection "tline" Broadcasted line plotting .PP .Vb 1 \& $win\->tline($x, $y, $options); .Ve .PP This is a broadcasted interface to \f(CW\*(C`line\*(C'\fR. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a \*(L"reasonable\*(R" way. In the sense that it will loop over the options wrapping over if there are less options than lines. .PP Example: .PP .Vb 4 \& $h={Colour => [\*(AqRed\*(Aq, \*(Aq1\*(Aq, 4], Linestyle => [\*(AqSolid\*(Aq ,\*(AqDashed\*(Aq]}; \& $tx=zeroes(100,5)\->xlinvals(\-5,5); \& $ty = $tx + $tx\->yvals; \& $win\->tline($tx, $ty, $h); .Ve .SS "tpoints" .IX Subsection "tpoints" A broadcasted interface to points .PP .Vb 1 \& Usage: tpoints($x, $y, $options); .Ve .PP This is a broadcasted interface to \f(CW\*(C`points\*(C'\fR. This is convenient if you have a 2D array and want to plot out every line in one go. The routine will apply any options you apply in a \*(L"reasonable\*(R" way. In the sense that it will loop over the options wrapping over if there are less options than lines. .PP Example: .PP .Vb 4 \& $h={Colour => [\*(AqRed\*(Aq, \*(Aq1\*(Aq, 4], Linestyle => [\*(AqSolid\*(Aq ,\*(AqDashed\*(Aq]}; \& $tx=zeroes(100,5)\->xlinvals(\-5,5); \& $ty = $tx + $tx\->yvals; \& tpoints($tx, $ty, $h); .Ve .SS "tcircle" .IX Subsection "tcircle" A broadcasted interface to circle .PP .Vb 1 \& Usage: tcircle($x, $y, $r, $options); .Ve .PP This is a broadcasted interface to \f(CW\*(C`circle\*(C'\fR. This is convenient if you have a list of circle centers and radii and want to draw every circle in one go. The routine will apply any options you apply in a \*(L"reasonable\*(R" way, in the sense that it will loop over the options wrapping over if there are less options than circles. .PP Example: .PP .Vb 5 \& $x=sequence(5); \& $y=random(5); \& $r=sequence(5)/10 + 0.1; \& $h={justify => 1,Color => [\*(Aqred\*(Aq,\*(Aqgreen\*(Aq,\*(Aqblue\*(Aq], filltype => [\*(Aqsolid\*(Aq,\*(Aqoutline\*(Aq,\*(Aqhatched\*(Aq,\*(Aqcross_hatched\*(Aq]}; \& tcircle($x, $y, $r, $h); .Ve .PP Note that \f(CW$x\fR and \f(CW$y\fR must be the same size (>1D is \s-1OK,\s0 though meaningless as far as \f(CW\*(C`tcircle\*(C'\fR is concerned). \f(CW$r\fR can be the same size as \f(CW$x\fR \s-1OR\s0 a 1\-element ndarray \s-1OR\s0 a single perl scalar. .SS "Text routines" .IX Subsection "Text routines" .SS "text" .IX Subsection "text" Write text in a plot window at a specified position. .PP .Vb 1 \& Usage: text ($text, $x, $y [, $opt]) .Ve .PP Options recognised: .ie n .IP """ANGLE""" 4 .el .IP "\f(CWANGLE\fR" 4 .IX Item "ANGLE" The angle in degrees between the baseline of the text and the horisontal (increasing counter-clockwise). This defaults to 0. .ie n .IP """JUSTIFICATION""" 4 .el .IP "\f(CWJUSTIFICATION\fR" 4 .IX Item "JUSTIFICATION" The justification of the text relative to the position specified. It defaults to 0.0 which gives left-justified text. A value of 0.5 gives centered text and a value of 1.0 gives right-justified text. .ie n .IP """XPos"", ""YPos"", ""Text""" 4 .el .IP "\f(CWXPos\fR, \f(CWYPos\fR, \f(CWText\fR" 4 .IX Item "XPos, YPos, Text" These gives alternative ways to specify the text and position. .ie n .IP """BackgroundColour""" 4 .el .IP "\f(CWBackgroundColour\fR" 4 .IX Item "BackgroundColour" This sets the background colour for the text in case an opaque background is desired. You can also use the synonyms \f(CW\*(C`Bg\*(C'\fR and \f(CW\*(C`BackgroundColor\*(C'\fR. .PP The following standard options influence this command: .PP .Vb 1 \& COLOUR, CHARSIZE .Ve .PP .Vb 2 \& line sequence(10), sequence(10)**2; \& text \*(AqA parabola\*(Aq, 3, 9, {Justification => 1, Angle=>atan2(6,1)}; .Ve .SS "legend" .IX Subsection "legend" Add a legend to a plot .PP .Vb 1 \& Usage: legend($text, $x, $y, [, $width], $opt]); .Ve .PP This function adds a legend to an existing plot. The action is primarily controlled by information in the options hash, and the basic idea is that \&\f(CW$x\fR and \f(CW$y\fR determines the upper left hand corner of the box in which the legend goes. If the width is specified either as an argument or as an option in the option hash this is used to determine the optimal character size to fit the text into part of this width (defaults to 0.5 \- see the description of \f(CW\*(C`TextFraction\*(C'\fR below). The rest of the width is filled out with either lines or symbols according to the content of the \f(CW\*(C`LineStyle\*(C'\fR, \&\f(CW\*(C`Symbol\*(C'\fR, \f(CW\*(C`Colour\*(C'\fR and \f(CW\*(C`LineWidth\*(C'\fR options. .PP The local options recognised are as follows: .ie n .IP """Text""" 4 .el .IP "\f(CWText\fR" 4 .IX Item "Text" An anonymous array of annotations, can also be specified directly. .ie n .IP """XPos"" and ""YPos""" 4 .el .IP "\f(CWXPos\fR and \f(CWYPos\fR" 4 .IX Item "XPos and YPos" The X and Y position of the upper left-hand corner of the text. .ie n .IP """Width"" and ""Height""" 4 .el .IP "\f(CWWidth\fR and \f(CWHeight\fR" 4 .IX Item "Width and Height" The width and/or height of each line (including symbol/line). This is used to determine the character size. If any of these are set to 'Automatic' the current character size will be used. .ie n .IP """TextFraction""" 4 .el .IP "\f(CWTextFraction\fR" 4 .IX Item "TextFraction" The text and the symbol/line is set inside a box. \f(CW\*(C`TextFraction\*(C'\fR determines how much of this box should be devoted to text. This defaults to 0.5. You can also use \f(CW\*(C`Fraction\*(C'\fR as a synonym to this. .ie n .IP """TextShift""" 4 .el .IP "\f(CWTextShift\fR" 4 .IX Item "TextShift" This option allows for fine control of the spacing between the text and the start of the line/symbol. It is given in fractions of the total width of the legend box. The default value is 0.1. .ie n .IP """VertSpace"" or ""VSpace""" 4 .el .IP "\f(CWVertSpace\fR or \f(CWVSpace\fR" 4 .IX Item "VertSpace or VSpace" By default the text lines are separated by one character height (in the sense that if the separation were 0 then they would lie on top of each other). The \&\f(CW\*(C`VertSpace\*(C'\fR option allows you to increase (or decrease) this gap in units of the character height; a value of 0.5 would add half a character height to the gap between lines, and \-0.5 would remove the same distance. The default value is 0. .ie n .IP """BackgroundColour""" 4 .el .IP "\f(CWBackgroundColour\fR" 4 .IX Item "BackgroundColour" This sets the background colour for the text in case an opaque background is desired. You can also use the synonyms \f(CW\*(C`Bg\*(C'\fR and \f(CW\*(C`BackgroundColor\*(C'\fR. .PP .Vb 2 \& line $x, $y, {Color => \*(AqRed\*(Aq, LineStyle => \*(AqSolid\*(Aq}; \& line $x2, $y2, {Color => \*(AqBlue\*(Aq, \*(AqLineStyle\*(Aq => \*(AqDashed\*(Aq, LineWidth => 10}; \& \& legend [\*(AqA red line\*(Aq, \*(AqA blue line\*(Aq], 5, 5, \& {LineStyle => [\*(AqSolid\*(Aq, \*(AqDashed\*(Aq], Colour => [\*(AqRed\*(Aq, \*(AqBlue\*(Aq] \& LineWidth => [undef, 10]}; # undef gives default. .Ve .SS "Cursor routines" .IX Subsection "Cursor routines" .SS "cursor" .IX Subsection "cursor" Interactively read cursor positions. .PP .Vb 1 \& Usage: ($x, $y, $ch, $xref, $yref) = cursor($opt) .Ve .PP This routine has no standard input parameters, but the type of cursor can be set by setting the option \f(CW\*(C`Type\*(C'\fR as a key in the anonymous hash \&\f(CW$opt\fR. The first three return values from the function are always defined and gives the position selected by the user and the character pressed. .PP Depending on the cursor type selected the last two arguments might also be defined and these give a reference position. For instance if the cursor is selected to be \f(CW\*(C`Rectangle\*(C'\fR then the reference position gives one of the corners of the rectangle and \f(CW$x\fR and \f(CW$y\fR the diagonally opposite one. .PP Options recognised: .IP "XRef, YRef" 4 .IX Item "XRef, YRef" The reference position to be used .IP "Type" 4 .IX Item "Type" The type of cursor. This can be selected using a number between 0 and 7 as in \s-1PGPLOT,\s0 or alternatively you can specify these as, \f(CW\*(C`Default\*(C'\fR (0), \&\f(CW\*(C`RadialLine\*(C'\fR (1), \f(CW\*(C`Rectangle\*(C'\fR (2), \f(CW\*(C`TwoHorizontalLines\*(C'\fR (3), \&\f(CW\*(C`TwoVerticalLines\*(C'\fR (4), \f(CW\*(C`HorizontalLine\*(C'\fR (5), \f(CW\*(C`VerticalLine\*(C'\fR (6) and \f(CW\*(C`CrossHair\*(C'\fR (7) respectively. The default cursor is just the normal mouse cursor. .Sp For the \f(CW\*(C`RadialLine\*(C'\fR you \fImust\fR specify the reference point, whereas for the \f(CW\*(C`Two(Vertical|Horizontal)Lines\*(C'\fR cursor the X or Y reference point, respectively, must be specified. .PP To select a region on a plot, use the rectangle cursor: .PP .Vb 2 \& ($x, $y, $ch, $xref, $yref) = cursor({Type => \*(AqRectangle\*(Aq}); \& poly pdl($x, $xref, $xref, $x, $x), pdl($y, $y, $yref, $yref, $y); .Ve .PP To select a region of the X\-axis: .PP .Vb 2 \& ($x1, $y1, $ch) = cursor({Type => \*(AqVerticalLine\*(Aq}); \& ($x2, $y2, $ch) = cursor({Type => \*(AqTwoVerticalLines\*(Aq, XRef => $x1}); .Ve .SH "Internal routines" .IX Header "Internal routines" .SS "catch_signals" .IX Subsection "catch_signals" To prevent pgplot from doing a fandango on core, we have to block interrupts during \s-1PGPLOT\s0 calls. Specifically, \s-1INT\s0 needs to get caught. These internal routines provide a mechanism for that. .PP You simply bracket any \s-1PGPLOT\s0 calls with \f(CW\*(C`catch_signals\*(C'\fR: .PP .Vb 4 \& catch_signals { \& ... \& pgcube($n, $x\->get_dataref); \& }; .Ve .PP and the signal_catcher will queue up any signals (like \s-1INT\s0 \*(-- the control-C interrupt) until the end of the block. .SS "_open_new_window" .IX Subsection "_open_new_window" Open a new window. This sets the window \s-1ID,\s0 which is the one used when accessing a window later using \f(CW\*(C`pgslct\*(C'\fR. It also sets the window name to something easily remembered if it has not been set before. .SS "_setup_window" .IX Subsection "_setup_window" This routine sets up a new window with its shape and size. This is also where the size options are actually parsed. These are then forgotten (well, they are stored in \f(CW$self\fR\->{Options}) and the corresponding aspect ratio and window width is stored. See the discussion under \fBnew()\fR for the logic. .PP Finally the subpanels are set up using \f(CW\*(C`pgsubp\*(C'\fR and colours and linewidth are adjusted according to whether we have a hardcopy device or not. .SS "_status" .IX Subsection "_status" This routine checks \s-1PGPLOT\s0's status for the window. It returns \s-1OPEN\s0 if the window is open and \s-1CLOSED\s0 if it is closed. (Windows can be closed but still exist). .SS "_reopen" .IX Subsection "_reopen" This functions reopens a window. Since this is an internal function it does not have a lot of error-checking. Make sure the device is closed \fIbefore\fR calling this routine. .PP There is an unfortunate problem which pops up viz. that the window name cannot be changed at this point since we are offering that to the rest of the world. That might be sensible, but it means that the window name will not reflect the id of the window \- use \f(CW\*(C`id()\*(C'\fR for that (this is also why we do not call \f(CW\*(C`open_new_window\*(C'\fR ) .SS "_advance_panel" .IX Subsection "_advance_panel" This routine advances one plot panel, updating the CurrentPanel as well. If the advance will proceed past the page the page will be erased. Also note that when you advance one panel the hold value will be changed. .SS "_check_move_or_erase" .IX Subsection "_check_move_or_erase" This routine is a utility routine which checks if we need to move panel, and if so will do this. It also checks if it is necessary to advance panels, and whether they need to be erased. .SS "_broadcast_options" .IX Subsection "_broadcast_options" This function is a cludgy utility function that expands an options hash to an array of hashes looping over options. This is mainly of use for \&\*(L"broadcasted\*(R" interfaces to standard plotting routines. .SS "options" .IX Subsection "options" Access the options used when \fIoriginally\fR opening the window. At the moment this is not updated when the window is changed later. .SS "id" .IX Subsection "id" Access the window \s-1ID\s0 that \s-1PGPLOT\s0 uses for the present window. .SS "device" .IX Subsection "device" This function returns the device type of the present window. .SS "name" .IX Subsection "name" Accessor to set and examine the name of a window. .SS "focus" .IX Subsection "focus" Set focus for subsequent \s-1PGPLOT\s0 commands to this window. .SS "info" .IX Subsection "info" Get general information about the \s-1PGPLOT\s0 environment. .PP .Vb 1 \& @ans = $self\->info( @item ); .Ve .PP The valid values of \f(CW@item\fR are as below, where case is not important: .PP .Vb 10 \& VERSION \- What PGPLOT version is in use. \& STATE \- The status of the output device, this is returns \*(AqOPEN\*(Aq. \& if the device is open and \*(AqCLOSED\*(Aq otherwise. \& USER \- The username of the owner of the spawning program. \& NOW \- The current date and time in the format \& \*(Aqdd\-MMM\-yyyy hh:mm\*(Aq. Most people are likely to use Perl \& functions instead. \& DEVICE * \- The current PGPLOT device or file, see also device(). \& FILE * \- The filename for the current device. \& TYPE * \- And the device type for the current device. \& DEV/TYPE * \- This combines DEVICE and TYPE in a form that can be used \& as input to new. \& HARDCOPY * \- This is flag which is set to \*(AqYES\*(Aq if the current device is \& a hardcopy device and \*(AqNO\*(Aq otherwise. \& TERMINAL * \- This flag is set to \*(AqYES\*(Aq if the current device is the \& user\*(Aqs terminal and \*(AqNO\*(Aq otherwise. \& CURSOR * \- A flag (\*(AqYES\*(Aq or \*(AqNO\*(Aq) to inform whether the current device \& has a cursor. .Ve .PP Those items marced with a \f(CW\*(C`*\*(C'\fR only return a valid answer if the window is open. A question mark (\f(CW\*(C`?\*(C'\fR) is returned if the item is not recognised or the information is not available. .SS "_extract_hash" .IX Subsection "_extract_hash" This routine takes and array and returns the first hash reference found as well as those elements that are \fInot\fR hashes. Note the latter point because all other references to hashes in the array will be lost. .SS "_parse_unit" .IX Subsection "_parse_unit" Convert a unit string or number into a PGPLOT-certified length unit specification, or return undef if it won't go. .SS "_parse_options" .IX Subsection "_parse_options" This is a convenience routine for parsing a set of options. It returns both the full set of options and those that the user has set. .SS "_save_status" .IX Subsection "_save_status" Saves the \s-1PGPLOT\s0 state so that changes to settings can be made and then the present state restored by \f(CW\*(C`_restore_status\*(C'\fR. .SS "_restore_status" .IX Subsection "_restore_status" Restore the \s-1PGPLOT\s0 state. See \*(L"_save_status\*(R". .SS "_checkarg" .IX Subsection "_checkarg" This routine checks and optionally alters the arguments given to it. .SS "_set_colour" .IX Subsection "_set_colour" This is an internal routine that encapsulates all the nastiness of setting colours depending on the different \s-1PGPLOT\s0 colour models (although \&\s-1HLS\s0 is not supported). .PP The routine works in the following way: .IP "\(bu" 8 At initialisation of the plot device the work colour index is set to 16. The work index is the index the routine will modify unless the user has specified something else. .IP "\(bu" 8 The routine should be used after standard interpretation and synonym matching has been used. So if the colour is given as input is an integer that colour index is used. .IP "\(bu" 8 If the colour is a reference the routine checks whether it is an \&\f(CW\*(C`ARRAY\*(C'\fR or a \f(CW\*(C`PDL\*(C'\fR reference. If it is not an error message is given. If it is a \f(CW\*(C`PDL\*(C'\fR reference it will be converted to an array ref. .IP "\(bu" 8 If the array has four elements the first element is interpreted as the colour index to modify and this overrules the setting for the work index used internally. Otherwise the work index is used and incremented until the maximum number of colours for the output device is reached (as indicated by \f(CW\*(C`pgqcol\*(C'\fR). Should you wish to change that you need to read the \s-1PGPLOT\s0 documentation \- it is somewhat device dependent. .IP "\(bu" 8 When the array has been recognised the R,G and B colours of the user-set index or work index is set using the \f(CW\*(C`pgscr\*(C'\fR command and we are finished. .IP "\(bu" 8 If the input colour instead is a string we try to set the colour using the \s-1PGPLOT\s0 routine \f(CW\*(C`pgscrn\*(C'\fR with no other error-checking. This should be ok, as that routine returns a rather sensible error-message. .SS "_standard_options_parser" .IX Subsection "_standard_options_parser" This internal routine is the default routine for parsing options. This routine deals with a subset of options that most routines will accept. .SS "_image_xyrange" .IX Subsection "_image_xyrange" Given a \s-1PGPLOT\s0 tr matrix and an image size, calculate the data world coordinates over which the image ranges. This is used in \*(L"imag\*(R" and \*(L"cont\*(R". It keeps track of the required half-pixel offset to display images properly \*(-- eg feeding in no tr matrix at all, nx=20, and ny=20 will will return (\-0.5,19.5,\-0.5,19.5). It also checks the options hash for XRange/YRange specifications and, if they are present, it overrides the appropriate output with the exact ranges in those fields. .SS "_FITS_tr" .IX Subsection "_FITS_tr" Given a \s-1FITS\s0 image, return the \s-1PGPLOT\s0 transformation matrix to convert pixel coordinates to scientific coordinates. Used by \&\*(L"fits_imag\*(R", \*(L"fits_rgbi\*(R", and \&\*(L"fits_cont\*(R", but may come in handy for other methods. .PP .Vb 2 \& my $tr = _FITS_tr( $win, $img ); \& my $tr = _FITS_tr( $win, $img, $opts ); .Ve .PP The return value (\f(CW$tr\fR in the examples above) is the same as returned by the \fBtransform()\fR routine, with values set up to convert the pixel to scientific coordinate values for the two-dimensional image \f(CW$img\fR. The \f(CW$opts\fR argument is optional and should be a \s-1HASH\s0 reference; currently it only understands one key (any others are ignored): .PP .Vb 1 \& WCS => undef (default), "", or "A" to "Z" .Ve .PP Both the key name and value are case insensitive. If left as \f(CW\*(C`undef\*(C'\fR or \f(CW""\fR then the primary coordinate mapping from the header is used, otherwise use the additional \s-1WCS\s0 mapping given by the appropriate letter. We make \fBno\fR checks that the given mapping is available; the routine falls back to the unit mapping if the specified system is not available. .PP The \s-1WCS\s0 option has only been tested on images from the Chandra X\-ray satellite () created by the \s-1CIAO\s0 software package (), for which you should set \f(CW\*(C`WCS => "P"\*(C'\fR to use the \f(CW\*(C`PHYSICAL\*(C'\fR coordinate system. .PP See for further information on the Representation of World Coordinate Systems in \s-1FITS.\s0 .SH "INTERNAL" .IX Header "INTERNAL" The coding tries to follow reasonable standards, so that all functions starting with an underscore should be considered as internal and should not be called from outside the package. In addition most routines have a set of options. These are encapsulated and are not accessible outside the routine. This is to avoid collisions between different variables. .SH "AUTHOR" .IX Header "AUTHOR" Karl Glazebrook [kgb@aaoepp.aao.gov.au] modified by Jarle Brinchmann (jarle@astro.ox.ac.uk) who is also responsible for the \s-1OO\s0 interface, docs mangled by Tuomas J. Lukka (lukka@fas.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz). Further contributions and bugfixes from Kaj Wiik, Doug Burke, Craig DeForest, and many others. .PP All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file \s-1COPYING\s0 in the \s-1PDL\s0 distribution. If this file is separated from the \s-1PDL\s0 distribution, the copyright notice should be included in the file.