/* @(#)README 1.4 92/03/05 * * Popi v3.2.1 * * Popi was originally written by Gerard J. Holzmann - AT&T Bell Labs. * This version is based on the code in his Prentice Hall book, * "Beyond Photography - the digital darkroom," ISBN 0-13-074410-7, * which is copyright (c) 1988 by Bell Telephone Laboratories, Inc. * * Permission is given to distribute these extensions, as long as these * introductory messages are not removed, and no monies are exchanged. * * No responsibility is taken for any errors or inaccuracies inherent * either to the comments or the code of this program, but if reported * (see README file) then an attempt will be made to fix them. */ Popi - README - January 1992. --------------------------------------------------------------------------- CONTENTS: 1. What is Popi? 2. Getting started. 3. Popi history. 4. Popi image format. 5. Acknowledgements. --------------------------------------------------------------------------- 1. What is Popi? ---------------- Popi is a program that allows arbitrary transformations to be interactively applied to digital images. It is based on the program described in "Beyond Photography - The Digital Darkroom" by Gerald J. Holzmann. See the manual page for details of all the options available to you, plus examples of how to use them. The graphical interface to popi can be very simple, or enhanced for a particular graphics environment. [ IMPORTANT NOTE: the following graphics drivers worked correctly in the previous release of this software. They will mostly all need to be "ported" again. ] Graphical device drivers are currently included for: Amiga Works with Lattice C 5.04, but you'ld better have at least 2M of memory, or restrict yourself to small (128by128) images. Apollo Atari terminal Hewlett Packard Kermit terminal MGR NeWS Works with NeWS v1.1 and OpenWindows v1.0. NeXT Tested on a NeXT-Dimension system, works with NeXTstep 2.1. It uses a screen-depth of 32 bits and leaves dithering to the Display-Postscript system. It doesn't support :monochrome. PC Works with Turbo C, Microsoft C (including Quick C) and Mix Software's Power C. There is support for the common graphics cards (CGA, EGA, VGA, HGC) and additionally, the Turbo C graphics library routines can be used for non-standard cards if you have the appropriate .BGI file. SunView Works with SunOS v3.x and SunOS v4.x. X11 Works with X11R4 and X11R5. XView Needs the XView toolkit source distribution or Open Windows v1.0. null For those with no graphics screen, this enables you to just use one of the printer options. Output is available for: PostScript Epson printers. This code has been tested on various Sun equipment (3's, 4's and 386i's) using the SunView, MGR, X11, NeWS and XView drivers, a Sequent using the Atari driver and X11 with a Sigma Data X terminal, a MIPS using an NCD X terminal and an Apollo DN1000 with the X11 driver. Plus the kermit and PC version of various PC's. We'd be interested to hear what other machines you get it working on, so that we can keep this list up to date. ---------- The latest version of popi is available via anonymous ftp from two sites: nic.funet.fi [Finland] in the pub/graphics/programs/popi directory. Thanks to Juhana Kouhia for providing this service. wuarchive.wustl.edu [USA] in the graphics/graphics/popi directory. Thanks to George Kyriazis for providing this service. Pick the site nearest to you, and please try to restrict your connections to outside 9:00am - 5:00pm local time during weekdays. ---------- There is a mailing list for people interested in popi. It is: popi@Aus.Sun.COM To get added to the list, send a request to: popi-request@Aus.Sun.COM Early patches are sent to the mailing list, plus active discussion on ideas for enhancements to popi, plus interesting popi transformations. 2. Getting started. ------------------- Initially there is no Makefile file present in the popi source directory. You will need to copy Makefile.dist to Makefile, then adjust accordingly. You need to specify one of the following options to compile popi: make amiga - to make the Amiga version. make apollo - to make the Apollo version. make atari - to make the Atari version. make hp - to make the HP version. make ibmpc - to make the PC version. make kermit - to make the Kermit version. make mgr - to make the MGR version. make news - to make the NeWS version. make next - to make the NeXT version. make nulldev - to make the null device version. make sunview - to make the SunView version. make x11 - to make the X11 version. make xview - to make the XView version. This should then be followed by a "make install". You might need super-user permission to do this successfully. The manual pages describe how to use popi in detail, and include several examples. The Makefile compilation details are setup to default to compiling the SunView version of popi on a Sun4 running SunOS v4.1. Note that there are various compilation definitions that might need uncommenting if you are trying to compile and run it on any other machine or graphics environment or operating system. These are: AR - system library manipulation command. CC - name your favorite C compiler. CP - your system "copy" command. E - suffix (including the `.') for executable files. EXE - compiler option for specifying exectable name HASPOLL - uncomment if you have the poll(2) system call. INSTALL - the name of your install command (or : to install by hand). ISTACK - uncomment if an integer evaluation stack should be used. LIBS - specify any libraries needed. MGRHOME - MGR only: home directory of the MGR installation. MGRINCDIR - MGR only: location of the MGR include files. MGRPARAM - MGR only: used to pass $MGRHOME to MGR. NEWSFILE - NeWS only: location of the NeWS .ps file. NOSELECT - uncomment if your machine doesn't have the select() call. O - suffix used for object files. OCFLAGS - specify any flags to be used with your C compiler. OLDFLAGS - specify any extra flags to be passed to the linker. P - Dynix (Sequent) only: uncomment if you have a parallel make. PFLAGS - Dynix (Sequent) only: uncomment for parallel programming lib. PLIB - Dynix (Sequent) only: uncomment for parallel programming lib. RANLIB - system library manipulation command. RM - your system "remove" command. SELTYPE - uncomment for old select(2) calls. SYS - system type: -DBSD for BSD unix or -DSYSV for System V unix. SIGRET - uncomment if your signal function expects a void function. SUNFLOAT - uncomment if you have a Sun with a floating point co-processor. USE_BZERO - uncomment if your system has bzero instead of memset. X11R3 - uncomment if you are building the X11 version under X11R3. X11INCDIR - X11 only: location of the X11 #include files. X11LIBDIR - X11 only: location of the X11 libraries. XVIEWINCDIR - XView only: location of the XView #include files. XVIEWLIBDIR - XView only: location of the XView libraries. See the Makefile for a more detailed description of each of these definitions. If you need to make other changes in order to get popi to compile and run on your system, please let us know the details (see email addresses below), and we will try to include them into a future version. Note that the Makefile is very generic. Considerable speedups can be obtained by using different compile and link options, plus inline libraries. There is a TODO file included which lists current bugs, and the enhancements that will be added in the future. Here are some possible settings for a variety of machines. Please send additional machine settings to the address below, to be included in this section. From Adrian F Clark Sun386i, vanilla X11R4 - no significant changes to the Makefile. From Harry Langenbacher Sun 4/75 gx, SunOS v4.1.1, SunView - no significant changes to the Makefile. From Rainer Wieland Sun IPC, SunOS v4.1.1, X11R4 with twm, "make x11" with no changes to the Makefile. 3. Popi history. ---------------- This program was first released to aus.sources in July 1989 in conjunction with a competition held prior to this year's Australian Unix User's Group Conference and Exhibition. The best transformation of Dennis Ritchie's face (as judged by Dennis) was put on T-shirts that were given to each conference delegate. Bug-fixes, improvements and new drivers were garnered. A number of vendors had popi running at the exhibition. 4. Popi Image format. --------------------- Popi use the portable graymap file format for the grayscale images, and the portable pixmap file format for it's color images. These image formats are an integral part of the PBMPLUS extended portable bitmap toolkit distributed by Jef Poskanzer. PBMPLUS provides comprehensive format conversion and image manipulation capabilities. The latest version is always available via anonymous FTP as export.lcs.mit.edu:contrib/pbmplus*.tar.Z and ftp.ee.lbl.gov:pbmplus*.tar.Z. These routines (which have been isolated into libpbm.c and libpbm.h) are: Copyright (C) 1989 by Jef Poskanzer. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. If you have some image files in the old popi image format, they can be converted to pgm format by using the popitopgm filter. See the popi manual pages for more details. This version of popi uses error diffusion floyd-steinberg dithering for displaying the images on monochrome screens. The routines to do this were taken from the xloadimage package. These routines (which have been isolated into dither.c) are: Copyright 1989, 1990 Kirk L. Johnson Copyright 1989, 1990 Jim Frost and Steve Losen. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 5. Acknowledgements. -------------------- Special thanks go to: Stephen Frede for writing the previous version of the lexical parser. Byron Rakitzis for the basis of the popi yacc grammar, and the various associated routines (alloc.c, *gen.c, mk.c), plus the runtime assember generating routines, taken from his pico implementation. Russ Nelson for implementing various changes to this version to make it more efficient, particularly with the PC versions. Rich Morin for adding: * -c flag - color (RGB) calculation, display, and I/O (NTSC luma display on non-24-bit monitors) * -s flag, #signed - signed I/O * 24-bit monitor support under SunView * smallest unambiguous name recognition for special commands (eg, #r) * table-driven messages about special commands in #help * assorted bug fixes. Thanks go to: Mark Andrews and Andrew Nicholson for help with the NeWS driver; Peter Chubb for the Amiga work; Frank Crawford for the kermit terminal driver; Eric Haines for the HP driver. Kirk L. Johnson, Jim Frost and Steve Losen for developing the xloadimage package. Tim Lambert for the Apollo driver; Jef Poskanzer for developing the PBMPLUS package. John Pritchard and James Ashton for bug reports and fixes; Tim Roper for System V diffs. Stephan Wasserroth for (re)porting the NeXT driver, plus numerous improvements including a floating point evaluation stack. Also thanks to Tor Lillqvist for fixing up the X11 driver to work with an HP9000 Series 300 workstation (which incidentally fixes it to work on NCD terminals) and to Eric Haines for spotting several minor inefficiencies in the popi code. Also thanks to the following for various bug reports, fixes and suggestions for improvement: Rob Beukers, Tim Born, Thomas M. Breuel, Eli Chiprout, Adrian F. Clark, Ed Falk, Jorgen Gustafsson, Eric Haines, Thomas Heller, Steve Howell, Glenn Huxtable, Ling Kan, Harry Langenbacher, Thierry Leconte, Martin A. Leisner Dave Spensley, Chris Stenton, Rainer Wieland Suggestions for furthur improvement would be most welcome, plus bugs, comments. Please direction all suggestions, bugs, and comments to the address below. If you make any bug fixes changes or improvements please let me know so that I can add them to the main distribution. More device drivers are particularily welcome. Rich Burridge, DOMAIN: richb@Aus.Sun.COM PHONE: +61 2 413 2666 UUCP: ...!sun!sunaus!richb