.\" 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 "IIS 3pm"
.TH IIS 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::IIS \- Display PDL images on IIS devices (saoimage/ximtool)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use PDL::Graphics::IIS;
\& saoimage ( \-geometry => \*(Aq800x800\*(Aq );
\& iis rvals(100,100);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides an interface to any image display 'device' which support the
\&'\s-1IIS\s0 protocol' \- viz the SAOimage and Ximtool X\-windows programs, the
old SunView imtool program and presumably even the original \s-1IIS CRT\s0 itself
if they aren't all in museums!
.PP
These programs should be familiar to astronomers \- they are used by
the common \s-1IRAF\s0 system. The programs and their \s-1HTML\s0 documentation
can be obtained from the following URLs:
.PP
.Vb 2
\& SAOimage: http://tdc\-www.harvard.edu/software/saoimage.html
\& Ximtool:  http://iraf.noao.edu/iraf/web/projects/x11iraf/x11iraf.html
.Ve
.PP
Non-astronomers may find they quite nifty for displaying 2D data.
.PP
The Perl variable \f(CW$stdimage\fR is exported from the module and controls
the frame buffer configuration currently in use. The default value
is \f(CW\*(C`imt1024\*(C'\fR which specifies a \f(CW\*(C`1024x1024\*(C'\fR frame buffer. Other
values supported by the module are:
.PP
.Vb 1
\& imt512, imt800, imt1024, imt1600, imt2048, and imt4096.
.Ve
.PP
If you have a \fI\f(CI$HOME\fI/.imtoolrc\fR you can use it to specify other frame
buffer names and configurations in exactly the same way you can in
\&\s-1IRAF.\s0 Here is a sample file:
.PP
.Vb 10
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-snip\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& # Format:  configno nframes width height
\&  1  2  512  512         # imt1|imt512
\&  2  2  800  800         # imt2|imt800
\&  3  2 1024 1024         # imt3|imt1024
\&  4  1 1600 1600         # imt4|imt1600
\&  5  1 2048 2048         # imt5|imt2048
\&  6  1 4096 4096         # imt6|imt4096
\&  7  1 8192 8192         # imt7|imt8192
\&  8  1 1024 4096         # imt8|imt1x4
\&  9  2 1144  880         # imt9|imtfs    full screen (1152x900 minus frame)
\& 10  2 1144  764         # imt10|imtfs35 full screen at 35mm film aspect ratio
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-snip\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
.Ve
.PP
(Note: some versions of SAOimage may not even work if this file is not
present. If you get funny error messages about 'imtoolrc' try copying
the above to \fI\f(CI$HOME\fI/.imtoolrc\fR or \fI/usr/local/lib/imtoolrc\fR)
.PP
The Perl variable \f(CW$iisframe\fR is also exported from the module and controls
which display frame number to use in programs such as Ximtool which supports
multiple frames. This allows you to do useful things such as blink between
images.
.PP
The module communicates with the \s-1IIS\s0 device down \s-1FIFO\s0 pipes (special \s-1UNIX\s0
files) \- unlike \s-1IRAF\s0 this module does a pretty decent job of intelligently
guessing which file names to use for the pipes and will prompt for their
creating if absent. Also if SAOimage or Ximtool are started from within Perl
using the module this will guarantee correct file names!
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "iis"
.IX Subsection "iis"
Displays an image on a \s-1IIS\s0 device (e.g. SAOimage/Ximtool)
.PP
.Vb 4
\& iis $image, [ { MIN => $min, MAX => $max,
\&                 TITLE => \*(Aqpretty picture\*(Aq,
\&                 FRAME => 2 } ]
\& iis $image, [$min,$max]
.Ve
.PP
.Vb 1
\& (image(m,n),[\e%options]) or (image(m,n),[min(),max()])
.Ve
.PP
Displays image on a \s-1IIS\s0 device. If \f(CW\*(C`min()\*(C'\fR or \f(CW\*(C`max()\*(C'\fR are omitted they
are autoscaled. A good demonstration of \s-1PDL\s0 broadcasting can be had
by giving \f(CW\*(C`iis()\*(C'\fR a data *cube* \- \f(CW\*(C`iis()\*(C'\fR will be repeatedly called
for each plane of the cube resulting in a poor man's movie!
.PP
If supplied, \f(CW\*(C`TITLE\*(C'\fR is used to label the frame, if no title is
supplied, either the \f(CW\*(C`OBJECT\*(C'\fR value stored in the image header or a
default string is used (the title is restricted to a maximum
length of 32 characters).
.PP
To specify which frame to draw to, either use
the package variable \f(CW$iisframe\fR, or the \f(CW\*(C`FRAME\*(C'\fR option.
.SS "iiscur"
.IX Subsection "iiscur"
Return cursor position from an \s-1IIS\s0 device (e.g. SAOimage/Ximtool)
.PP
.Vb 1
\& ($x,$y) = iiscur($ch)
.Ve
.PP
This function puts up an interactive cursor on the \s-1IIS\s0 device and returns
the \f(CW\*(C`($x,$y)\*(C'\fR position and the character typed (\f(CW$ch\fR)
by the user.
.SS "iiscirc"
.IX Subsection "iiscirc"
Draws a circle on a \s-1IIS\s0 device (e.g. SAOimage/Ximtool)
.PP
.Vb 1
\& (x(),y(),radius(),colour())
.Ve
.PP
.Vb 1
\& iiscirc $x, $y, [$radius, $colour]
.Ve
.PP
Draws circles on the \s-1IIS\s0 device with specified points and colours. Because
this module uses 
\&\s-1PDL::PP\s0 broadcasting you can supply lists of points via
1D arrays, etc.
.PP
An amusing \s-1PDL\s0 idiom is:
.PP
.Vb 1
\& pdl> iiscirc iiscur
.Ve
.PP
Note the colours are the same as \s-1IRAF,\s0 viz:
.PP
.Vb 10
\& 201 = cursor color (white)
\& 202 = black
\& 203 = white
\& 204 = red
\& 205 = green
\& 206 = blue
\& 207 = yellow
\& 208 = cyan
\& 209 = magenta
\& 210 = coral
\& 211 = maroon
\& 212 = orange
\& 213 = khaki
\& 214 = orchid
\& 215 = turquoise
\& 216 = violet
\& 217 = wheat
.Ve
.SS "saoimage"
.IX Subsection "saoimage"
Starts the SAOimage external program
.PP
.Vb 1
\& saoimage[(command line options)]
.Ve
.PP
Starts up the SAOimage external program. Default \s-1FIFO\s0 devices are chosen
so as to be compatible with other \s-1IIS\s0 module functions. If no suitable
FIFOs are found it will offer to create them.
.PP
e.g.:
.PP
.Vb 2
\& pdl> saoimage
\& pdl> saoimage( \-geometry => \*(Aq800x800\*(Aq )
.Ve
.SS "ximtool"
.IX Subsection "ximtool"
Starts the Ximtool external program
.PP
.Vb 1
\& ximtool[(command line options)]
.Ve
.PP
Starts up the Ximtool external program. Default \s-1FIFO\s0 devices are chosen
so as to be compatible with other \s-1IIS\s0 module functions. If no suitable
FIFOs are found it will offer to create them.
.PP
e.g.
.PP
.Vb 2
\& pdl> ximtool
\& pdl> ximtool (\-maxColors => 64)
.Ve
.SH "BUGS"
.IX Header "BUGS"
None known
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) Karl Glazebrook 1997.
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.