PAWSDisp 1.40 : 18 September 1990 - Markus Buchhorn What is PAWS ? ============== PAWS = Personal Astronomical WorkStation. PAWS is a terminal emulation program for Commodore Amigas. It runs on all models (A500/A1000/A2000/A2500 - and we have no reason to believe it shouldn't run on the A3000) It was written by Dr Ken J. Mighell, who is (at time of writing this) a Post Doc at Mount Stromlo Observatory, Canberra, Australia. The PAWS executable is freely distributable. The PAWS source and PAWS-Language documentation is available for (some quantity of money)- contact Ken at mighell@mso.anu.oz.au PAWS provides a three screen device: A VT100, A Tek4010 and an image display screen, (no particular emulation) programmable with Tek4010 commands. The VT100 is Dave Wecker's VT100 2.4. The Tek4010 is a fixed two-colour 640x400 screen. The Image display screen is 320x200 , 32 colours, 4 of which are used by the system, leaving 28 for the actual image. PAWS provides 3 colour tables you can choose from, swapping at any time you like, also flipping and rotating of the colour table is possible. PAWS is a programmable emulator. It uses the PAWS Language to move between screens, clear screens, display a row of pixel data, draw lines, etc. Much of this is based on TEK4010 codes. All data transfer is done over the serial line. This means that PAWS can be run over a modem. It uses a clever compression technique to send data over the serial line, and the Amiga decompresses this and displays it. This means that PAWS runs at quite a respectable rate over 9600 baud lines, and you can cope quite well with just 2400 baud. Unless you have Ethernet/etc., you'll be stepping up ! :-) Anybody can write programs in Fortran/C/Pascal/whatever that program PAWS, using the PAWS_LIB library. You can thus tailor your programs to do whatever you want. What is PAWSDisp ? ================== PAWSDisp provides a standard interface for PAWS image displays. It provides a large number of image manipulation/analysis features, together with a very flexible usage: The user provides the header program to read data in, and then calls PAWSDisp as outlined below. PAWS and PAWSDisp were written with Astronomy in mind. Hence, it provides features to speed up data reduction. For the Astronomers out there, we currently have headers for (1) FIGARO, (VAX and Sun) (2) Mike Cawson's GASP, (VAX) (3) IRAF (Sun) (4) Starlink BDF (VAX) (5) Diskfits (Sun) [Still to come: STSDAS, MIDAS .bdf, PANDORA .sad, NCSA .hdf, Poskanzer's PBM, anything else that comes along...?] But PAWSDisp is not just for Astronomers. Anybody with images on a mainframe that they want to look at can use PAWS. And not just images. If you have a scientific model, say, with three parameters: Put two of them as coordinates on a grid, and make the third one an intensity. Treat that as an image and display it/print it. This is a *very* effective way of presenting data/models. Installing and using PAWSDisp: ============================== Given that you have some image data, you need to write a small program to do the following: (If you have grabbed one of our headers you can skip this) Read your data (nx,ny) into a real*4 2D array, of size xlim,ylim. Note: You can't pass arrays by general reference in fortran, and redimension them within a subroutine. In something like FIGARO, you can cheat by using the swap space. Most other formats don't like that. You have to declare some array to start with (e.g. 1024x1024) then read your data into the top left hand corner of the array (e.g. 512x512). Hence, to avoid problems, you have to specify both array sizes, the size you declared it to be (xlim,ylim), and the size of the data frame within it (nx,ny). The name of the file is 'frame' which is used as the root for files generated by PAWSDisp (NB This can include the path! Take care!). You can define a PAL or NTSC display on the subroutine call. Hence: integer xlim,ylim,nx,ny real*4 image(xlim,ylim) character frame [...] CALL pawsdisp(image,xlim,ylim,nx,ny,frame,'PAL','ERASE') [...] end simple, really.... :-) (the 'ERASE' indicates the screen should be wiped when PAWSDisp first starts up) Installing PAWS/PAWSDisp ======================== (i) Ok,you've just unpacked the archive that you've just brought across on your mainframe. On the Suns you will have: PAWS.zuu PAWSDisp.for PAWS_lib_1.f PAWS_lib_2.c PAWSDisp.txt qio_lib.for qio_structure.inc On the VAX you will have the all of the above, except there is only one file for PAWS_LIB. (ii) Get the PAWS.zuu file onto your Amiga and unpack it (uudecode and zoo) This gives you the PAWS executable + icon and the vt100.init file. Note that the vt100.init file must be in the same directory as the PAWS executable is. (iii) to run the emulator, click on the icon..The first time you run it, *hit any key and read all the relevant bits*. [Note that some of it is a bit old. Some of it refers to the VAX-only version of PAWS. This is due to a HD crash that we won't go into..:-(. We'll put up a newer version soon, but just for the sake of comments..For a more up-to-date address, contact Ken at the address below] The next time you can avoid reading this by clicking the close gadget *once* (twice = quit :-) ) (iv-a) On the VAX: $ for PAWS_LIB $ for PAWSDisp $ for ! your program, or one of my headers.. $ link ,PAWSDisp.obj,paws_lib.obj (iv-b) On the Sun - sorry there's an extra step. I ported PAWSDisp from the VAX and so the source code needs one tweak... % f77cvt -evs PAWSDisp.for I could have done this for you, but the source code looks like *&^% after f77cvt, and I'm not going through it, just for aesthetic purposes..Sorry :-) % f77 -c PAWS_LIB_1.f % cc -c PAWS_LIB_2.c % f77 -c PAWSDisp.f % f77 -o .f PAWSDisp.o PAWS_LIB_1.o PAWS_LIB_2.o (v) before running the program, I suggest you set the logical PAWS_USER to be equal to your username. This logical is read by the program, and is printed on all PostScript output files. If you don't set it, it will a leave a blank there. Logical <=> environment variable under Unix. i.e On the VAX you type: $ define PAWS_USER Markus or on the Sun/SPARC: % setenv PAWS_USER Markus (vi) Run your program ! Below is an extended description of what all the key commands do. Some are PAWS commands, executed by PAWS on the Amiga, the rest are PAWSDisp commands, acted on by your program on the mainframe. (vii) Enjoy ! (I hope...:-) ) Problems/Bugs/etc. ================== One thing that can go wrong is that sometimes a glitch comes down the line, which throws PAWS out of kilter. This is usually noticeable by the displaying stopping, a line gets shunted too far right, the cursor reports some strange coordinates, or the cursor doesn't even appear. It can be due to glitches on the line, or the users typing a PAWSDisp command (+some PAWS) before the cursor is up. *WAIT UNTIL THE CURSOR IS UP BEFORE TYPING A COMMAND*. If you do get a glitch, try the following: -Q *once*, and if this doesn't fix it, then -X *once*. (c-Q is if the image stops, c-X is when the cursor misbehaves. If it's just a glitch in the display, you can redraw the display with 'N') If nothing comes up, get out of the program and start again. PAWS takes over the Amiga when an image is being displayed, and will complain heartily if you try to _start_ anything else while an image is coming over. This is for your safety (so Ken tells me..:-) ) Beyond that, there are no known Bugs in PAWSDisp..........:-) with a stress on the word `known'. Actually, that's not true. I have (just) found two bugs, which are annoying to some extent. I'd classify them as 'misfeatures' rather than bugs, I know what they are, it's just thinking of some way to get round them..They only hit you if you are working with very odd images - something with an aspect ratio of > 10:1 for example. Most people won't be bothered by this, but when you do....I am working to fix them a.s.a.p. but I have a rather hectic few weeks ahead of me, so it might take a while. I'd like PAWS/PAWSDisp to circulate a bit and see what people think of it. When I get a chance I'll fix them (one is almost fixed, but the dreaded flow-on bugs are now hitting me...) Glory only to anyone who can tell me what the bugs are, gratitude to those who fix them..:-) If you find a bug (i) tell me, or (ii) fix it, then tell me how. The reason I've given out the source to PAWSDisp is mani-fold: (1) It makes it easily transportable to anything else you might have and we don't. *ALL SYSTEM DEPENDENCIES ARE IN PAWS_LIB!* If you want to port this to something we haven't tried (we have done Suns, SPARCS and VAXes/VMS) then you'll have to figure out the dependencies for that machine. Ken will try to help you as much as he can, if you need it, but....Getting this onto the Suns was fun already. If you do port it succesfully, tell Ken or myself. We'd appreciate a copy of the new PAWS_LIB...:-) (2) Anybody with spare time could've written it. It's simple in some places, fiddly in others. I've learnt about PostScript, TEK codes and how to automatically pick 'proper' tick-spacings for plots, plus a few other things I'd never thought about. Feel free to use any of the algorithms in your own programs. (3) You mightn't want somethings I have put in, or want things I haven't. You'll see in the code something called `usrfns()' This gives you an example of how to hook in more code of your own. It's called with the key. Do what you want with it...My idea was to make usrfns a subroutine, which then offers a menu of more functions, so that -1 calls one thing, -2 another, etc. [There are only three keys left in the alphabet I haven't used yet] (4) If someone finds a bug, or a way of enhancing it, they can try it out. If you do either, let me know Please! If I like it, I'll put it in my version. ============================================================================ A word or two from my lawyer... PAWSDisp is freely distributable. Do what you want with it. HOWEVER, there are some conditions on this: (i) If you make changes to the code, ANY AT ALL!, then you can no longer call the program PAWSDisp. This is to avoid people hassling me about bugs someone else put in. Like I said above: if you make a good change, tell me and I might put it into the PAWSDisp distribution. (ii) All the files in the above manifest must be left together. PAWSDisp is useless without PAWS, but PAWS can run by itself (see latter condition). Leave my name attached to the program. PAWS is separately distributable. (iii) I make no guarantee AT ALL that the numbers that come out of PAWSDisp are correct. I accept no responsibility for any errors that may arise if you assume that all measurements are perfect, that the graph axes are exact, etc. (I have tried to make them right though - I'm reducing my data too you know!) *The user assumes all responsibility for interpretation of PAWSDisp output.* (iv) I accept no responsibility for any damage caused by PAWSDisp. Note that you are passing the actual data to PAWSDisp. If you modify PAWSDisp to modify your image (pixel cleans for example) that will be returned to your main program. That is the way I wanted it to be ! At this stage (v1.40) there is no image data manipulation that I know of. Use this at your own risk. (v) PAWS is a separate product with its own rules regarding distribution, liability, etc. The rules of PAWSDisp do not implicitly apply to PAWS, the rules of PAWS do not implicitly apply to PAWSDisp. Please read the rules for the use of PAWS. These are contained within the PAWS program - On startup, hit any key.[Note the comments I made earlier about the age of some of the PAWS comments..] ============================================================================= Who can I complain/report bugs/report bug-fixes/send-money to ? :-) =============================================================== If it's about PAWSDisp: me: markus@mso.anu.oz.au If it's about PAWS: Ken Mighell: mighell@mso.anu.oz.au We both read the net NEWS, so a posting there may get our attention too... [comp.sys.amiga is your best bet..] Please feel free to get in touch with us for any help. We'll try to solve your problems as quickly as possible, but we hope that there won't be any.. -------------------------------------------------------------------------- Commands description -------------------------------------------------------------------------- The standard PAWS commands - all implemented (LUT=Look-up table) ALT 1 = go to vt100 window ALT ! = erase vt100 window ALT 2 = go to tek window ALT @ = erase tek window ALT 3 = go to image window ALT # = erase image window ALT F = flip color table ALT L = change color table ALT R = toggle LUT rotation ALT W = display color table ALT T = toggle window title PAWSDisp commands. Note that (except where given) most of these commands are case-insensitive. Any keystroke not listed here will just measure the data value wherever the cursor currently is. (I recommend using the space-bar for this.) DO NOT use the numeric keypad or Function keys ! ?-/ = Type the help menu Q = Quit '?' or '/' displays an abbreviated form of this information. Q quits from PAWSDisp when on the image display, and quits from the tek (spectrum) screen back to the image screen. C = Clip LUT F = Fold LUT You can clip the LUT, thus getting 'burnt-out' regions in an image (like in a photograph), or you can fold the LUT, with a folding length of hi_cut-lo_cut which means you can stretch the image display's effective dynamic range, by cycling back through the LUT from bottom to top an unlimited number of times. S = Set LUT limits R = Auto-set LUT Auto-set picks values = mean-1.5sigma, mean+2sigma T = Toggle data header L = Toggle log. scale The data header can be written on the display screen, or for neatness, on the VT100 scale. The log scale tries to produce a logarithmic display of the image - mainly useful for pictures with very high dynamic range. If the mean is negative, then the mean and std dev. are both set to -99 as a warning flag. This feature is very rarely useful... X = Flip image in X Y = Flip image in Y Self-evident what these do - NB only the display (and PS output) is flipped ! Z = Zoom onto image A = Display whole image Zooming is done in different ways. `Z' lets you handpick the corners of the box. (You can cancel a zoom by making the box only one line high or wide) d-D = Zoom out by 1-3 i-I = Zoom in by 1-3 These zoom in by some fixed amount. Upper case means to zoom three times faster than lower case. 'D' conserves the centre of the image, 'I' will zoom on where the cursor is. The zoom is additive, not multiplicative - if the zoom is 2, and you zoom in by 3, the zoom becomes 5, not 6. ('zoom' values indicate the amount of rebinning/stretching of pixels is done to an image. G = Zoom in or out by a factor of 2 If you hit 'G' followed by either 'i' or 'd' the zoom increases or decreases by a factor of 2 (as close as practical, anyway). If you hit any other key after 'G' it effectively cancels the 'G'. \ = List info of image N = Refresh the screen Info is things like size, zoom, scale, file-output, etc. 'N' is for all those times that someone sends you a message while displaying an image.... h-H = horizontal spectrum v-V = vertical spectrum These produce binned spectra of the image, sliced in x (h/H) or in y (v/V). The lower case command lets you use the cursor to indicate the box, upper case prompts you for pixel values. The Tektronix screen has three options: q-to quit,|-for PS output (see below) and any other key will measure the point, with the output going to the VT100 screen. If you specify the box only a single pixel wide/tall it will cancel the slice. | = Screen -> PostScript '|' (the UNIX pipe symbol) will produce a file of the image you can print on laserwriters. It only contains that part of the image that is currently on screen, in the same orientation, same greyscale (+/- laserwriter quality). Also includes the icon (if up) along with the 'you are here' box, and writes up a header line, plus any comments you might like to add. The same command given on the Tektronix (spectrum) display will produce a PostScript file of the plot. It allows you to add your own labels for the axes and the main label, in addition to the information header. It's fairly simple PS (witness who wrote it :-) ) so if you want to rearrange stuff afterwards, change labels, etc., it's very easy. Note that (i) The plot is redrawn on the screen as the file is written, and (ii) the labels are mainly only for the TPS file, not the screen plot - they won't all appear there. W = Write points to file 'W' opens a file for points measured, giving, x,y,z and which key was hit (ASCII value) P = pan / finder chart O = set panscreen LUT Produces an iconic form of the image, indicating current screen. If you select a point *on* the icon, that becomes the new center - shifts the image to there, while conserving the zoom. This allows you to move around quickly, and doesn't need the PAWS super-bitmap feature - which needs a lot of memory.'P' again removes the panscreen (or tries to - if it doesn't go away, just redraw the screen).The greyscale on the panscreen is the default one it starts with, which is sometimes wrong - the 'O' command will let you set it interactively. B = histogram plot of pixel values Plots a histogram of pixel values inside a user-specified box. This is handy for quickly finding the mean/sdtdev of an image, or determining the 10%-90% levels of an image. This allows you to pick a grey-scale better sometimes than my values. U = change icon size For those of you with large image sizes: This lets you change the size of box in which the icon is drawn - but you have to allow for integer zooms - What you are setting is the *maximum* size an icon can be. E = expand the image in y For those of you with narrow images: It allows you to stretch the image in the y-direction, up to some value. If you just hit 'e' and , it will pick a nice default value for you. The icon stretch is picked and fixed by the program. If you don't like it....sorry. Note that y-stretching and zooming are somewhat overlapping. If you zoom on a stretched image, the stretch needs to be adjusted. I've picked a way of doing this automatically, which works best if you use the default stretch. ----------------------------------------------------------------------------- To Do Yet: - Allow arrays for conversion of pixel values to other values, e.g. wavelength scale, intensity scale... - Allow for batch-mode operation... - Arbitrary direction slices, with input slit width. - More ILASER-ish like output for the Postscript image output. (i.e. tickmarks.) - Flip the Tek(and TPS)-spectrum in x or y if the image itself is flipped. - Improve the label positioning on the Tek/TPS output - still kinda screwy now. - Suggestions ???? ======================== end of document ==================================