IIS(3pm)

✨ IIS(3pm) ✨ — no wait bestie, this is the PDL::Graphics::IIS page 💖

okay so. you know how manpages are usually giving "boring old man yells at terminal"? not this one. this one is about putting pictures on screens and it's genuinely so fun. sit down, grab a snack 🍓

---

NAME 💅

PDL::Graphics::IIS — Display PDL images on IIS devices (saoimage/ximtool)

like. it shows your PDL images on IIS devices. that's the whole vibe. 🦋

---

SYNOPSIS ✨

use PDL::Graphics::IIS;
saoimage ( -geometry => '800x800' );
iis rvals(100,100);

three lines. that's it. that's the whole entrance. iconic behavior honestly 👑

---

DESCRIPTION 🌸

So this module is basically the bestie-bridge between your PDL images and any image display "device" that speaks the 'IIS protocol' — which means the SAOimage and Ximtool X-windows programs, the old-school SunView imtool program, and lowkey probably even the original IIS CRT itself, assuming they're not all sitting in museums rn 💀

If you're an astronomer these programs are gonna feel like home — the common IRAF system uses them. The programs and their HTML docs live at these URLs:

 SAOimage: http://tdc-www.harvard.edu/software/saoimage.html
 Ximtool:  http://iraf.noao.edu/iraf/web/projects/x11iraf/x11iraf.html

And if you're not an astronomer? ngl you might still find these quite nifty for displaying 2D data. no gatekeeping here 🫶

---

the frame buffer situation 🎀

The Perl variable $stdimage gets exported from the module and it controls the frame buffer configuration currently in use. Default value is "imt1024", which specifies a "1024x1024" frame buffer. The other values this module supports are:

 imt512, imt800, imt1024, imt1600, imt2048, and imt4096.

If you've got a $HOME/.imtoolrc, you can use it to specify other frame buffer names and configurations in exactly the same way you can in IRAF. Here's a sample file:

-------------------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-------------------------

heads up bestie: some versions of SAOimage may not even work if this file isn't present. So if you get funny error messages about 'imtoolrc', try copying the above to $HOME/.imtoolrc or /usr/local/lib/imtoolrc. 🚨

---

frames & pipes 🦋

The Perl variable $iisframe is also exported from the module, and it controls which display frame number to use in programs like Ximtool that support multiple frames. This is the bit that lets you do useful things such as blink between images. so cool. so main character. 😭

The module talks to the IIS device down FIFO pipes (special UNIX files). And unlike IRAF, this module does a pretty decent job of intelligently guessing which file names to use for the pipes, and it'll prompt for their creating if they're absent. Also — if SAOimage or Ximtool are started from within Perl using the module, that guarantees correct file names! slay 💅

---

FUNCTIONS 🔥

iis

Displays an image on a IIS device (e.g. SAOimage/Ximtool)

iis $image, [ { MIN => $min, MAX => $max,
                TITLE => 'pretty picture',
                FRAME => 2 } ]
iis $image, [$min,$max]

(image(m,n),[\%options]) or (image(m,n),[min(),max()])

Displays image on a IIS device. If min() or max() are omitted they get autoscaled. And here's the fun part — a genuinely good demonstration of PDL broadcasting: hand iis() a data cube and iis() will be repeatedly called for each plane of the cube, giving you a poor man's movie! 🎬 obsessed.

If supplied, "TITLE" is used to label the frame. If no title is supplied, either the "OBJECT" value stored in the image header or a default string is used — and jsyk the title is restricted to a maximum length of 32 characters.

To specify which frame to draw to, either use the package variable $iisframe, or the "FRAME" option.

---

iiscur

Return cursor position from an IIS device (e.g. SAOimage/Ximtool)

($x,$y) = iiscur($ch)

This function puts up an interactive cursor on the IIS device and returns the "($x,$y)" position and the character typed ($ch) by the user. cute lil interactive moment 🎀

---

iiscirc

Draws a circle on a IIS device (e.g. SAOimage/Ximtool)

(x(),y(),radius(),colour())

iiscirc $x, $y, [$radius, $colour]

Draws circles on the IIS device with specified points and colours. Because this module uses PDL::PP broadcasting you can supply lists of points via 1D arrays, etc. 💫

An amusing PDL idiom is:

pdl> iiscirc iiscur

Note the colours are the same as IRAF, viz:

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

the whole palette?? served. 🌈

---

saoimage

Starts the SAOimage external program

saoimage[(command line options)]

Starts up the SAOimage external program. Default FIFO devices are chosen so as to be compatible with other IIS module functions. If no suitable FIFOs are found, it will offer to create them.

e.g.:

pdl> saoimage
pdl> saoimage( -geometry => '800x800' )

---

ximtool

Starts the Ximtool external program

ximtool[(command line options)]

Starts up the Ximtool external program. Default FIFO devices are chosen so as to be compatible with other IIS module functions. If no suitable FIFOs are found, it will offer to create them.

e.g.

pdl> ximtool
pdl> ximtool (-maxColors => 64)

---

BUGS 💀

None known

(not me being shocked a manpage BUGS section is this chill 😭 iconic honestly)

---

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 COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

---

okay that's the whole thing bestie, go make some pictures ✨

this little manual came to you from perl v5.38.2, dated 2024-04-10 — love that for us. mwah 💖🎀🦋