home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #7 / amigamamagazinepolishissue1998.iso / varia / povray3 / povray3_060 / utils / netpbm.intro next >
Text File  |  1997-12-12  |  11KB  |  242 lines
  1.         NETPBM Image conversion and processing package
  2.                     Amiga information
  3.  
  4.  
  5. Binaries
  6. --------
  7. Binaries are available at ftp.informatik.uni-oldenburg.de [134.106.1.9] in
  8. /pub/netpbm/amiga, or on all Aminet sites in /pub/aminet/gfx/pbm.
  9. The full distribution consists of these archives:
  10.     texts.lha     REQ   textfiles, miscellaneous stuff
  11.     manuals.lha   REQ   formatted Unix manuals
  12.     mergedbin.lha REQ*  merged binaries
  13.     pbmbin.lha    REQ*  PBM binaries, for B&W images
  14.     pgmbin.lha    REQ*  PGM binaries, for greyscale images
  15.     ppmbin1.lha   REQ*  PPM binaries #1, for color images
  16.     ppmbin2.lha   REQ*  PPM binaries #2, for color images
  17.     pnmbin.lha    REQ*  PNM binaries, tools and special converters
  18.     scripts.lha   OPT   Unix shell scripts
  19.     source1.lha   DEV   source: tools and main libraries
  20.     source2.lha   DEV   source: TIFF library, Unix nroff manuals, VMS stuff
  21.     dicelibs.lha  DEV   compiled link libraries, for DICE
  22. REQ = required, OPT = optional, DEV = only useful for programmers
  23. *: You need either all the p?mbin archives, or just the mergedbin archive.
  24.    See the section "Merged binaries vs Separate binaries" for an explanation.
  25.  
  26.  
  27. What is NETPBM?
  28. ---------------
  29. NETPBM is a revised version of the PBMplus package, containing corrections
  30. and enhancements to the 10dec91 version of PBMplus. It is not "official" in
  31. the sense of being released by the original author, but the idea of a net
  32. supported version has been approved by him.
  33.  
  34. NETPBM is a collection of tools which do the following:
  35.   1. Import - read images in popular formats and convert to one of the
  36.      internal PBM formats.
  37.   2. Image processing - manipulate the image data to produce many effects
  38.      including scaling, contrast and gamma adjustment, edge detection, etc.
  39.   3. Export - write images in popular formats for use with other software.
  40.  
  41. NETPBM uses three intermediate formats:
  42.  
  43.     PBM = `portable bitmap'   (black&white)
  44.     PGM = `portable gray map' (greyscale, usually 8bit)
  45.     PPM = `portable pix map'  (color, usually 24bit)
  46.  
  47. The formats are upward compatible, PGM programs can read both PBM and PGM and
  48. write PGM, PPM programs can read all three and write PPM.  There are also PNM
  49. programs (PNM = `portable anymap'), these work on all three formats. The
  50. difference between PPM and PNM programs is that PPM programs always write PPM,
  51. but PNM programs can write any of the three formats (usually they write the
  52. same format as they got as input).  There is no PNM format!
  53.  
  54. The great advantage of using intermediate formats is that for a conversion
  55. between N formats only 2*N converters are needed instead of N^2; and if yet
  56. another graphic format appears, all that is needed are the newtop?m and
  57. p?mtonew filters, and you are immediately able to convert the new format to
  58. and from any other old format. The disadvantage is that two commands are
  59. needed to convert an image:
  60.     giftoppm mypic.gif >mypic.ppm
  61.     ppmtoilbm -hamif mypic.ppm >mypic.iff
  62. or on Unix-like shells:   giftoppm mypic.gif | ppmtoilbm > mypic.iff
  63.  
  64. Another disadvantage is that the intermediate formats are very simple and
  65. therefore the files get quite big, for example a 1024x768 PPM picture needs
  66. 1024*768*3 bytes = 2.25MB.
  67.  
  68. NETPBM also includes a lot of tools that manipulate the intermediate formats
  69. in some way: scaling, rotating, reducing the number of colors and more.  For
  70. example, to convert a GIF of any size to a 320*200 IFF-ILBM you could do this:
  71.     giftoppm mypic.gif >mypic.ppm
  72.     pnmscale -xysize 320 200 mypic.ppm >mypic.ppm2
  73.     ppmtoilbm -hamif mypic.ppm2 >mypic.iff
  74. or  giftoppm mypic.gif | pnmscale -xysize 320 200 | ppmtoilbm -hamif >mypic.iff
  75.  
  76. If you are not using an Unix-like shell, you can use the PIPE: handler to avoid
  77. using temporary files:
  78.     run giftoppm mypic.gif >pipe:1
  79.     run pnmscale -xysize 320 200 <pipe:1 >pipe:2
  80.     run ppmqvga <pipe:2 >pipe:3
  81.     ppmtoilbm -aga <pipe:3 >mypic.iff
  82.  
  83.  
  84. Requirements
  85. ------------
  86. * OS 2.04 or higher, or 1.3 with disk-based mathieeesingbas/mathieeesingtrans
  87.   libraries (available from C=).
  88. * mathtrans, mathieeedoubbas and mathieeedoubtrans libraries in LIBS:
  89.  
  90. A hard disk, a fast CPU, and lots of memory are recommended.  It will work on
  91. 68000's if you have sufficient memory; on machines with 020+MMU, non-EC 030,
  92. or non-EC 040, a virtual memory program like GigaMem will be useful if you are
  93. processing large images.
  94.  
  95. A full binary installation takes 1MB of HD space for merged binaries, 3MB for
  96. separate binaries (see below for an explanation).   Source (not including
  97. libtiff source, unix nroff manuals and the vms subdir) takes another 3MB.
  98.  
  99. There is no special 68020/881 binary distribution. The FPU is already used by
  100. the math libraries, and most programs are I/O-bound instead of CPU-bound.
  101.  
  102.  
  103. Merged binaries vs Separate binaries
  104. ------------------------------------
  105. Netpbm consists of more than 130 programs, each being stand-alone and not
  106. depending on the other programs.  This means a lot of disk space is wasted,
  107. since all programs use the same routines for reading, writing, allocation
  108. etc., and the code for these routines has to be in every single program.
  109. To avoid this, the programs can be merged into a single huge executable
  110. (actually four of them) and the individual programs are just hardlinks to
  111. this binary.  Both methods have advantages and disadvantages:
  112.  
  113. Separate binaries:
  114.   + executables can be individually tuned for maximum performance (register
  115.     args and small data model are used whenever possible).
  116.   + most executables are "pure" and can be made resident
  117.   - full installation takes MUCH more disk space (3MB)
  118. Merged binaries:
  119.   + only 4 executables and a bunch of links. Requires only 1MB of disk space
  120.     for a full installation.
  121.   - executables are slower, since all have to be compiled with stack-args and
  122.     large data model
  123.   - executables are huge and require more RAM to execute. This will be fixed
  124.     in the future by using overlays.
  125.  
  126. Why no shared library?  Its just too much work. If you think your life depends
  127. on having a pbm.library, go ahead and create it... or pay me for a month or two
  128. of full-time work, and I'm doing it :-)
  129.  
  130.  
  131. Installation
  132. ------------
  133. Separate binaries:
  134.   You need the following archives: pbmbin, pgmbin, ppmbin1, ppmbin2, pnmbin.
  135.   Extract the programs that you need from the archives and copy them to a
  136.   directory in your search path.
  137.  
  138. Merged binaries:
  139.   You only need the mergedbin archive.  Extract the four p?mmerge programs and
  140.   copy them to a directory in your search path.  Then CD to this directoy and
  141.   execute the "link_merged" script.  This generates all the hardlinks.
  142.  
  143. Links are not supported by 1.3, so if you are still running it, you have no
  144. choice but to use the separate binaries.  Some 2.x and 3.x filesystems have
  145. bugs with links that trashes the disk if the original file is deleted and a
  146. link still exists. A safe way is to use the merged binaries on these systems
  147. is to install them in their own directory, and if you decide one day to de-
  148. install them do it in this way:
  149.     delete ~(#?merge)
  150.     delete #?
  151.  
  152. X11 color names file: Some programs (for example pgmtoppm and ppmmake) can use
  153. a color names file, so you can specify colors by names instead of RGB values.
  154. An example color names file is included in the texts archives, as "RGB.txt".
  155. Just copy the file to a convenient place (S: is a good choice) and set the
  156. environment variable "RGBDEF" to the full path and name of this file:
  157.   setenv RGBDEF "s:RGB.txt"
  158.  
  159. Unix shell scripts: I didn't bother to convert the scripts to AmigaDOS-scripts
  160. (it's almost impossible anyway).  If you want to run them, use a Bourne-shell
  161. or Csh clone.
  162.  
  163. Stack size: Don't worry about it.  The programs automatically allocate a
  164. larger stack if they need more.
  165.  
  166.  
  167. Memory usage
  168. ------------
  169. You can control the way how the programs allocate their memory with the
  170. environment variable "PBMMEM".  The following keywords are used:
  171.  
  172.   fast
  173.     The programs will not try to allocate chipmem if they run out of fastmem.
  174.     If this keyword is not used, then the programs will allocate both fast-
  175.     and chipmem (fastmem first).
  176.  
  177.   pool
  178.   pool=<n>
  179.     With this keyword, the programs use memory pools. This is faster and
  180.     avoids run-time memory fragmentation, but unfortunately crashes if used
  181.     with GigaMem.  Note that OS 3.x is *NOT* required, it works under 2.x
  182.     (tested on 2.1) and probably even under 1.3 (not tested).  The optional
  183.     number selects the size of the pools, the default being 32K.  If this
  184.     keyword is not used, all allocations are done with normal AllocMem()
  185.     calls.  This should work on all systems and with virtual memory programs
  186.     like GigaMem.
  187.  
  188.   max=<n>
  189.     The maximum memory a program allocates.  This does not include the memory
  190.     used for the code, data and stack segments.  The default value (if this
  191.     keyword is not used) is "unlimited" (2GB, to be precise).
  192.  
  193. Multiple keywords are delimited by whitespace or commas.   Numbers can be in
  194. decimal, hex (prefix "0x") or octal (prefix "0") and can be given in bytes,
  195. Kbytes (suffix "k") or megabytes (suffix "m").
  196.  
  197. Example:    setenv PBMMEM "pool=64k,fast,max=2M"
  198.     Selects allocation via memory pools, fast memory only, and sets the
  199.     poolsize to 64KB and the maximum memory usage to 2MB.
  200.  
  201.  
  202. Misc info
  203. ---------
  204. NETPBM does not include converters for JPEG, but the freely distributable
  205. programs "djpeg" and "cjpeg" can convert JPEG to and from P?M.  You can get
  206. them from Aminet:/pub/aminet/gfx/conv, look for an archive called "jpegV?.lha"
  207. or "AmigaJPEG?.lha" or something similar.
  208.  
  209. The hpcdtoppm included in NETPBM converter is an older version, an up-to-date
  210. version is available on Aminet:/pub/aminet/gfx/pbm, archive "hpcdtoppm*.lha".
  211.  
  212. All programs have two hidden options, "-version" and "-quiet".  The first does
  213. the obvious: it prints version and configuration information of the program.
  214. The other suppresses all messages from the program (unfortunately, some
  215. programs ignore this option).  Most programs print usage information if a "-?"
  216. option is given.
  217.  
  218.  
  219. Support
  220. -------
  221. Your can reach me via
  222.   E-mail:
  223.     Ingo.Wilken@informatik.uni-oldenburg.de
  224.   IRC:
  225.     Nobody  (usually on channel "#amigager")
  226.   Carrier pigeon and other ancient communication channels:
  227.     Ingo Wilken
  228.     Bloherfelder Str. 72
  229.     26129 Oldenburg
  230.     W-Germany
  231.  
  232. For bug reports, please describe exactly what you were doing, what went wrong
  233. (guru number?) what OS version you are using, your machine configuration, and
  234. everything else that could be important.  If possible, provide the following:
  235.     * "enforcer" & "mungwall" output
  236.     * "showconfig" output
  237.     * a sample image that triggers the bug (unless it appears with any image)
  238.     * the output of running the NETPBM-program with the -version option
  239. Also, make sure that it's really the NETPBM-program thats causing the problems,
  240. not some background-utility playing corewar.
  241.  
  242.