summaryrefslogtreecommitdiff
path: root/graphics/sam2p/README
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/sam2p/README')
-rw-r--r--graphics/sam2p/README2822
1 files changed, 2822 insertions, 0 deletions
diff --git a/graphics/sam2p/README b/graphics/sam2p/README
new file mode 100644
index 0000000000..68dad7c848
--- /dev/null
+++ b/graphics/sam2p/README
@@ -0,0 +1,2822 @@
+-*- coding: UTF-8 -*-
+
+README for sam2p
+by pts@fazekas.hu
+at Sun Dec 30 19:30:17 CET 2001 -- Fri Mar 22 19:25:03 CET 2002
+Sat Apr 27 00:39:12 CEST 2002
+Wed Jul 3 01:20:40 CEST 2002
+Wed Feb 5 19:46:51 CET 2003
+grammatical corrections by Steve Turner at Mon Jan 10 00:53:46 CET 2005
+
+This is the README file for sam2p, a raster to PostScript/PDF image
+conversion program. This file contains a 5-minute turbo tutorial for new and
+impatient users (search for the phrase `Turbo tutorial' in your text editor).
+As of now, this README file is the only, and definitive, documentation of sam2p.
+
+sam2p is a UNIX command line utility written in C++ (C++98) that converts many
+raster (bitmap) image formats into Adobe PostScript or PDF files and several
+other formats. The images are not vectorized. sam2p gives full control to
+the user to specify standards-compliance, compression, and bit depths. In
+some cases sam2p can compress an image 100 times smaller than the PostScript
+output of many other common image converters. sam2p provides ZIP, RLE and
+LZW (de)compression filters even on Level1 PostScript devices.
+
+Send donations to the author of sam2p:
+https://flattr.com/submit/auto?user_id=pts&url=https://github.com/pts/sam2p
+
+Do you need sam2p?
+
+-- If you have a raster image (e.g. PNG, JPEG), and you need EPS or PDF output,
+ then sam2p is probably very useful for you, because it can generate small
+ EPS and PDF files quickly, outperforming many other
+ tools (such as ImageMagick's convert) in speed and output file size. For
+ EPS output files, the compatibility of sam2p is also better that of other
+ tools.
+-- If you use any of pdftex, pdflatex, luatex, lualatex, xetex or xelatex,
+ and you have your raster images as PNG and JPEG files, then you don't need
+ sam2p or any other raster image converter, because \includegraphics works
+ on PNG and JPEG files directly.
+-- If you want to make your JPEG files smaller, there are much better tools
+ than sam2p for that.
+-- If you want to make your PNG files smaller, you can use sam2p to convert
+ PNG to PNG, but with other tools (such as pngout, advpng and zopflipng)
+ you can get a better compression ratio at a cost of slower compression
+ speed.
+-- If you want to make your PDF files smaller, use pdfsizeopt
+ (https://github.com/pts/pdfsizeopt). pdfsizeopt uses sam2p and other
+ tools (such as jbig2) under the hood to make the raster images embedded
+ in the PDF files smaller.
+
+How small is the EPS output of sam2p?
+
+-- A testimonial from Grant Ingram, UK: Anyway this is just a quick note to say
+ thanks for writing the sam2p utility which I am using to create EPS figures
+ of photographs for my thesis -- it works very well producing image sizes
+ that are some 3% of the ones produced by ImageMagick.
+
+-- A testimonial from Tom Schneider, US:
+
+ -rw------- 1 toms delila 88628 Mar 3 17:38 prototype-small.eps
+ -rw------- 1 toms delila 7979299 Feb 24 12:25 prototype.eps
+
+ Good GRIEF you have written a nice program!!!! The file is 90 fold
+ smaller than the one from ImageMagick's convert.
+
+ That image that was 90x smaller had been bugging me because it was so
+ large that xdvi would strongly hesitate while I passed by the page.
+ Now it just has a minor delay, thanks to you.
+
+-- Results are not always that impressive. See the section
+ {sam2p vs convert in 2017} for more details.
+
+Benefits of sam2p:
+
+-- sam2p produces much smaller output.
+-- sam2p gives the user complete control over the data layout of the output
+ image. This includes Compression, SampleFormat and TransferEncoding.
+-- sam2p is fast.
+-- sam2p doesn't depend on external libraries. (But it does depend on external
+ programs for _reading_ JPEG, TIFF and PNG files.)
+-- sam2p supports the mainstream image formats of today without compromise.
+ sam2p has many file format fine-tuning features that are missing from
+ most other converter utilities. For example:
+ TIFF ZIP compression, TIFF LZW compression, TIFF
+ JPEG compression, transparent PNG files, BMP RLE-4 and RLE-8
+ compression, etc.
+-- sam2p supports all levels (versions) of the PostScript language and
+ output images have the smallest file size allowed by the LanguageLevel.
+-- PostScript ZIP, RLE and LZW compression is provided for _all_
+ LanguageLevels (!), even for PSL1 (which appeared in 1984). You can print
+ your ZIP-compressed images onto your ancient printer of the 1980s.
+-- sam2p supports all versions of PDF, and as with PostScript,
+ output images have the smallest file size allowed by the version.
+-- Output images of sam2p are always compliant to the standard selected by
+ the user.
+-- Output images of sam2p are real-world compatible, i.e the author has
+ tested them with many common image processing programs, for example:
+ Ghostscript, pdfTeX, xpdf, Acrobat Reader, The GIMP, ImageMagick, xv,
+ Acrobat Distiller, QuarkXPress, InDesign. The author has also tested
+ PostScript files on HP and OkiData printers.
+-- sam2p converts every pixel faithfully, preserving all the 24 RGB bits
+ intact. There is no quality or information loss unless you ask for it.
+-- sam2p uses only a minimal number of libraries. You don't have to install
+ 33Mb of ballast software to use sam2p. Image libraries (libtiff etc.) are
+ _not_ used, the math library is not used, libstdc++ is not used, zlib is
+ not used.
+
+Long-term limitations of sam2p:
+
+-- Only DeviceRGB color space, with the Indexed, Gray and RGB image types.
+-- Indexed images are limited to a maximum of 256 colors.
+-- Alpha channel and transparency supported only for Indexed images: only
+ one color may be transparent.
+-- The entire input image is read into memory. During operation both the
+ input and the output images may be held in memory.
+
+Many thanks to Steve Turner for reviewing and making corrections to this
+document.
+
+Status
+~~~~~~
+sam2p is production-ready software. It is available from:
+
+ https://github.com/pts/sam2p
+
+The documentation is incomplete, but -- together with the examples -- it is
+quite useful. Please have a look at the home page to find articles and more
+documentation (the PDF docs are much more eye-pleasing than this README).
+The source code contains valuable comments, but they may be hard to find
+unless you're deeply into developing sam2p.
+
+The author is developing sam2p in his free time. (He is studying and
+working in non-free time.)
+
+The imaging model is complete. Image output routines are stable and
+adequate. Reasonable defaults are provided for all command line options.
+sam2p can usually find the best SampleFormat automatically. There is
+an educated (but not perfect) default guess for the Compression.
+
+See subsection {OutputRule combinations} about all planned formats.
+
+Turbo tutorial
+~~~~~~~~~~~~~~
+Quick compilation instructions:
+
+1. Run: make
+ It also runs ./configure with the right defaults for you.
+2. Copy the `sam2p' executable to your $PATH, or invoke it as `./sam2p'.
+
+Quick try:
+
+-- ./sam2p examples/pts2.pbm try.eps
+-- ./sam2p examples/pts2.pbm try.pdf
+-- ./sam2p examples/pts2.pbm try.ps
+-- ./sam2p examples/pts2.pbm try.png
+-- ./sam2p examples/pts2.pbm try.tiff
+-- ./sam2p examples/pts2.pbm try.xpm
+-- ./sam2p examples/pts2.pbm try.bmp
+-- ./sam2p examples/pts2.pbm try.jpg
+
+A really short User's guide
+"""""""""""""""""""""""""""
+To convert an image, call:
+
+ ./sam2p <INPUT.IMG> <OUTPUT.IMG>
+ Example: ./sam2p examples/pts2.pbm try.eps
+
+To print an image as a full PostScript page, call:
+
+ ./sam2p [MARGIN-SPECS] <INPUT.IMG> ps: - | lpr
+ Example: ./sam2p -m:1cm examples/pts2.pbm ps: - | lpr
+
+To convert an image to be included as EPS (Encapsulated PostScript) into
+(La)TeX documents, call:
+
+ ./sam2p <INPUT.IMG> <OUTPUT.eps>
+ Example: ./sam2p examples/pts2.pbm test.eps
+ In file.tex: \usepackage{graphicx} ... \includegraphics{test}
+
+To convert an image to be included as PDF into pdf(La)TeX documents, call:
+
+ ./sam2p <INPUT.IMG> <OUTPUT.pdf>
+ Example: ./sam2p examples/pts2.pbm test.pdf
+ In file.tex: \usepackage{graphicx} ... \includegraphics{test}
+
+If you have a large image file (possibly originating from dumb software),
+you can reduce the image size and keep the same filename. (Please note that
+some meta-information may be lost using this method.) This operation is
+_DANGEROUS_ if you don't have a backup, because due to a software or
+hardware problem, sam2p might clobber time image file so the actual image
+gets lost. To overwrite a file in-place, call:
+
+ ./sam2p <INPUT-OUTPUT.IMG> --
+ Example: ./sam2p test.tiff --
+
+You may specify a compression method (or supply other command line options)
+to make a file even smaller, call:
+
+ ./sam2p [OPTIONS] <INPUT.IMG> <OUTPUT.IMG>
+ Example: ./sam2p -c:zip test.tiff test2.tiff
+
+See the detailed documentation of available command-line options elsewhere
+in this document. You may also read section {FAQ} for more information.
+
+Too see a list about the supported input and output image file formats, call:
+
+ ./sam2p
+
+Example output:
+
+ This is sam2p v0.39.
+ Available Loaders: JAI PNG JPEG TIFF PNM BMP GIF LBM XPM PCX TGA.
+ Available Appliers: XWD Meta Empty BMP PNG TIFF6 TIFF6-JAI JPEG-JAI JPEG PNM GIF89a XPM PSL1C PSL23+PDF PDF-JAI PSL2-JAI l1fa85g P-TrOpBb.
+ Usage: [...]
+
+The list of ``Available Loaders'' lists the input image file formats. All
+except for JAI are self-explanatory. JAI is JPEG-as-is, it means reading a
+JPEG file and writing back the exactly same image into an other JPEG variant,
+without quality loss.
+
+From the list of ``Available Appliers'' one can derive the supported output
+image file formats. XWD, BMP, PNG, TIFF6, JPEG, PNM, GIF89a and XPM are
+self-explanatory. TIFF6-JAI, JPEG-JAI, PDF-JAI and PSL2-JAI are JPEG
+variants into which JAI files (see above) can be saved. While the names of
+the remaining appliers may be quite cryptic to the beginner user; most of
+those appliers provide sam2p's excellent support for writing PS, EPS and
+PDF files.
+
+sam2p operation modes
+~~~~~~~~~~~~~~~~~~~~~
+sam2p is a command line utility (i.e, without a graphical user
+interface), so it can be used by composing a command line with the
+appropriate options and parameters, and launching it. See sections ``Turbo
+tutorial'' and ``One-liner mode'' for more details.
+
+sam2p is not interactive, it doesn't ask questions; thus it is completely
+suitable for batch processing and automation. sam2p doesn't log errors, but
+its STDERR can be redirected to a log file quite easily.
+
+There are three modes sam2p can operate in:
+
+-- one-liner mode: (since sam2p 0.37)
+ the user, perhaps, has to type a long command line, specifying the input
+ and the output file name, output file format, compression options, etc.
+ Most of the functionality of sam2p is available in a quite intuitive way
+ in one-liner mode. Users of the `convert' utility from ImageMagick and
+ `tiff2ps' and `tiffcp' will find that one-liner mode of sam2p is very
+ similar to them. This mode is recommended for impatient users.
+
+ Due to the nature of sam2p development, some new functionality of job mode
+ might be missing from one-liner mode. Please report this as a bug.
+
+-- job mode: the user has to write a ``job'' file (recommended extension:
+ .job), which specifies all conversion parameters, including the input and
+ output file name. The name of the job file must be passed to sam2p. This
+ mode is recommended for expert users who want to retain full control of
+ all aspects of the final output. All functionality is available in job
+ mode. This is especially useful in repetative but time separated jobs.
+
+-- GUI mode: This is completely experimental, and will be very probably
+ dropped in the near future. Try executing sam2p.tk (TCL/Tk is required).
+ Please don't use GUI mode, use one-liner mode instead! The flexability
+ of a one-liner (or job) mode is nearly imposible to encompas in a GUI.
+ No more documentation is provided for GUI mode.
+
+ There might be a Micro$oft Windoze version of sam2p available in the near
+ future, but very probably you won't get real GUI with radio boxes, lists
+ and file selection dialogs. You'll have to start sam2p from the DOS
+ prompt...
+
+One-liner mode
+~~~~~~~~~~~~~~
+This section contains a reference-style summary for the one-liner mode.
+The author knows that this section is quite incomprehensible, and a bit old.
+He is planning to completely rewrite it to be readable for the novice user.
+
+The order of the arguments and options is significant.
+
+Input file extension is discarded. The file format is recognised by its
+magic number.
+
+Output file extension gives a hint for /FileFormat:
+
+.ps :\
+ .eps : \ where PS: implies scale to fit page
+ .epsi : > PSL1 PSLC PSL2 PSL3 and
+ .epsf : / EPS: implies no scale changes
+ [E]PS::/ also see Q9 in FAQs below
+.pdf : \ PDF1.0 PDF1.2 (and)
+ PDF: : / PDFB1.0 PDFB1.2
+.gif : GIF89a
+.pnm : PNM (for use with transparency)
+.pbm : PNM /SampleFormat/Gray1
+.pgm : PNM /SampleFormat/Gray8
+.ppm : PNM /SampleForamt/Rgb8
+.pam : PAM
+.pip : PIP
+.empty : Empty
+.meta : Meta
+.jpeg : JPEG
+ .jpg : "
+.tiff : TIFF
+ .tif : "
+.png : PNG
+.xpm : XPM
+.bmp : BMP /Compression/RLE
+.rle : BMP /Compression/RLE
+
+Options (case insensitive):
+
+-- --tmpremove {true|false} : remove temporary files after completion.
+ Set to false for debugging. Default: true.
+-- -j -j:job : display in-memory .job file
+-- -j:warn : be verbose and display warnings about impossible combinations in
+ the .job file
+-- -j:quiet : print only error and fatal error messages, suppress
+ warnings, notices etc. Must be put at the beginning of the
+ command line to suppress initial banners, too. For example,
+ `sam2p -j:quiet in.gif out.eps'.
+-- -s:Indexed1:Indexed4:Indexed8: Try /SampleFormats in this order, and try
+ all others after these. Can be specified separately
+ (e.g `-s Indexed1 -s Indexed2:Indexed8')
+-- -s:Indexed1:Indexed4:Indexed8:stop: Try only these /SampleFormats in
+ this order. Can be specified separately
+ (e.g `-s Indexed1:Indexed2 -s Indexed8:stop')
+-- -s:Indexed1:Indexed4:Indexed8:stopq: Try only these /SampleFormats in
+ this order, be quiet (no warnings on failures). Can be
+ specified separately (e.g `-s Indexed1:Indexed2 -s Indexed8:stop')
+-- -s:tr equivalent to `-s Transparent:Opaque:Mask:Transparent2:Transparent4:Transparent8'
+-- -l:... : /LoadHints(...)
+-- disabled: -a: /LoadHints(asis) extra /Compression/JAI; load JPEG files (and others as-is)
+
+-- -1 -ps:1 PSL1: : [tiff2ps] hint /FileFormat/PSL1 among /PSL*
+-- -1c -ps:1c -ps:c PSLC: : [pts] hint /FileFormat/PSLC among /PSL*
+-- -2 -ps:2 PSL2: EPS2: : [tiff2ps,imagemagick] default hint /FileFormat/PSL2 among /PSL*
+-- -3 -ps:3 PSL3: : [pts] hint /FileFormat/PSL3 among /PSL*
+-- -pdf:b0 PDFB1.0: : [pts] hint /FileFormat/PDFB1.0 among /PDF* (PDF 1.0 with inline image)
+-- -pdf:b2 PDFB1.2: : [pts] default hint /FileFormat/PDFB1.2 among /PDF* (PDF 1.2 with inline image; default because image processors usually keep inline images intact, so they wouldn't want to inefficiently recompress our image)
+-- -pdf:0 PDF1.0: : [pts] hint /FileFormat/PDF1.0 among /PDF* (PDF 1.0 with XObject image)
+-- -pdf:2 PDF1.2: : [pts] hint /FileFormat/PDF1.2 among /PDF* (PDF 1.2 with XObject image)
+-- EPS: EPSF: : [pts] hint /FileFormat/PSL2 or
+ /FileFormat/PSL3 (for /Compression/ZIP)
+-- PDF: : [pts] hint /FileFormat/PDFB1.0 or
+ /FileFormat/PDFB1.2 (for /Compression/ZIP)
+-- PS: : [pts] hint /Scale/RotateOK /FileFormat/PSL2 or
+ /FileFormat/PSL3 (for /Compression/ZIP)
+-- PS2: : [imagemagick] hint /Scale/RotateOK
+ /FileFormat/PSL2. Deprecated, please use PS:.
+
+-- -e:0 -e:none : /Scale/None
+-- -e -e:1 -e:scale : /Scale/OK
+-- -e:rot -e:rotate : /Scale/RotateOK
+
+-- GIF: GIF89a: : [imagemagick,pts] /FileFormat/GIF89a
+-- JPEG: JPG: : [imagemagick,pts] /FileFormat/JPEG
+-- TIFF: TIF: : [imagemagick,pts] /FileFormat/TIFF
+-- PNG: : [imagemagick] /FileFormat/PNG
+-- XPM: : [imagemagick] /FileFormat/XPM
+-- BMP: : [imagemagick] /FileFormat/BMP
+-- Empty: : [pts] /FileFormat/Empty
+-- Meta: : [pts] /FileFormat/Meta
+-- PIP: : [pts] /FileFormat/PIP
+-- PAM: : [pts] /FileFormat/PAM
+-- PNM: : [imagemagick] /FileFormat/PNM (for use with transparency)
+-- PBM: : [imagemagick] /FileFormat/PNM /SampleFormat/Gray1
+-- PGM: : [imagemagick] /FileFormat/PNM /SampleFormat/Gray8
+-- PPM: : [imagemagick] /FileFormat/PNM /SampleFormat/Rgb8
+
+-- -t:bin : [pts] hint /TransferEncoding/Binary (default unless /PS*)
+-- -t:hex : [pts] hint /TransferEncoding/Hex (default for /PSL1 /PSLC)
+-- -t:a85 : [pts] hint /TransferEncoding/A85 (default for /PSL2 /PSL3)
+-- -t:ascii : [pts] hint /TransferEncoding/ASCII
+-- -t:lsb1 -f:lsb2msb : [pts,tiffcp] hint /TransferEncoding/LSBfirst
+-- -t:msb1 -f:msb2lsb : [pts,tiffcp] hint /TransferEncoding/MSBfirst
+
+-- -c:none : [pts,tiffcp] non-default hint /Compression/None
+-- -c:lzw : [pts,tiffcp] hint /Compression/LZW
+-- -c:lzw:(1..99) : [pts] hint /Compression/LZW /Predictor ...
+-- -c:zip : [pts,tiffcp] hint /Compression/ZIP
+-- -c:zip:(1..99) : [pts] hint /Compression/ZIP /Predictor ...
+-- -c:zip:(1..99):(-1..9) : [pts] hint /Compression/ZIP /Predictor ... /Effort ...
+-- -c:(rle|packbits) : [pts,tiffcp] hint /Compression/RLE
+-- -c:(rle|packbits):(0..) : [pts] hint /Compression/RLE /RecordSize ...
+-- -c:fax : [pts] hint /Compression/Fax
+-- -c:fax:(-1..) : [pts] hint /Compression/Fax /K ...
+-- -c:dct : [pts] hint /Compression/DCT /DCT<<>>
+-- -c:dct:... : [pts] hint /Compression/DCT /DCT<<...>>
+-- -c:jpeg : [pts,tiffcp] hint /Compression/JAI, /Compression/IJG
+-- -c:jpeg:(0..100) : [pts] hint /Compression/JAI, /Compression/IJG /Quality ...
+-- -c:ijgi : [pts,tiffcp] hint /Compression/IJG
+-- -c:ijg:(0..100) : [pts] hint /Compression/IJG /Quality ...
+-- -c:g4 : [pts] equivalent to -c:fax:-1
+-- -c:g3 -c:g3:1d : [pts] equivalent to -c:fax:0, -c:fax
+-- -c:g3:2d : [pts] equivalent to -c:fax:-2
+-- -c:jai : [pts] hint /Compression/JAI
+
+-- -m:dpi:(dimen) : set /ImageDPI to `dimen'
+-- -m:(dimen) \ : set all margins (/TopMargin,/BottomMargin, /LeftMargin, /RightMargin) to `dimen'
+ -m:all:(dimen) \ : /LeftMargin, /RightMargin) to `dimen'
+ -m:a:(dimen) :
+-- -m:horiz:(dimen) \ : set /LeftMargin and /RightMargin to `dimen'
+ -m:h:(dimen) \ :
+ -m:x:(dimen) :
+-- -m:vert:(dimen) \ : set /TopMargin and /BottomMargin to `dimen'
+ -m:v:(dimen) \ :
+ -m:y:(dimen) :
+-- -m:left:(dimen) \ : set /LeftMargin to `dimen'
+ -m:l:(dimen) :
+-- -m:right:(dimen) \ : set /RightMargin to `dimen'
+ -m:r:(dimen) :
+-- -m:top:(dimen) \ : set /TopMargin to `dimen'
+ -m:t:(dimen) \ :
+ -m:up:(dimen) \ :
+ -m:u:(dimen) :
+-- -m:bottom:(dimen) \ : set /BottomMargin to `dimen'
+ -m:b:(dimen) \ :
+ -m:down:(dimen) \ :
+ -m:d:(dimen) :
+
+-- -- : if given as last arg, then OutputFile:=InputFile
+-- -- : if given earlier than last arg, then treat other args as filenames
+-- -transparent:(rgb) Change the all pixels having the specified RGB color
+ to transparent. Previously transparent pixels are not changed. See FAQ
+ answer A44 for an exampe.
+
+Default and fallback compression types for each file format:
+
+-- PSL1 PSLC : /RLE
+-- PSL2 PDFB1.0 PDF1.0 : /JAI /RLE
+-- PSL3 PDFB1.2 PDF1.2 : /JAI /ZIP
+-- GIF89a : /LZW
+-- XPM PNM PAM PIP Empty Meta : )/None)
+-- JPEG : /JAI /IJG
+-- TIFF : /JAI /LZW? /RLE
+-- PNG : /ZIP
+-- BMP : /RLE
+
+Overview of job mode
+~~~~~~~~~~~~~~~~~~~~
+In the ``job mode'' sam2p doesn't accept any command line options. It must be
+controlled from the ``job'' files. In ''job mode'' sam2p expects a single command
+line argument: the name of the Job file (file format described in section
+{Jobs}). sam2p runs that single job, prints debug, info, notice, warning and
+error messages (etc.), and creates a single output file: a PS or a PDF. For
+multiple jobs and/or multiple output files, one has to run sam2p multiple
+times.
+
+The details about the output file format (including standards-compliance,
+compression and transfer encoding) are specified in the Job file and other
+files. Thus, in order to make use of the (basic and) advanced
+features of sam2p in job mode, you have to:
+
+1. Understand the basic concepts (i.e read through this manual, and have a
+ look at the examples).
+2. Prepare the input raster (bitmap) graphics file in one of the supported
+ input formats (see section {Supported input formats}).
+3. Decide the name of the output file.
+4. Decide some or all details of the output format.
+5. Create a Job file that describes those details.
+6. Invoke the program `sam2p' with the name of the Job file as a single
+ command-line argument (or `-' if the Job file is fed on STDIN).
+7. Read warning and error messages (printed to STDOUT and STDERR), and retry
+ if necessary.
+
+Revision history, changes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+See in the file debian/changelog.
+
+Known bugs and issues
+~~~~~~~~~~~~~~~~~~~~~
+Please see pending bugs on https://github.com/pts/sam2p/issues .
+Feel free to report any issue there if you encounter one! Your
+bug reports and contributions are very welcome.
+
+All of these old bugs had a follow-up elsewhere, or they don't need one:
+https://code.google.com/archive/p/sam2p/issues .
+
+If you are interested in fixed or closed bugs, please see them on
+https://github.com/pts/sam2p/issues?q=is%3Aissue%20is%3Aclosed .
+
+Requirements
+~~~~~~~~~~~~
+External software required for running sam2p:
+
+-- operting system: any of:
+ -- Linux
+ -- Mac OS X
+ -- Windows (any 32-bit Windows system released since 1995 will do;
+ for older systems, install Wordpad to get MSVCRT.DLL)
+ -- FreeBSD
+ -- any UNIX system with a fairly standard BSD or POSIX C library (C++
+ libraries are not required),
+-- optionally: the libjpeg `cjpeg' utility for /Compression/IJG
+-- optionally: the libjpeg `djpeg' utility for reading JPEG files
+-- optionally: tif22pnm (uses libtiff) for reading TIFF files
+-- optionally: png22pnm (uses libpng) for reading PNG files
+
+Installation on Linux from package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you use Debian, Ubuntu or some other .deb-based distribution on an i386
+(x86) or amd64 (x86_64) system, download the latest .deb package from:
+
+ https://github.com/pts/sam2p/releases
+
+Install it like this:
+
+ $ sudo dpkg -i sam2p_0.49.3-1_i386.deb
+
+The executable in the .deb file doesn't have any library dependencies, it
+works on any version of Debian and Ubuntu.
+
+sam2p used to be included in Debian and Ubuntu for all architectures, but it
+isn't anymore as of 2017-07-12 (it disappeared in 2016-01-22, see
+https://tanguy.ortolo.eu/blog/article143/removing-sam2p-from-debian .)
+
+If you need PNG input support, download the latest png22pnm.exe from:
+
+ https://github.com/pts/tif22pnm/releases
+
+Then put it to the same directory where sam2p.exe is.
+
+If you need PNG input support, download the latest png22pnm.xstatic
+executable from:
+
+ https://github.com/pts/tif22pnm/releases
+
+Then put it to your $PATH as tif22pnm, something like this:
+
+ $ chmod 755 tif22pnm.xstatic
+ $ sudo mv tif22pnm.xstatic /usr/local/bin/tif22pnm
+
+Alternatively, tif22pnm may be available as a package on your Linux
+distribution.
+
+Using it on Linux without installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you use any Linux on an i386 (x86) or amd64 (x86_64) system, download the
+latest sam2p.xstatic executable from:
+
+ https://github.com/pts/sam2p/releases
+
+Run it like this:
+
+ $ mv sam2p.xstatic sam2p
+ $ chmod 755 sam2p
+ $ ./sam2p
+
+The executable doesn't have any library dependencies, it works on any Linux
+system.
+
+If you need PNG input support, download the latest png22pnm.xstatic
+executable from:
+
+ https://github.com/pts/tif22pnm/releases
+
+Then put it to your $PATH as tif22pnm, something like this:
+
+ $ chmod 755 tif22pnm.xstatic
+ $ sudo mv tif22pnm.xstatic /usr/local/bin/tif22pnm
+
+Using it on FreeBSD without installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+FreeBSD has a Linux subsystem, which is able to run sam2p. After activating
+it, follow the instructions in the section {Using it on Linux without
+installation}.
+
+Using it on Windows without installation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Download the latest sam2p.exe from:
+
+ https://github.com/pts/sam2p/releases
+
+Then copy sam2p.exe to the current directory, or to somewhere on your $PATH,
+and run it as `sam2p' (without the quotes).
+
+sam2p.exe has only standard Windows DLL dependencies, it works on any
+Windows systems (i386 and amd64). If MSVCRT.DLL is missing, install Wordpad.
+
+If you need PNG input support, download the latest png22pnm.exe from:
+
+ https://github.com/pts/tif22pnm/releases
+
+Then put it to the same directory where sam2p.exe is.
+
+Compilation on UNIX
+~~~~~~~~~~~~~~~~~~~
+For Win32 compilation, see later.
+
+Software required for UNIX compilation:
+
+-- a UNIX system
+-- a working, GNU-compatible C++ compiler (preferably GNU G++ >=2.91. Known
+ working compilers: g++-2.91 g++-2.95 g++-3.0 g++-3.1 g++-3.2)
+-- GNU Make (`make -v' should print `GNU Make')
+-- Perl >=5.004 (no external Perl modules are required)
+-- a Bourne-compatible shell (preferably GNU Bash >=2.0)
+-- the following libraries are _not_ required: libjpeg, libtiff, libpng,
+ libungif, PDFlib, zlib, libm, libstdc++
+-- optionally: GNU autoconf >=2.53 (version number is important, see
+ AC_C_CONST)
+
+Compilation:
+
+ # compile and install required programs
+ autoconf # optional, for experts only
+ export CC=gcc-3.2 CXX=g++-3.2 # optional, for experts only
+ ./configure --enable-gif --enable-lzw
+ make
+ # the stand-alone utility `./sam2p' is now built
+ make install # optional, may not work
+
+If installation doesn't work, please copy the file `sam2p' to somewhere in
+your $PATH, for example /usr/local/bin. Please also copy the README to a
+directory like /usr/share/doc/sam2p. There is no man page -- the
+documentation is the readme.
+
+Testing:
+
+ ./sam2p
+ ./sam2p examples/ptsbanner_zip.job
+ ./sam2p examples/pts2.pbm try.eps
+ gs test.ps
+ # try other examples: examples/*.job
+
+On Debian systems, you'll need GNU Make, Perl, GNU Bash and any of the
+following packages for compilation:
+
+ apt-get install libc6-dev gcc-2.95 g++-2.95
+ apt-get install libc6-dev gcc-3.0 g++-3.0
+ apt-get install libc6-dev gcc-3.1 g++-3.1
+ apt-get install libc6-dev gcc-3.2 g++-3.2
+ apt-get install libc6-dev gcc-3.3 g++-3.3
+ apt-get install libc6-dev gcc-3.4 g++-3.4
+
+Please also run any of the following before ./configure:
+
+ export CC=gcc-2.95 CXX=g++-2.95
+ export CC=gcc-3.0 CXX=g++-3.0 # or g++-3.1 etc.
+
+Optionally, you may install any of
+
+ apt-get install gccchecker
+ apt-get install autoconf
+
+sam2p has been tested with a wide variety of GNU C++ compilers, including
+g++-2.91, g++-2.95, g++-3.0, g++-3.1, g++-3.2, i386-uclibc-g++-2.95,
+checkerg++-2.95. The program must be compilable _without_ _warnings_ with
+any of g++-2.91, g++-2.95, g++-3.0, g++-3.1, g++-3.2. If there is a
+compilation error, send a brief e-mail to the author immediately!
+
+Portability
+~~~~~~~~~~~
+sam2p is quite portable on UNIX systems. It runs on:
+
+ Debian GNU/Linux Slink 2.2.13 glibc-2.0.7 (development platform)
+ Debian GNU/Linux Potato 2.2.18 glibc-2.1.3
+ Debian GNU/Linux Sid 2.4.17 glibc-2.2.5
+ Digital OSF1 V4.0 1229 alpha
+ Slackware 8.0/8.1 2.4.5 libc-2.2.3 gcc-2.95.3
+ SunOS 5.7 Generic_106541-17 sun4u sparc SUNW,Ultra-2 gcc-2.95.2
+ SunOS 5.8 Generic_108528-12 sun4u sparc gcc-3.0.4
+
+Also it runs on Win32 in command line (sam2p.exe) and GUI mode (vcsam2p.exe).
+Command line mode is stable and it is recommended on this platform.
+
+It should work on any Linux or BSD system without modification. Porting to
+other Unices should be quite easy. The author welcomes portability patches.
+
+Porting to non-UNIX systems may be hard. Reasons:
+
+-- Those systems might not have GNU Make, Perl or a Bourne-compatible shell
+ installed. So the Makefile supplied won't work, and many man hours of extra
+ work would be necessary.
+-- sam2p uses the popen(3) library call to communicate with external
+ processes. This call might not be available on non-UNIX systems.
+-- sam2p expects that the $PATH contains the external binaries. Some systems
+ tend to have empty or misconfigured $PATH. On some systems, `gs' is
+ called `gswin32c.exe' etc.
+
+sam2p 0.38 has been compiled and run successfully on:
+
+-- Linux 2.2.8 Debian Slink, g++-2.91
+-- Linux 2.4.18-ac3 Debian SID, g++-2.95, g++-3.0, g++-3.1, g++-3.2
+ Executable size: 318kB.
+-- Linux 2.4.2 Debian Potato, gcc version 2.95.2 20000220 (Debian GNU/Linux)
+ No warnings.
+ Compilation took 0:47, executable size: 330kB.
+-- Linux 2.2.16-3 Red Hat Linux release 6.2 (Zoot), gcc version egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)
+ No warnings.
+ Compilation took 0:44, executable size: 324kB.
+-- OSF1 V4.0 564 alpha, gcc version 2.7.2.2
+ (tons of: warning: cast discards `const' from pointer target type,
+ tons of: warning: the meaning of `\x' varies with -traditional
+ tons of: warning: cast increases required alignment of target type)
+ Compilation took 5 minutes, executable size: 550kB.
+-- SunOS 5.7 Generic_106541-19 sun4u sparc SUNW,Ultra-2, gcc version 3.1
+ (some: warning: cast from `char*' to `int*' increases required alignment of target type)
+ Compilation took 2:50, executable size: 437kB.
+-- SunOS 5.8 Generic_108528-15 sun4u sparc, gcc version 3.1.1
+ (some: warning: cast from `char*' to `int*' increases required alignment of target type)
+ Compilation took 1:26, executable size: 437kB.
+-- Slackware 8.0/8.1, kernel 2.4.5, libc.6.so (libc-2.2.3) gcc-2.95.3
+
+sam2p 0.42 has been compiled and run successfully on:
+
+-- Windows 98, Visual C++ 6.0
+-- Windows 98, MSYS, MingGW, G++ 3.2
+
+Win32 compilation instructions for command-line mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(These instructions are outdated.)
+
+To compile sam2p.exe, the Win32 equivalent of the UNIX utility sam2p, you
+have to install these build dependencies first:
+
+-- MinGW and MSYS, available from http://www.mingw.org
+
+-- Perl 5.004 or newer (only perl.exe and perl5*.dll are required), available
+ from http://www.perl.com. Note that this will be a long download and a
+ bloated install, but after that, just copy perl.exe and the single
+ perl5*.dll to your C:\WINDOWS directory, and uninstall the rest.
+
+To build sam2p:
+
+1. Install all the build dependencies.
+
+2. Open the MSYS terminal window from the start menu.
+
+3. Run `explorer .' to figure out what is the current working directory.
+ Let's call this directory the MSYS home.
+
+4. Download the sam2p sources (.tar.gz) into the MSYS home from:
+
+ https://github.com/pts/sam2p/releases
+
+5. Unpack the sources. Run:
+
+ tar xzvf sam2p-latest.tar.gz
+ tar xvf sam2p-latest.tar.gz # if the previous one doesn't work
+
+6. Run `cd sam2p-*.*' to enter the sam2p source directory. It should contain
+ a newer version of this README and the file sam2p_main.cpp.
+
+7. Run `perl -edie' to check whether Perl is correctly installed. It should
+ print a line beginning with `Died '. If no such line appears (or you get
+ a `command not found' error message), go and install Perl first. Run
+ `echo $PATH' to find out where MSYS is searching for perl.exe. Copy
+ perl.exe to one of those directories.
+
+8. Run
+
+ ./configure --enable-gif --enable-lzw
+ make
+
+9. The file sam2p.exe is now created in the current directory. Use it. You
+ may copy it to another directory right now:
+
+ cp sam2p.exe 'C:\Program Files'
+
+10. You should invoke sam2p.exe from the command line (COMMAND.COM or
+ CMD.EXE) with the _appropriate_ arguments, described elsewhere in
+ this document. Don't put it into the Start menu, it won't work.
+ (a window will flash in and disappear, showing an error message that you
+ haven't supplied the right arguments).
+
+11. The file bts2.tth is also created. It is an important file, because it
+ is required for the GUI compilation.
+
+12. Don't forget to install tif22pnm.exe to load TIFF files, djpeg.exe to
+ load JPEG files, cjpeg.exe to save JPEG files, and png22pnm.exe to load
+ PNG files. The installation instructions for these programs are not
+ given here.
+
+Win32 compilation instructions for GUI mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+(These instructions are outdated.)
+
+vcsam2p.exe is a preliminary, alpha-stage attempt to provide a Win32 GUI for
+sam2p.exe. Currently it can load and display images, but not cannot save
+them. vcsam2p.exe is not ready for production use. Feel free to enhance the
+code. Just remember to semd me copies.
+
+You'll need Visual Studio 6.0 installed.
+
+1. Download the sam2p sources (.tar.gz) from:
+
+ https://github.com/pts/sam2p/releases
+
+2. Download untarka.exe to be able to unpack the sources:
+
+ http://.../untarka.exe
+
+3. Unpack the sources. Run:
+
+ untarka.exe sam2p-latest.tar.gz
+
+ A directory sam2p-*.* will be created, containing a newer version of this
+ README and the file config-vc6.h
+
+4. You'll need bts2.tth. You can get an old, possibly outdated and buggy
+ version directly:
+
+ http://.../bts2.tth
+
+ Or, you may compile sam2p under Linux (or Win32 command-line), and copy
+ the generated bts2.tth from there.
+
+ Copy bts2.tth to the same directory as config-vc6.h
+
+5. Start the Visual C++ 6.0 environment.
+
+6. File / Open Workspace / File type: Projects
+ Filename: vcsam2p.dsp
+ Build / Set Active Configuration: vcsam2p - Win32 Release
+ Build / Build vcsam2p.exe
+ Build / Execute vcsam2p.exe
+
+7. Don't forget to install tif22pnm.exe to load TIFF files, djpeg.exe to
+ load JPEG files, cjpeg.exe to save JPEG files, and png22pnm.exe to load
+ PNG files. The installation instructions for these programs are not
+ given here.
+
+Please report and fix bugs in vcsam2p.exe
+
+Copyright
+~~~~~~~~~
+sam2p is written and owned by Szabó Péter <pts@fazekas.hu>. sam2p contains
+code from various people.
+
+sam2p may be used, modified and redistributed only under the terms of the
+GNU General Public License, found in the file COPYING in the distribution,
+or at
+
+ http://www.fsf.org/licenses/gpl.html
+
+Supported input formats
+~~~~~~~~~~~~~~~~~~~~~~~
+-- PNM, PBM, PGM, PPM (preferred formats for non-transparent images)
+-- PNM+PGM, PNM+PBM. The input is a concatenation of a PNM and a P[GB]M
+ file with the same dimensions. The second P[GB]M contains the alpha
+ channel.
+-- XPM (preferred formats for indexed images with transparency)
+-- BMP
+-- GIF, with transparency
+-- LBM (IFF ILBM), with transparency
+-- TGA (Targa)
+-- baseline JPEG JFIF (limited by /Compression/JAI)
+-- PCX
+-- JPEG, is supported with libjpeg/djpeg
+-- TIFF, is supported with the author's tif22pnm, with transparency; also
+ works in a limited way with tifftopnm (Debian package libtiff-tools)
+-- PNG, is supported with the author's png22pnm, with transparency
+ (part of the tif22pnm sources); also works in a limited way with
+ libpng/pngtopnm (Debian package graphics/pnmtopng); with transparency
+-- PS, EPS, PDF: Ghostscript is needed (`gs' or `gswin32c.exe'), see also FAQ
+ question Q39.
+
+Note that only the major features of these file formats are supported. sam2p
+is able to load most of these files, but not all of them.
+
+Important, but unsupported input formats:
+
+-- XBM
+-- XWD
+-- Utah RLE
+
+Input image model
+~~~~~~~~~~~~~~~~~
+A (sampled, raster, bitmap) image is a rectangular array of pixels (dots)
+plus some metadata. Each pixel is represented by an unsigned integer which
+is BPC (BitsPerComponent) and CPP (ComponentsPerPixel) wide. The image
+coordinate system (X,Y) is defined as: upper left corner is (0,0), upper
+right corner is (Width-1,0), lower right corner is (Width-1,Height-1).
+(Note that this is the natural, traditional top->down, left->right system,
+and it is different from PostScript and PDF!).
+
+Some pixels of the image may be without color: they're transparent. A
+transparent pixel is not painted, so whatever was left under it on the
+paper, remains visible. (On the other hand, a colored pixel overrides the
+pixel below unconditionally. E.g a white pixel overrides a black pixel, a
+half-gray pixel, and also another white pixel; but a transparent pixel
+leaves the original one visible.). Notions referring to transparent pixels
+are: transparency, opacity, transparent, opaque, alpha channel, matte
+channel.
+
+Images are read from image files on disk. The file format is autodetected
+(see section {Supported input formats}), and it can also be specified in the
+Job file (NOT implemented yet). Not all file formats are able to specify all
+pixel data and metadata, so additional hints (such as the transparent color
+or the name of the image author) can be specified in Job files.
+
+Sample formats
+~~~~~~~~~~~~~~
+The image pixels could be packed to bytes according to several sample
+formats. Each output file (both EPS and PDF) has its own SampleFormat
+(notation: capitals).
+
+A color is either transparent or it is an opaque RGB triplet (8*3 bits).
+
+The number of colors is the number of colors actually _used_. So unused
+palette entries, and e.g unused #555555 in gray-4 are not counted.
+
+If PSLC is required, but the printer is only PSL1, then the color image will
+be printed grayscale.
+
+When _choosing_ the output format, sam2p doesn't degrade image quality. For
+example, if an image has only two colors: #000001 and #ffffff, sam2p won't
+allow the gray-1 sample format, but with #000000 and #ffffff, it will. The
+user is expected to have an image editor in which she can adjust image
+colors precisely (such as in the Dialogs/(Indexed palette) dialog of The
+GIMP).
+
+Supported Sample Formats:
+
+Name:
+ Fast compatibility
+ Slow compatibility
+ Criteria for the image
+ -- Comment(...)
+
+transparent: (specialisation of mask)
+ all
+ -
+ the whole image is transparent
+ -- implemented with empty image body
+opaque: (specialisation of mask and indexed-1)
+ all
+ -
+ the whole image contains the same, opaque color
+ -- implemented with `setrgbcolor', `fill'
+mask: (specialisation of transparent-2)
+ all
+ -
+ a transparent and a non-transparent color (any may be missing)
+ -- display a Warning if the whole image is transparent or opaque,
+ because transparent or opaque would be a better choice
+ -- implemented with a single call to `imagemask'
+indexed-1:
+ all
+ -
+ exactly 2 non-transparent colors or 1 non-transparent color
+ -- display a Warning if only 1 non-transparent color, because
+ opaque would be a better choice
+ -- display a Notice if colors are in black (#000000) and white
+ (#ffffff), beacuse gray-1 would be a better choice
+ -- implemented with a `setrgbcolor', `fill', and a single call to
+ `imagemask'
+indexed-2:
+ PSL2, PDF1.0??
+ PSLC
+ 3 or 4 non-transparent colors or 1..2 non-transparent colors
+ -- display a Warning if only 1..2 non-transparent colors, because
+ opaque or indexed-1 would be a better choice
+ -- display a Notice if colors are in (#000000, #555555, #aaaaaa,
+ #ffffff), beacuse gray-2 would be a better choice
+ -- implemented with the /Indexed color space or colorimage +
+ manual palette lookup
+ -- users with a PSL1 printer without PSLC should use transparent-*
+indexed-4:
+ PSL2, PDF1.0??
+ PSLC
+ 5..16 non-transparent colors or 1..4 non-transparent colors
+ -- display a Warning if only 1..4 non-transparent colors, because
+ opaque, indexed-1 or indexed-2 would be a better choice
+ -- display a Warning if all components are #00 or #ff,
+ because rgb-1 would be a better choice (3 bits over 4 bits)
+ -- display a Notice if colors are in (#000000, #111111, ...,
+ #ffffff), beacuse gray-4 would be a better choice
+ -- implemented with the /Indexed color space or colorimage +
+ manual palette lookup
+ -- users with a PSL1 printer without PSLC should use transparent-*
+indexed-8:
+ PSL2, PDF1.0??
+ PSLC
+ 17..256 non-transparent colors or 1..16 non-transparent colors
+ -- display a Warning if only 1..16 non-transparent colors, because
+ opaque, indexed-1, indexed-2, indexed-4 would be a better
+ choice
+ -- display a Warning if all components are #00, #55, #aa or #ff,
+ because rgb-2 would be a better choice (6 bits over 8 bits)
+ -- display a Notice if all colors are gray, beacuse gray-8 would be
+ a better choice
+ -- implemented with the /Indexed color space or colorimage +
+ manual palette lookup
+ -- users with a PSL1 printer without PSLC should use transparent-*
+transparent-2:
+ all
+ -
+ 0..1 transparent and 1..3 non-transparent colors
+ -- display a Notice that color separation was done (which can
+ decrease speed and compression)
+ -- display a Warning if no transparent color, because `indexed-2'
+ would be a better choice
+ -- display a Warning if only 1 non-transparent color, because `mask'
+ would be a better choice
+ -- implemented with multiple calls to `setrgbcolor', `imagemask'
+transparent-4:
+ all
+ -
+ a transparent and 1..15 non-transparent colors
+ -- display a Notice that color separation was done (which can
+ seriously decrease speed and compression)
+ -- display a Warning if only 1..3 non-transparent colors, because
+ `mask' or `transparent-2' would be a better choice
+ -- implemented with multiple calls to `setrgbcolor', `imagemask'
+transparent-8:
+ all
+ -
+ a transparent and 1..255 non-transparent colors
+ -- display a Warning that color separation was done (which can
+ seriously decrease speed and compression)
+ -- display a Warning if only 1..15 non-transparent colors, because
+ `mask', `transparent-2' or `transparent-4' would be a better
+ choice
+ -- implemented with multiple calls to `setrgbcolor', `imagemask'
+gray-1:
+ all
+ -
+ colors are in black (#000000) and white (#ffffff)
+ -- display a Warning if only 1 color, because opaque would be a
+ better choice
+ -- implemented with the multiple-argument `image'
+gray-2:
+ all
+ -
+ colors are in (#000000, #555555, #aaaaaa, #ffffff)
+ -- display a Warning if only 1..2 colors, because opaque,
+ indexed-1, or gray-1 would be a better choice
+ -- implemented with the multiple-argument `image'
+gray-4:
+ all
+ -
+ colors are in (#000000, #111111, ..., #ffffff)
+ -- display a Warning if only 1..4 colors, because opaque,
+ indexed-1, gray-1, indexed-2 or gray-2 would be a better choice
+ -- implemented with the multiple-argument `image'
+gray-8:
+ all
+ -
+ colors must be gray
+ -- display a Warning if only 1..16 colors, because opaque,
+ indexed-1, gray-1, indexed-2, gray-2, indexed-4 or gray-4
+ would be a better choice
+ -- implemented with the multiple-argument `image'
+rgb-1:
+ PSLC, PDF1.0
+ -
+ color components must be #00 or #ff (8 colors max)
+ -- display a Warning if all colors are gray
+ -- display a Warning if only 1..4 colors, because opaque,
+ indexed-1, indexed-2 (or gray-*) would be a better choice
+ -- implemented with `colorimage'
+rgb-2:
+ PSLC, PDF1.0
+ -
+ color components must be #00, #55, #aa or #ff (64 colors max)
+ -- display a Warning if all colors are gray
+ -- display a Warning if only 1..16 colors, because opaque,
+ indexed-1, indexed-2 or indexed-4 (or gray-*) would be a better choice
+ choice (this includes the case when color components are in
+ #00, #ff)
+ -- implemented with `colorimage'
+rgb-4:
+ PSLC, PDF1.0
+ -
+ color components must be #00, #11, ... #ff (4096 colors max)
+ -- display a Warning if all colors are gray
+ -- display a Warning if only 1..256 colors, because opaque,
+ indexed-1, indexed-2, indexed-4 or indexed-8 (or gray-*) would be a better
+ choice (this includes the case when color components are in
+ #00, #55, #aa, #ff)
+ -- implemented with `colorimage'
+rgb-8:
+ PSLC, PDF1.0
+ -
+ no transparency
+ -- display a Warning if all colors are gray
+ -- display a Warning if only 1..256 colors, because opaque,
+ indexed-1, indexed-2, indexed-4 or indexed-8 (or gray-*) would be a better
+ choice
+ -- display a Warning if all color components are in
+ #00, #11, ... #ff, because rgb-4 would be a better choice
+ -- implemented with `colorimage'
+
+The following directed (acyclic) graph represents that some formats should
+be tried earlier than others to avoid most Warning and Notice messages. The
+graph was created according to the descriptions above.
+
+ EarlierFormat LaterFormat
+
+ transparent mask
+ opaque mask
+ opaque indexed-1
+ indexed-1 indexed-2
+ indexed-2 indexed-4
+ indexed-4 indexed-8
+ gray-1 gray-2
+ gray-2 gray-4
+ gray-4 gray-8
+ rgb-1 rgb-2
+ rgb-2 rgb-4
+ rgb-4 rgb-8
+ gray-1 indexed-1
+ gray-2 indexed-2
+ gray-4 indexed-4
+ gray-8 indexed-8
+ rgb-1 indexed-4
+ rgb-2 indexed-8
+ mask transparent-2
+ transparent-2 transparent-4
+ transparent-4 transparent-8
+ opaque gray-1
+ indexed-1 gray-2
+ indexed-2 gray-4
+ indexed-4 gray-8
+ opaque rgb-1
+ gray-1 rgb-1
+ gray-2 rgb-2
+ gray-4 rgb-4
+ gray-8 rgb-8
+ indexed-2 rgb-1
+ indexed-4 rgb-2
+ indexed-8 rgb-4
+ indexed-8 rgb-8
+
+Every directed acyclic graph (DAG) has a topological ordering on its nodes.
+Such an ordering can be computed by the UNIX (Version 7 AT&T UNIX) utility
+tsort(1). Its output on the author's machine:
+
+ opaque
+ transparent
+ gray-1
+ indexed-1
+ mask
+ transparent-2
+ gray-2
+ indexed-2
+ transparent-4
+ rgb-1
+ gray-4
+ indexed-4
+ transparent-8
+ rgb-2
+ gray-8
+ indexed-8
+ rgb-4
+ rgb-8
+
+This ordering should be taken into account when someone develops her
+Rule Profile. Rules having SampleFormats listed earlier should be earlier in
+the Rule Profile to avoid Warning and Notice messages.
+
+The availability (and also Warnings and Notices) of a Sample Format for a
+particular image can be easily decided after answering the following
+characteristic questions:
+
+-- Is transparency _used_?
+-- How many _used_ non-transparent colors are there? (257 if >=257)
+-- Is there a non-gray color?
+-- How many bits are required (maximum) for each component?
+
+Output rules
+~~~~~~~~~~~~
+Every detail of the output file format is precisely determined by the Output
+Rule. The Output Rule may be specified in the Job file, or is
+automatically chosen from several pre-defined output rules in the Output
+Profile (see section {Output profiles} elsewhere in this document).
+
+Output rule entries:
+
+-- FileFormat: enum (see section {Standards} for detailed information), no
+ default
+ /PSL1 -- PostScript Level1
+ /PSLC -- PostScript Level1 with the CMYK and `colorimage' extension
+ /PSL2 -- PostScript Level2 (default)
+ /PSL3 -- PostScript Level3
+ /PDFB1.0 -- PDF version 1.0, BI inline image, see 4.8.6 in PDFRef.pdf
+ /PDFB1.2 -- PDF version 1.2, BI inline image, see 4.8.6 in PDFRef.pdf
+ /PDF1.0 -- PDF version 1.0, XObject image, see 4.8.4 in PDFRef.pdf
+ /PDF1.2 -- PDF version 1.2, XObject image, see 4.8.4 in PDFRef.pdf
+ /GIF89a
+ /Empty
+ /Meta
+ /PNM
+ /PAM
+ /PIP
+ /TIFF
+ /JPEG
+ /PNG
+ /XPM
+
+-- SampleFormat: enum, no default, see section {Sample formats}
+ /Opaque
+ /Transparent
+ /Gray1
+ /Indexed1
+ /Mask
+ /Transparent2
+ /Gray2
+ /Indexed2
+ /Transparent4
+ /Rgb1
+ /Gray4
+ /Indexed4
+ /Transparent8
+ /Rgb2
+ /Gray8
+ /Indexed8
+ /Rgb4
+ /Rgb8
+ /Asis -- accept contents of the JAI file
+ /Bbox -- no image, only bounding box information
+-- WarningOK: boolean; this Output Rule is enabled iff WarningOK is true or
+ SampleFormat causes no warnings, default: true
+-- TransferEncoding: enum, no default
+ /Binary -- Binary (RawBits, see pbm(5), pgm(5), ppm(5)) (Binary integers
+ are stored in any byte order allowed by /FileFormat)
+ /ASCII -- ASCII (text, chars: 9,10,13,32..126), used with transparent and opaque
+ /Hex /AHx -- Hex ((PSL1), PDF1.0, PSL2 ASCIIHexEncode filter)
+ /A85 -- A85 (PSL2 PDF1.0, ASCII85Encode filter)
+ /MSBfirst -- Binary data with integers stored in MSB first byte order.
+ If 0x41424344 is represented as "ABCD", the byte order is called: big
+ endian, MSB, MSB first (preferred), most significant byte first, most
+ significant bit first, MSB-to-LSB, network byte order, m68k byte order.
+ QuarkXPress 3 can read only TIFF files with MSB-to-LSB byte order.
+ /LSBfirst -- Binary data with integers stored in LSB first byte order.
+ If 0x41424344 is represented as "DCBA", the byte order is called:
+ little endian, LSB, LSB first (preferred), least significant byte
+ first, least significant bit first, LSB-to-MSB, VAX byte order, PC
+ (i386) byte order.
+-- Compression: enum
+ /None -- None (default)
+ /LZW -- LZW (PSL2 PDF1.0 LZWEncode filter EarlyChange=true, UnitLength=8
+ LowBitFirst=false)
+ /ZIP /Flate /Fl -- ZIP (PSL3 PDF1.2 FlateEncode filter without options)
+ /RLE /RunLength /RunLengthEncoded /RL /PackBits -- RLE (PSL2 PDF1.0
+ RunLengthEncode filter, similar to TIFF PackBits)
+ /Fax /CCITTFax /CCF -- Fax (PSL2 PDF1.0 CCITTFaxEncode filter,
+ Uncompressed=true!, K=-1,0,1, EndOfLine=false, EncodedByteAlign=false,
+ Columns=..., Rows=0, EndOfBlock=true, BlackIs1=false,
+ DamagedRowsBeforeError=0)
+ /DCT -- DCT (PSL2 PDF1.0 DCTEncode, options in JPEG
+ stream)
+ /IJG /JPEG /JPG /JFIF -- IJG (PSL2 PDF1.0 DCTEncode, options in JPEG
+ stream; the IJG libjpeg library is used for compression, respecting the
+ quality value 0..100). This requires /SampleFormat/Rgb8 or
+ /SampleFormat/Gray8. This doesn't work with /SampleFormat/Asis.
+ /JAI -- JAI (PSL2 PDF1.0 DCTEncode, options in JPEG stream; JPEG-as-is: the
+ input file must be a JPEG file -- its contents are transferred
+ unmodified into the /DCTDecode JPEG stream). This requires
+ /SampleFormat/Asis, and doesn't work with any other /SampleFormats
+-- Predictor: enum (see later), default: 25, numbering same as PSL1 filter.
+ 1 -- no predictor. (default) Must be this unless Compression is /LZW or
+ /Flate
+ 2 -- TIFF predictor 2 (horizontal differencing)
+ 10 -- PNG predictor, None function
+ 11 -- PNG predictor, Sub function
+ 12 -- PNG predictor, Up function
+ 13 -- PNG predictor, Average function
+ 14 -- PNG predictor, Paeth function
+ 15 -- PNG predcitor, individually chosen for each line (absolute minimum)
+ This is the same as what libpng uses by default when creating PNG.
+ 25 -- Pick 15 or 1 based on the SampleFormat: use 15 for Gray8 and Rgb8,
+ and use 1 (no predictor) for everything else. This is the default.
+ 45 -- PNG predcitor, individually chosen for each line (unsigned minimum)
+ Don't use this, it is quite inefficient.
+ 55 -- PNG predcitor, individually chosen for each line (signed minimum)
+ Don't use this, it is quite inefficient.
+
+-- Transparent: color. Default: null. Specify a color forced to be
+ transparent. Old transparency, if exists, is blacked!
+-- Hints: dict
+ see below
+
+The Hints member of the Output Rule contains a dict with the following
+elements:
+
+-- TopMargin : dimen; desired vertical gap between the top line of the page
+ and the top line of the raster. Default: 0. Ignored unless for PS
+ and PDF output. See docs about `dimen' elsewhere in this document.
+-- BottomMargin : dimen; desired vertical gap between the bottom line of the
+ raster and the bottom line of the page. Default: 0. Ignored unless
+ for PS and PDF output. See docs about `dimen' elsewhere in this document.
+-- LeftMargin : dimen; desired horizontal gap between the left line of the page and
+ the left line of the raster. Default: 0. Ignored unless for PS and PDF
+ output. See docs about `dimen' elsewhere in this document.
+-- RightMargin : dimen; desired horizontal gap between the right line of the raster and
+ the right line of the page. Default: 0. Ignored unless for PS and PDF
+ output. See docs about `dimen' elsewhere in this document.
+-- ImageDPI : positive number; resolution of bitmap image in dots per inch.
+ Default: 72, which means no scaling.
+-- Scale : enum /None -- don't scale (zoom, magnify) the image (default)
+ /OK -- scale PS image to fit page (x factor == y factor)
+ /RotateOK -- scale and/or rotate PS image to fit page (x factor == y factor)
+-- EncoderBPL : int >=1 (bits per scanline, <= rlen)
+-- EncoderCoumns : int >=1 (pixels per scanline)
+-- EncoderRows : int >=1
+-- EncoderColors : int >=1
+-- PredictorColumns : uint; also used if compression is /Fax (reasonable default)
+-- PredictorColors : 1..3; number of color _components_ (reasonable default)
+-- PredictorBPC : 1, 2, 4, 8 (reasonable default), /BitsPerComponent entry in PS and PDF
+-- Effort : -1..9, must be -1 unless Compression is /ZIP (-1 means 5, default)
+-- RecordSize : uint, default: 0. Compression must be /RLE
+-- K : int, default: 0 (-2..infty). Compression must be /Fax.
+ -1 means G4 1d encoding,
+ 0 meangs G3 1D encoding,
+ -2 means G3 2D encoding with arbitrary height, positive value
+ means G3 2D encoding with that height.
+-- Quality : 0..100, used by IJG libjpeg when compression is /IJG. default: 75
+-- ColorTransform : 0..2. For IJG, this _must_ be 0 for Gray and 1 for RGB, so its value
+ is ignored. For DCT, its value is respected: use 0 or 1 only. See DCTEncode
+ in subsubsection 3.13.3 in PLRM.pdf, and for a better documentation: see the
+ sources and docs of libjpeg.
+-- TransferCPL : number of data characters per line. Must be positive when TransferEncoding is
+ /Hex or /A85, and must be zero otherwise. Default: 78
+-- DCT : dict, default: <<>>. Additional parameters for the /DCTEncode filter
+-- Comment : string, default: empty
+-- Title : string, default: empty
+-- Subject : string, default: empty
+-- Author : string, default: empty
+-- Creator : string, default: empty
+-- Producer : string, default: empty
+-- Created : string, default: now
+-- Produced : string: default: now
+
+Metric units
+""""""""""""
+Certain parameters have type `dimen'. This is a metric dimension, measured
+in any of the following real-word distance metric units:
+
+-- 1 bp = 1 bp (big point)
+-- 1 in = 72 bp (inch)
+-- 1 pt = 72/72.27 bp (point)
+-- 1 pc = 12*72/72.27 bp (pica)
+-- 1 dd = 1238/1157*72/72.27 bp (didot point) [about 1.06601110141206 bp]
+-- 1 cc = 12*1238/1157*72/72.27 bp (cicero)
+-- 1 sp = 72/72.27/65536 bp (scaled point)
+-- 1 cm = 72/2.54 bp (centimeter)
+-- 1 mm = 7.2/2.54 bp (millimeter)
+
+Note: If it helps: American typesetters use 72 points per US inch,
+thus 10 pt text will yield 72 chars per normal line of US Letter
+ (like an IBM Selectric)
+ 12 pt text will yield 65 chars per normal line of US Letter
+ (US normal typewritter).
+
+Each image pixel is assumed to be 1 bp wide and 1 bp tall. A dimen is an
+integer or real number, followed by optional whitespace and an optional unit
+(any of `bp', `in', `pt', `pc', `dd', `cc', `sp', `cm', `mm'). The default
+unit is `bp', i.e a bare number is a dimen measured in `bp'. The following
+dimens are all one inch long: `72', `72bp', `72 bp', `1in', `1 in',
+`2.54cm', `25.4mm', `72.27pt', `6pc', `4736286.72sp'.
+
+Note: MiniPS and TeX use the same units.
+
+OutputRule combinations
+~~~~~~~~~~~~~~~~~~~~~~~
+In the final version of sam2p, the following combinations will be supported:
+
+LZW >=2 Binary|Hex|A85 >=PSL2|>=PDF1.0 Mask|Gray*|RGB*|Indexed*
+LZW >=2 Binary|Hex|A85 >=PSL2|>=PDF1.0 Transparent+
+ZIP >=2 Binary|Hex|A85 >=PSL3|>=PDF1.2 Mask|Gray*|RGB*|Indexed*
+ZIP >=2 Binary|Hex|A85 >=PSL3|>=PDF1.2 Transparent+
+None|ZIP|LZW|RLE|Fax|DCT|IJG 1 Binary|Hex|A85 >=PSL2|>=PDF1.0 Mask|Gray*|RGB*|Indexed*
+None|ZIP|LZW|RLE|Fax|DCT|IJG 1 Binary|Hex|A85 >=PSL2|>=PDF1.0 Transparent+
+None 1 ASCII >=PSL1|>=PDF1.0 Opaque
+None 1 ASCII >=PSL1|>=PDF1.0 Transparent
+ZIP 1 Binary|Hex|A85 >=PSL1 Gray*|RGB*|Indexed*
+ZIP 1 Binary|Hex|A85 >=PSL1 Mask|Gray1|Indexed1
+ZIP 1 Binary|Hex|A85 >=PSL1 Transparent+
+None 1 Binary|Hex|A85 >=PSL1 Gray*|RGB*|Indexed*
+None 1 Binary|Hex|A85 >=PSL1 Mask|Gray1|Indexed1
+None 1 Binary|Hex|A85 >=PSL1 Transparent+
+RLE 1 Binary|Hex|A85 >=PSL1 Gray*|RGB*|Indexed*
+RLE 1 Binary|Hex|A85 >=PSL1 Mask|Gray1|Indexed1
+RLE 1 Binary|Hex|A85 >=PSL1 Transparent+
+JAI 1 Binary|Hex|A85 >=PSL2|>=PDF1.0 Asis
+
+TTM files
+~~~~~~~~~
+TTM stands for Template Toy Macro.
+
+A TTM file is a dirty hack for generating templates with auto-calculated
+lengths and offsets. Currently they are used for generating PDF output files
+(/FileFormat/PDFB10 etc.). The syntax
+of a TTM file is MiniPS (i.e a minimalistic PostScript, similar to .job
+files). The TTM file must contain a single MiniPS array.
+
+The elements of the array are called chunks. Each chunk causes some bytes
+to be appended to the output file. Data is appended in the order the
+chunks are listed in the TTM file, but the data calculation order may be
+different. This way it is possible to write (calc) the length of a chunk
+not written (filled in) yet. The very first chunk has number zero.
+different. This way it is possible to write the length of a chunk not
+written yet. The very first chunk has number zero.
+
+The chunk types:
+
+-- string: backtick-sequences will be substituted (e.g ``w' to the width of
+ the image, in pixels) by writeTemplate(). The result is appended to the
+ output file.
+-- positive integer: The offset (zero-based byte-position of the very first
+ character of chunk 0) of the specified chunk will be appended to
+ the output file. Only chunks already appearead may be specified this
+ way. If the specified chunk is an array, then printf("%10u") will be
+ called to print the number (this is useful for making PDF xref tables),
+ otherwise printf("%u") will be called.
+-- negative integer: The length (measured in bytes, after substitutions)
+ of the specified chunk will be appended to the output file, using
+ printf("%u"). Only chunks already calculated may be specified this way.
+-- zero: error
+-- array: the array is interpreted as a standalone TTM subfile, and the rules
+ are applied recursively. This subfile contains sub-chunks, and the
+ subchunks may be arrays themselves.
+-- other MiniPS types: error
+
+The chunks are calculated in the following order: first the array chunks are
+calculated (recursively) in order of appearance, followed by the non-array
+chunks in order of appearance.
+
+A TTM file can have up to 64 top-level chunks.
+
+Example:
+
+ [ 1 %0
+ [ (pts) ] %1.0
+ -1 %2
+ ]
+
+The output file will be: `3pts0000000001' since chunk 1 has length 3 and
+offset 1.
+
+Example job file
+~~~~~~~~~~~~~~~~
+ <<%sam2p job
+ % This is file (named test0.job).
+ /InputFile (test0.pbm)
+ /OutputFile (test0.pdf)
+ /Profile [
+ % This in-line profile is preferred over the defaults
+ << /FileFormat/PDF10 /SampleFormat/Gray1 /TransferEncoding/Binary
+ /Compression/Fax /Hints<</K 99>> >>
+ (pdf10.jib) run % elements found in external file
+ ]
+ >>
+
+See the directory examples/*.job in the sam2p sources.
+
+sam2p vs convert in 2017
+~~~~~~~~~~~~~~~~~~~~~~~~
+Several test runs were done on 2017-07-12 with the latest sam2p and the
+convert tool in ImageMagick 6.7.7-10 to compare the performance of both
+output file size and processing speed.
+
+Conclusions:
+
+-- Don't use convert for EPS output, because with `eps3:' it produces
+ an output file with non-ASCII characters, which is incompatible with many
+ systems, and with `eps:' it produces huge output files. Use e.g. sam2p
+ instead.
+-- For PDF output and JPEG or PNG input, the latest version of both convert
+ and sam2p are fast enough and produce an output of reasonable size.
+-- For PDF output and some PNG input (especially if the image has at most
+ 16 colors), sam2p can be faster and produce much smaller output than
+ convert. (This was not compared here.)
+
+Raw performance data:
+
+-- A run on a 4048x3036 landscape photo JPEG, file size 3009251 bytes:
+
+ $ time jpegtran -optimize -copy none <beach.jpg >beach.opt.jpg
+ 0.14s user 0.02s system 99% cpu 0.170 total
+ output file size: 2955545 bytes
+ (jpegtran removes some unnecessary markes from the JPEG)
+
+ $ time sam2p beach.jpg beach.jpg.sam2p.pdf
+ 0.00s user 0.01s system 90% cpu 0.011 total
+ output file size: 3009793 bytes
+ $ time convert beach.jpg beach.jpg.convert.pdf
+ 0.39s user 0.07s system 138% cpu 0.333 total
+ output file size: 2983807 bytes
+ (convert is a bit smarter removing unnecessary markers from the JPEG)
+ $ time convert beach.opt.jpg beach.opt.jpg.convert.pdf
+ 0.41s user 0.17s system 136% cpu 0.419 total
+ output file size: 2965683 bytes
+ $ time sam2p beach.opt.jpg beach.opt.jpg.sam2p.pdf
+ 0.00s user 0.01s system 90% cpu 0.014 total
+ output file size: 2956087 bytes
+ (now, without the unnecessary markers, the output of sam2p is smaller)
+
+ $ time sam2p beach.jpg beach.jpg.sam2p.eps
+ 0.02s user 0.01s system 96% cpu 0.035 total
+ output file size: 3809826 bytes
+ $ time convert beach.jpg eps3:beach.jpg.convert.eps
+ 0.27s user 0.04s system 86% cpu 0.359 total
+ output file size: 2979366 bytes
+ (the file is small, because convert doesn't apply /ASCII85Decode,
+ thus breaks the embedding of the EPS on some systems)
+ $ time sam2p -t:bin beach.opt.jpg beach.opt.jpg.sam2p_n.eps
+ 0.00s user 0.00s system 84% cpu 0.006 total
+ output file size: 2955974 bytes
+ (that's very close to the input JPEG file size, better than convert)
+
+-- A run on a 4048x3036 landscape photo PNG, file size 11508728 bytes:
+
+ $ time sam2p beach.png beach.png.sam2p.pdf
+ 4.07s user 0.15s system 99% cpu 4.223 total
+ output file size: 12471057 bytes
+ $ time convert beach.png beach.png.convert.pdf
+ 2.01s user 0.13s system 106% cpu 2.015 total
+ output file size: 18095807 bytes
+ (convert is faster, but its output PDF is much larger)
+
+ $ time sam2p beach.png beach.png.sam2p.eps
+ 2.63s user 0.18s system 99% cpu 2.812 total
+ output file size: 15734187 bytes
+ $ time convert beach.png eps3:beach.png.convert.eps
+ 1.87s user 0.06s system 99% cpu 1.933 total
+ output file size: 18079080 bytes
+ (the file is larger, but it's still not fair to compere,
+ because convert doesn't apply /ASCII85Decode,
+ thus breaks the embedding of the EPS on some systems)
+ (convert is faster because sam2p is slow to read PNG files)
+ $ time sam2p -t:bin beach.png beach.png.sam2p_n.eps
+ 2.52s user 0.24s system 99% cpu 2.761 total
+ output file size: 12428098 bytes
+ (that's the fair comparison of sizes)
+
+Some comments:
+
+-- Converting JPEG to PDF or EPS is fast for both sam2p and convert, because
+ JPEG decoding and encoding is not done. sam2p is even faster, because
+ it doesn't do lossless optimizations.
+-- When converting JPEG, convert removes some JPEG markers and does some
+ lossless optimizations (similar but less
+ than what `jpegtran -optimize -copy none' removes), thus the output of
+ convert is smaller than sam2p. However, if we run the jpegtran command
+ first, then the output of sam2p becomes smaller.
+-- When creating EPS files with convert, `eps3:' should be specified as
+ the output format, because `eps:' would create much larger files, mostly
+ because of worse compression algorithms and hex-encoding.
+-- Older versions of convert created much larger EPS files, mostly because
+ they included an uncompressed image preview.
+-- With the `eps3:' output format of convert, the EPS file will contain
+ non-ASCII characters, which is incompatible with some systems, and
+ it cannot be fixed with a command-line flag. sam2p applies /ASCII85Decode
+ (-t:a85) by default, producing an ASCII output file. Thus convert doesn't
+ have a good option: with `eps:' output files are huge; with `eps3:'
+ output files are incompatible with some systems.
+-- convert is generally slower than sam2p, except when reading PNG files
+ (for which sam2p is about 1.5 times slower). convert used to be much
+ slowen that it is now.
+-- sam2p has fewer dependencies and the total binary size is smaller than of
+ convert. This can make startup time faster, and it can make it easy to
+ install to systems without sam2p packaged.
+-- sam2p is smart and fast, and it produces small output with images with a
+ few colors only (2..16). (It doesn't matter if these colors are encoded
+ as a palette or RGB.) There were no such images in this test run.
+-- sam2p gives control to the user to fine-tune compression and other
+ settings for EPS and PDF, and convert doesn't. The defaults of sam2p are
+ tuned for the general use case though.
+
+FAQ
+~~~
+Q1. Should I care about /LoadHints (,asis,) when loading JPEG files?
+
+A1. No, sam2p guesses it by magic (in both job mode and one-liner mode).
+ However, you may want to set it manually in job mode:
+
+ /LoadHints () % use djpeg
+ /LoadHints (,asis,) % don't use djpeg
+ % nothing: automatic guess, based on /Compression/JAI
+
+Q2. How do I convert a JPEG file to PostScript Level2 EPS?
+
+A2. In one-liner mode, just run:
+
+ ./sam2p <INPUT.jpg> <OUTPUT.eps>
+ Example: ./sam2p try.jpg try.eps
+
+ In one-liner mode, if you have both the djpeg and cjpeg utilities
+ (budled with libjpeg from IJG (Independent JPEG Group)), _and_ you want
+ to adjust quality vs size of the output, just run:
+
+ ./sam2p -c:jpeg:<QUALITY> <INPUT.jpg> <OUTPUT.eps>
+ Example: ./sam2p -c:jpeg:60 try.jpg try.eps
+
+ In job mode, just run sam2p with the following .job file:
+
+ <<%sam2p-job;
+ % conversion is possible without external utilities cjpeg and djpeg
+ % No quality loss, just verbatim adata copying.
+ /InputFile (INPUT.jpg)
+ /OutputFile (OUTPUT.eps)
+ /Profile [
+ << /FileFormat/PSL2 /SampleFormat/Asis /TransferEncoding/A85
+ /Compression/JAI >>
+ ] >>
+
+ Alternatively, to adjust quality vs size, use the following .job file:
+
+ <<%sam2p-job;
+ % external utilities cjpeg and djpeg are required
+ % This uses a JPEG decompression (djpeg), plus lossy JPEG compression
+ % (cjpeg), so there might be quality loss!
+ /InputFile (INPUT.jpg)
+ /OutputFile (OUTPUT.eps)
+ /Profile [
+ << /FileFormat/PSL2 /SampleFormat/Rgb8 /TransferEncoding/A85
+ /Compression/IJG /Hints <<
+ /Quality 40 % 0..100 (should be at least around 30)
+ >> >>
+ ] >>
+
+Q3. How do I convert a GIF file to PostScript Level2 EPS?
+
+A3. Check that sam2p has been compiled with GIF support: run sam2p, and
+ examine its console output. It should contain a line:
+
+ Available Loaders: ... GIF ...
+
+ If GIF doesn't appear in the line, please recompile sam2p with:
+
+ make clean
+ ./configure --enable-gif --enable-lzw
+ make
+ cp sam2p /usr/local/bin
+
+ After that, run sam2p again, and check for the line above again.
+
+ In one-liner mode, just run:
+
+ ./sam2p <INPUT.gif> <OUTPUT.eps>
+ Example: ./sam2p try.gif try.eps
+
+ In job mode, if the GIF file doesn't have transparent pixels, run sam2p
+ with the following .job file:
+
+ <<%sam2p-job;
+ /InputFile (INPUT.gif)
+ /OutputFile (OUTPUT.eps)
+ /Profile [
+ << /FileFormat/PSL2 /SampleFormat/Indexed8 /TransferEncoding/A85
+ /Compression/None >>
+ ] >>
+
+ If the GIF file has transparent pixels, run sam2p with the following .job
+ file:
+
+ <<%sam2p-job;
+ /InputFile (INPUT.gif)
+ /OutputFile (OUTPUT.eps)
+ /Profile [
+ << /FileFormat/PSL2 /SampleFormat/Transparent8 /TransferEncoding/A85
+ /Compression/None >>
+ ] >>
+
+Q4. How do I covert a JPEG file to a TIFF/JPEG output file?
+
+A4. A TIFF/JPEG file is a TIFF file (_not_ a JPEG file!), in which the image
+ data is compressed with JPEG (DCTEncode compression). The Compression
+ TIFF tag value is 7. (There is also Compression==6, which corresponds to
+ the old, obsolete JPEG format defined in the old TIFF6.0 spec.)
+
+ In one-liner mode, autodetection is magical. Just run:
+
+ ./sam2p <INPUT.jpg> <OUTPUT.tiff>
+ Example: ./sam2p try.jpg try.tiff
+
+ In job mode, run sam2p with the following .job file:
+
+ <<%sam2p-job;
+ /InputFile (INPUT.jpg)
+ /OutputFile (OUTPUT.tiff)
+ %/LoadHints (asis) % default for /Compression/JAI
+ /Profile [
+ << /FileFormat/TIFF /SampleFormat/Asis /TransferEncoding/Binary
+ /Compression/JAI >>
+ ] >>
+
+ See also {FAQ question Q5} for compatibility notes.
+
+Q5. The TIFF/JPEG file generated by sam2p is invalid! I cannot read it with
+ any programs.
+
+A5. No, it isn't invalid, but most of the programs (including those found in
+ libtiff) cannot deal with TIFF files with JPEG compression.
+
+ Compatibility notes:
+
+ -- tif22pnm 0.03 (from the author of sam2p) can read TIFF/JPEG files
+ perfectly. That's because it calls the TIFFRGBAImageGet() function
+ of libtiff, which works.
+
+ -- sam2p 0.37 can read TIFF/JPEG files, beacuse it calls tif22pnm to do
+ the job. Sam2p can write TIFF/JPEG files as well.
+
+ -- GIMP 1.0.2: error message: `Unknown photometric number 6'. GIMP TIFF
+ import filter cannot deal with the YCbCr color space (which is the
+ most common and de facto standard color space in non-grayscale JPEG
+ files). It works, however, with grayscale JPEGs.
+
+ -- tifftopnm from libtiff-tools 3.4beta037-5.1: `unknown photometric:
+ 6'. Ditto. (Unfortunately tifftopnm doesn't call TIFFRGBAImageGet(),
+ it just tries to re-implement an obsolete version of the function.)
+
+ -- `tiffcp -c jpeg' from libtiff-tools 3.4beta037-5.1 creates a
+ perfectly legal TIFF/JPEG file.
+
+ -- tiffcp from libtiff-tools 3.4beta037-5.1 cannot load a file created
+ by itself (`tiffcp -c jpeg')! There is no problem with grayscale
+ images, but color images have one component removed.
+
+ -- xv 3.10a: Ditto.
+
+ -- display from ImageMagick 4.04: strange error message about libraries:
+ `JPEGLib: Wrong JPEG library version: library is 61, caller expects 62.'
+
+ Simple conclusion:
+
+ -- Use sam2p or `tiffcp -c jpeg' to create a TIFF/JPEG. (Be aware that
+ `tiffcp -c jpeg' cannot read a TIFF/JPEG: it can only create one.)
+ -- Use tif22pnm to load or decode a TIFF/JPEG.
+ -- In your own C programs, call the TIFFRGBAImageGet() function to read
+ TIFF image data.
+ -- Don't use anything else if you want to avoid compatibility problems.
+
+Q6. Does sam2p support transparency and alpha channels?
+
+A6. sam2p supports only bilevel transparency (i.e a pixel is either fully
+ opaque or fully transparent), and only with indexed images. Transparency
+ is supported when loading indexed PNG, TIFF, PNM, GIF, LBM and XPM files.
+ A PNM file with transparency is a regular PBM/PGM/PPM file with a
+ PBM image appended to it as the alpha channel (black pixel is
+ transparent).
+
+ For transparent output, the user has to specify /Transparent, /Mask,
+ /Transparent2, /Transparent4 or /Transparent8 as /SampleFormat. This
+ works with:
+
+ -- /FileFormat/PSL1+ /SampleFormat/Transparent
+ -- /FileFormat/PDF1.0+ /SampleFormat/Transparent
+ -- /FileFormat/PDFB1.0+ /SampleFormat/Transparent
+ -- /FileFormat/PSL1+ /SampleFormat/Mask
+ -- /FileFormat/PDF1.0+ /SampleFormat/Mask
+ -- /FileFormat/PDFB1.0+ /SampleFormat/Mask
+ -- /FileFormat/GIF89a /SampleFormat/Mask
+ -- /FileFormat/PNM /SampleFormat/Mask
+ -- /FileFormat/TIFF /SampleFormat/Mask
+ -- /FileFormat/PNG /SampleFormat/Mask
+ -- /FileFormat/XPM /SampleFormat/Mask
+ -- /FileFormat/PSL1+ /SampleFromat/Transparent+
+ -- /FileFormat/GIF89a /SampleFormat/Transparent+
+ -- /FileFormat/PNM /SampleFormat/Transparent+
+ -- /FileFormat/TIFF /SampleFormat/Transparent+
+ -- /FileFormat/PNG /SampleFormat/Transparent+
+ -- /FileFormat/XPM /SampleFormat/Transparent+
+
+Q7. How large is a pixel of PostScript and PDF files generated by sam2p in
+ real-world metric units (inches or centimeters)?
+
+A7. 72 big points == 1 inch == 2.54 centimeters
+
+ 1 pixel == 1 big point
+
+Q8. I have an image with transparent pixels. What happens if I convert it to
+ /Rgb* or /Gray*?
+
+A8. Either of the following will happen:
+
+ -- You get an error message, sam2p refuses to ignore transparency.
+ Please use /SampleFormat/Transparent+, or call an image manipulation
+ program to remove transparency from the image before feeding it to
+ sam2p.
+ -- Transparency information will be lost, and the color of formerly
+ transparent pixels will be undefined. This would be a bug in sam2p,
+ you should report it.
+
+ However, if you loaded a GIF file, and
+ transformed it to /Gray8 or /Rgb8, the original palette entry (RGB
+ triplet) is faithfully preserved.
+
+Q9. How do I generate a PostScript page ready for immediate printing with
+ margins and the image properly scaled to fit the page?
+ How do I create a PostScript file that will automatically scale the
+ image to the maximum when printed?
+
+
+A9. To print an image as a full PostScript page, call:
+
+ ./sam2p [MARGIN-SPECS] <INPUT.IMG> ps: - | lpr
+ Example: ./sam2p -m:1cm examples/pts2.pbm ps: - | lpr
+
+ To create a PostScript file for printing, call:
+
+ ./sam2p [MARGIN-SPECS] <INPUT.IMG> [ps:] <OUTPUT.ps>
+ Example: ./sam2p -m:1cm examples/pts2.pbm try.ps
+
+ The `-m' option above is sets all four margins to `1 cm'. You can
+ set the margins individually:
+
+ Example: ./sam2p -m:left:7mm -m:right:1cm -m:top:0.5in \
+ -m:bottom:18bp examples/pts2.pbm try.ps
+
+ As you can see in this example, you may specify dimensions in various
+ metric units, see subsection {Metric units}.
+
+ You are strongly encouraged to print raster images with sam2p. Be aware
+ that The GIMP 1.2 printing plugin has several weird contrast setting
+ problems (even for /Gray1 images); white pixels will be gray etc. Other
+ utilities may add unnecessary text banners or scale the image
+ inappropriately.
+
+ In one-liner mode, sam2p guesses from the file extension and the selector
+ (`ps:') whether the desired output file format is PostScript (fit single
+ page) or Encapsulated PostScript (leave size as-is, suitable for
+ inclusion into TeX documents).
+
+ In job mode, without /Scale/OK and /Scale/RotateOK in /Hints,
+ sam2p outputs EPS (Encapsulated PostScript) with /FileFormat/PSL*. EPS
+ files should be included as figures into other documents (such as TeX
+ and InDesign), not printed alone. If you just want to print a sampled
+ image alone, please use your favourite graphics manipulation program
+ instead of sam2p.
+
+ In job mode, create a .job file for the EPS file, and add /Hints. For
+ example:
+
+ <<%sam2p-job;
+ /InputFile (test.in)
+ /OutputFile (test.ps)
+ /Profile [
+ << /FileFormat/PSL2 /SampleFormat/Rgb8 /TransferEncoding/A85
+ /Compression/None /Predictor 1
+ /Hints << /Scale/OK % or /Scale/RotateOK
+ /LeftMargin 12 % measured as number/72 inches
+ /Rightargin 12 % measured as number/72 inches
+ /TopMargin 12 % measured as number/72 inches
+ /BottomMargin 12 % measured as number/72 inches
+ >>
+ >>
+ ]
+ >>
+
+Q10. Do the EPS files created by sam2p conform to some specifications?
+
+ The EPS output of sam2p conforms to the following Adobe specifications:
+
+ 5001.DSC_Spec.pdf
+ 5002.EPSF_Spec.pdf
+
+ DSC and ADSC are: Adobe Document Structuring Conventions. They are
+ comments with lines beginning with `%!' and `%%' in PS and EPS files.
+
+ An excerpt:
+
+ The following example illustrates the proper use of DSC comments in a
+ typical page description that an application might produce when including an
+ EPS file. For an EPS file that is represented as
+
+ %!PS-Adobe-3.0 EPSF-3.0
+ %%BoundingBox: 4 4 608 407
+ %%Title: (ARTWORK.EPS)
+ %%CreationDate: (10/17/89) (5:04 PM)
+ %%EndComments
+ ...PostScript code for illustration..
+ showpage
+ %%EOF
+
+ DSC comments discussion:
+
+ %!PS-Adobe-3.0 EPSF-3.0 (mandatory)
+ %%BoundingBox: ... ... ... ... (mandatory)
+
+ %%Extensions: CMYK (optional, for /PSLC)
+ %%LanguageLevel: 2 (optional, for /PSL2)
+ %%LanguageLevel: 3 (optional, for /PSL3)
+ %%Creation (strongly recommended)
+ %%Title (strongly recommended)
+ %%CreationDate (strongly recommended)
+ %%Trailer (optional)
+ %%EOF (optional)
+ %%DocumentData: Clean7Bit (optional)
+ %%DocumentData: Binary (optional)
+
+Q11. I get the error message `sam2p: Error: applyProfile: invalid
+ combination, no applicable OutputRule'. Help!
+
+A11. This error message means you have requested an invalid combination of
+ FileFormat, SampleFormat, Compression etc. parameters. If you use
+ one-liner mode, and you're sure that you've specified your will
+ correctly in the command line, please report this error message as a
+ sam2p bug (also specify -j in the command line). If you use job mode,
+ please read on.
+
+ Example 1:
+ /Compression/Fax is not allowed in /PSL1.
+
+ Solution 1:
+ specify /FileFormat/PSL2 /Compression/Fax.
+
+ Example 2:
+ /Compression/IJG requires /SampleFormat/Gray8 or /SampleFormat/Rgb8.
+ Please have a look at the messages `sam2p: Warning: check_rule: ...'
+ to get more specific information. After that, correct your request.
+
+ Solution 2:
+ specify /Compression/IJG /SampleFormat/Rgb8.
+
+ Another cause for this message is that your request cannot be applied
+ to the image you've specified. In this case, there is no relevant
+ `sam2p: Warning: check_rule: ...' message.
+
+ Example 1:
+ you've requested /SampleFormat/Indexed4,
+ but the input image has more than 16 colors.
+
+ Solution 1:
+ specify /SampleFormat/Rgb8.
+
+ Example 2:
+ you've requested /SampleFormat/Indexed4,
+ but the input image has transparency.
+
+ Solution 2:
+ specify /SampleFormat/Transparent8.
+
+ It is possible, but very unlikely that this error message is caused by
+ a bug in sam2p.
+
+Q12. Can I use /Compression/Fax when bits-per-pixel > 1 ?
+
+A12. With /FileFormat/PS* and /FileFormat/PDF*, you can (but you shouldn't,
+ because of the possibly poor compression ratio). With /FileFormat/TIFF,
+ you're not allowed to, because the TIFF specification forbids it.
+ Example one-liners:
+
+ sam2p -s:Indexed8 -c:fax test.gif test.pdf # OK
+ sam2p -s:Indexed8 -c:fax test.gif test.eps # OK
+ sam2p -s:Indexed8 -c:fax test.gif test.tiff # forbidden
+
+Q13. Bad luck?
+
+A13. Not for me.
+
+Q14. Can I use negative margins (i.e /TopMargin -20) to crop the output
+ image?
+
+A14. No. Margins are ignored by sam2p unless /FileFormat is /PSL* or /PDF*.
+ Even with these formats, the image is only moved, not cropped. Please
+ use an image manipulation program (e.g The GIMP) to crop your images
+ before feeding them to sam2p.
+
+Q15. When I try to print the PostScript output of sam2p, the edge of the
+ image is missing (white).
+
+A15. Many printers cannot print to the edge of the paper (so that region is
+ left white). Please increase the margins to a safe value, for example:
+
+ ./sam2p -m:7mm test.ppm test.ps
+ lpr test.ps
+
+ See also {FAQ question Q9} for more information about margins.
+
+Q16. How do I report a bug in sam2p?
+
+A16. Please send an e-mail to the author (pts@fazekas.hu, see more in
+ section {Copyright}) describing the problem. Don't forget to:
+
+ -- download the latest version of sam2p, and try it with the same image
+ -- describe what sam2p does (incorrectly)
+ -- describe what sam2p should do if there was no bug
+ -- run sam2p without arguments, and attach its output (STDOUT) to the
+ bug report
+ -- attach the exact command line with which you call sam2p to the bug
+ report
+ -- if you spot the bug in one-liner mode, specify the `-j' option in
+ the command line, and attach the messages printed by sam2p (both
+ STDOUT and STDERR) to the bug report
+ -- if you spot the bug in job mode, attach the .job file you are using
+ to the bug report
+ -- attach the input image file to the bug report. Try to attach a file
+ as small as possible.
+ -- if sam2p runs successfully (i.e it prints `Success.'), and it
+ creates an output image, but you think that the output image is
+ incorrect, attach the output image to your bug report
+ -- if you have a similar input image, for which sam2p works fine,
+ attach it to the bug report
+
+Q17. How long does the LZW patent held by Unisys last?
+
+A17. mcb@cloanto.com (author of http://lzw.info) wrote:
+
+ Thank you for your interest and mail. I must stress that the "exact"
+ answers you may be looking for may come only from lawyers and courts,
+ and I am none of these. If you consider the IBM, the BT and Unisys US
+ patents, then the last of the three would be the Unisys one, expiring,
+ as the article I think mentions, on June 19, 2003, 24:00. There cannot
+ be other (new) patents on LZW, as far as I know. Please let me know if
+ you find different information.
+
+Q18. I want to create an RGB PostScript image, but sam2p creates a Gray one,
+ or it gives me an error message.
+ For example: `./sam2p -1 -s:rgb1 examples/ptsbanner.gif test.eps'.
+
+A18. /PSL1 doesn't support RGB images. There are two solutions:
+
+ -- Use /PSLC or /PSL2 or /PSL3 instead or drop the '-1'
+ alltogether. Examples:
+
+ ./sam2p -1c -s:rgb1 examples/ptsbanner.gif test.eps # /PSLC
+ ./sam2p -2 -s:rgb1 examples/ptsbanner.gif test.eps # /PSL2
+ ./sam2p -s:rgb1 examples/ptsbanner.gif test.eps # /PSL2 or /PSL3
+
+ -- Use /Mask or /Transparent+. Note that you'll very probably get poor
+ compression ratio.
+
+ ./sam2p -1 -s:tr:stop examples/ptsbanner.gif test.eps # /PSL1
+
+ You can get more (and more useful) error messages from sam2p if you
+ specify the `-j:warn' option. You may also try specifying
+ `-s:rgb1:stop' instead of `-s:rgb1' to force sam2p try /SampleFormat/Rgb1
+ only.
+
+Q19. sam2p doesn't allow me to use /Compression /Fax. For example:
+ `./sam2p -c fax examples/ptsbanner.gif test.eps'. The same command
+ works fine without `-c fax'.
+
+A19. /Compression/Fax is intended to be used with images with 1 bit per
+ pixel. However, in PostScript and PDF, you can use it for any image
+ data, but compression ratio will be very poor for other than /Gray1,
+ /Indexed1 or /Mask, of course. You can force sam2p to use /Fax by
+ specifying the desired SampleFormat in option `-s'. Examples:
+
+ sam2p -s:Indexed8 -c:fax test.gif test.pdf # OK
+ sam2p -s:Indexed8 -c:fax test.gif test.eps # OK
+ sam2p -s:Indexed8 -c:fax test.gif test.tiff # forbidden by TIFF std
+
+ See {FAQ question Q12} for more information.
+
+Q20. Can sam2p convert images with transparency to PDF?
+
+A20. Only if the image has at most 1 non-transprent color
+ (/SampleFormat/Mask). See {FAQ question Q6} for details.
+
+ Although PDF-1.3 supports transparency masks for arbitrary PDF images,
+ sam2p 0.39 doesn't. That's because the author of sam2p hasn't
+ implemented it yet.
+
+Q21. I get the error message `sam2p: Warning: buildProfile: ignoring, no
+ handlers for OutputRule'. Help!
+
+A21. This means that sam2p doesn't know how to do the conversion you've
+ requested (and it even doesn't know whether the request is erroneous or
+ not). This might be because your request is bad (it is impossible to
+ be fulfilled), or your request is good, but sam2p doesn't know how to
+ deal with it. If you think that the latter is the case, please report
+ this message as a bug.
+
+ See {FAQ question Q11} for more information.
+
+Q22. How do I compile with G++ 3.2?
+
+A22. See the answer in section {Compilation and installation}. Don't forget
+
+ export CC=gcc-3.2 CXX=g++-3.2
+
+Q23. How do I do a `make dist' without running configure again?
+
+A23. Just issue
+
+ make MAKE_DIST=1 dist
+
+Q24. I cannot open a JPEG file in the Win32 version.
+
+A24. Make sure you have djpeg.exe on your PATH. Simply copy it to your
+ C:\WINDOWS directory.
+
+Q25. I cannot open a TIFF file in the Win32 version.
+
+A25. Make sure you have tif22pnm.exe on your PATH. Simply copy it to your
+ C:\WINDOWS directory.
+
+Q26. I cannot open a PNG file in the Win32 version.
+
+A26. Make sure you have png22pnm.exe on your PATH. Simply copy it to your
+ C:\WINDOWS directory.
+
+Q27. What is tif22pnm?
+
+A27. tif22pnm is a TIFF -> PNM converter written by the author of sam2p. It
+ can load more TIFF files correctly than tifftopnm, ImageMagick convert,
+ xv and The GIMP. The TIFF loader code is based on GIMP 1.3, but has
+ many bugfixes and improvements. sam2p uses tif22pnm to load TIFF files.
+ You can download tif22pnm from
+
+ https://github.com/pts/tif22pnm
+
+Q28. What is png22pnm?
+
+A28. png22pnm is a PNG -> PNM converter compiled by the author of sam2p. It
+ is based on the excellent pngtopnm utility, but doesn't depend on the
+ NetPBM library (only libpng). sam2p uses png22pnm (or, as a fallback:
+ pngtopm) to load PNG files. png22pnm is part of the tif22pnm package,
+ so you can download it from
+
+ https://github.com/pts/tif22pnm
+
+Q29. Can sam2p convert a transparent GIF to PDF?
+
+A29. The PDF-1.3 file format supports transparent images, but sam2p doesn't.
+ However, if the image contains at most two colors (including the
+ transparent pixel), sam2p can create a working PDF-1.2 file; use
+ Ghostscript to view it, because Acrobat Reader 5.0 is buggy. However,
+ sam2p supports generating transparent EPS, GIF, PNG, PNM, XPM and TIFF
+ files up to 256 colors.
+
+Q30. How do I build my own sam2p debian package?
+
+A30. Please download the newest sources (.tar.gz) from
+
+ https://github.com/pts/sam2p
+
+ As root, run
+
+ apt-get update
+ apt-get install debmake fakeroot dpkg
+ apt-get install make g++ gcc perl sed
+
+ As normal user, run (in the directory containing sam2p_main.cpp):
+
+ debian/rules clean
+ rm -f build*
+ debian/rules build
+ fakeroot debian/rules binary
+ ls -l ../sam2p_*.deb
+
+ As root, substitute X and Y, and run:
+
+ dpkg -i sam2p_X_Y.deb
+
+ Please also install the tif22pnm and png22pnm packages from the author
+ of sam2p (and the Debian standard libjpeg-progs package), available as
+ Debian source from:
+
+ https://github.com/pts/tif22pnm
+
+Q31. Why not use libjpeg/libtiff/libpng/zlib or any other library with
+ sam2p?
+
+A31. -- library and .h incompatibilities (the binary would be less portable
+ across Linux systems)
+ -- to avoid forced dependencies
+ -- checkergcc wouldn't work
+
+Q32. How do I specify the page size when printing a .ps file (-m and -e
+ command line options)?
+
+A32. You cannot. (Use -m to specify the margins.) The page size is
+ autodetected by your printer when the page is
+ printed. So you can print the same .ps file on different printers, and the
+ margins will be all right on all of them.
+
+ If you really have to specify the page size, edit the .ps file and
+ insert the `a4 ' or `letter ' command after the last line of the
+ first block of lines starting with %%. You may also use something like
+ `1 dict dup /PageSize [ 595 842 ] put setpagedevice ' to exactly specify
+ the page width and height in 1/72 inches.
+
+ For example, change the PostScript file
+
+ %!PS-Adobe-3.0
+ %%Pages: 1
+ %%DocumentData: Clean7Bit
+ %%LanguageLevel: 1
+ %%EndComments
+ %%Page: 1 1
+ save
+ ... % many lines omitted
+ %%Trailer
+ %%EOF
+
+ to
+
+ %!PS-Adobe-3.0
+ %%Pages: 1
+ %%DocumentData: Clean7Bit
+ %%LanguageLevel: 1
+ %%EndComments
+ %%Page: 1 1
+ 1 dict dup /PageSize [ 595 842 ] put setpagedevice
+ save
+ ... % many lines omitted
+ %%Trailer
+ %%EOF
+
+ Please note that PostScript is a programming language, so your changes
+ might be undone by instructions later in the file. You might find the
+ a2ping.pl utility (written by the author of sam2p) useful:
+
+ a2ping.pl -v --papersize=a4 in.ps out.ps
+
+Q33. How do I control ZIP compression ratio?
+
+A33. Use
+
+ sam2p -c:zip:1:0 in.img out.png # uncompressed ZIP carrier
+ sam2p -c:zip:1:1 in.img out.png # normal compression
+ sam2p -c:zip:1:9 in.img out.png # maximum compression
+
+Q34. ImageMagick convert creates smaller PNGs. Why?
+
+A34. I don't know the real reason. Probably because ImageMagick uses libpng,
+ which is smarter than sam2p.
+
+ You are probably trying to convert a JPEG or other true color photo to
+ PNG. Try one of the following compression options:
+
+ sam2p -c:zip:12:7 # 464727 bytes
+ sam2p -c:zip:12:8 # 454271 bytes
+ sam2p -c:zip:12:9 # 447525 bytes
+ sam2p -c:zip:13:9 # 488748 bytes
+ sam2p -c:zip:14:9 # 454182 bytes
+ sam2p -c:zip:15:9 # 453080 bytes
+ convert -quality ? # 454438 bytes
+
+Q35. Can sam2p convert large JPEGs to smaller ones (with loss of
+ quality and resolution)?
+
+A35. sam2p cannot resize or scale images. So the pixel width and height of
+ the input and output image cannot be changed. If you need that (for
+ example you want to create thumbnails), use the famous convert(1)
+ utility of ImageMagick. For example:
+
+ convert -scale 444 -quality 50 in.jpg out.jpg # specify out width
+ convert -scale x444 -quality 50 in.jpg out.jpg # specify out height
+ convert -scale "10%" -quality 50 in.jpg out.jpg # specify scale ratio
+
+ However, it is possible to specify the quality of the JPEG output of
+ sam2p. The quality of 0 means ugly output with small file size, and the
+ quality of 100 means nice output with big file sizes. You can specify
+ intermediate integer quality values (50 and 75 are recommended). Be
+ prepared that qualties above 30 (or so) may not work on all JPEG viewers.
+ For example:
+
+ sam2p -c ijg:10 large_input.jpg small_output.jpg
+
+ sam2p uses the cjpeg(1) and djpeg(1) utilities from libjpeg to write
+ and read JPEG files, respectively. If you need more control over your
+ JPEG output, then forget sam2p, and please consult the documentation of
+ those utilities.
+
+Q36. Can sam2p convert JPEG to GIF?
+
+A36. Yes, it can, but usually not directly. GIF allows a maximum of 256
+ different
+ colors in an image. A typical RGB JPEG image contains many more colors,
+ so it has to be quantized down to 256 colors first. For example, if the
+ console output of ``sam2p in.jpg out.gif'' contains ``applyProfile:
+ invalid combination, no applicable OutputRule'', then in.jpg must be
+ quantized first:
+
+ convert in.jpg out1.gif # does the quantization automatically
+ sam2p out1.gif out2.gif # compresses the output image further
+
+ From out1.gif and out2.gif keep the one with the smaller file size. It
+ is common that convert(1) creates huge GIF files because LZW compression
+ is disabled inside it. sam2p should be compiled with LZW compression
+ and GIF input/output enabled. To check this, run sam2p, and
+ examine its console output. It should contain a line:
+
+ Available Appliers: ... GIF89a+LZW ...
+
+ If GIF89a+LZW doesn't appear in the line, please recompile sam2p with:
+
+ make clean
+ ./configure --enable-gif --enable-lzw
+ make
+ cp sam2p /usr/local/bin
+
+ , and try again.
+
+Q37. I need to transform GIF images of 15 colors to BMPs of 256 colors not
+ compressed. sam2p converts it to BMP 16 colors...
+
+A37. Use
+
+ sam2p -c none -s rgb8 in.gif out.bmp
+
+ If you get an error message `Error: applyProfile: invalid combination,
+ no applicable OutputRule', it very probably means that your GIF is
+ transparent. Remove the transparent color within an image editor first.
+
+Q38. Can sam2p _load_ PDF or EPS files?
+
+A38. Yes, if you have Ghostscript installed, and your input EPS file is not
+ too exotic. This has been tested on Linux only. If you experience
+ problems loading EPS files, but no problems loading PDF files, please
+ run a2ping.pl written by the author of sam2p to make your EPS file more
+ compatible.
+
+Q39. Can sam2p load an EPS or PDF file with an arbitrary resoultion?
+
+A39. Yes. For example use one of
+
+ sam2p -l:gs=-r216 in.eps out.png
+ sam2p -l:gs=-r216 in.pdf out.png
+
+ to have resoultion 216 DPI (image scaled 3 times to both directions).
+ Without scaling, 72 DPI is the default.
+
+Q40. Can sam2p emit a multi-page PDF or a multi-page PS?
+
+A40. No, it can't. Emitting a multi-page document would need a fundamental
+ change of the sam2p architecture. (Should the 2nd page be compressed with
+ a different method? What if the 2nd contains too many colors? Should we
+ keep all previous pages in memory?)
+
+ I think another program should be written that is able to concatenate
+ EPS/PS or PDF files. I've already written a PDF-merger called pdfconcat,
+ available from https://raw.githubusercontent.com/pts/pdfconcat/master/pdfconcat.c
+ . An EPS-merger would be even easier. But I don't have time to
+ implement these features directly into sam2p soon.
+
+Q41. Can sam2p read a multi-page TIFF?
+
+A41. sam2p reads only the first page.
+
+ The auxilary utility tif22pnm could be patched so it extracts other
+ pages, and a new command line option can be added to sam2p that passes
+ the required page number to tif22pnm. But I don't have time to
+ implement these features soon.
+
+ By the way, multi-page TIFFs can be created with the following command:
+
+ tiffcp -c g4 d1.tiff d2.tiff d3.tiff output.tiff
+
+Q42. Can sam2p convert a multi-page TIFF to a multi-page PDF?
+
+A42. No. There are two main problems: See also Q40 and Q41.
+
+Q43. How do I convert a TIFF image to a 1-bit black-and-white PDF? Should I
+ use `sam2p -c:fax test.tif test.pdf'?
+
+A43. The above will ensure that fax compression is used. What you need for
+ ensuring that the output is 1-bit black-and-white is:
+
+ sam2p -s:gray1:stop test.tif test.pdf
+
+ You can also specify a compression algorithm (I recommend -c:zip):
+
+ sam2p -c:fax -s:gray1:stop test.tif test.pdf
+ sam2p -c:lzw -s:gray1:stop test.tif test.pdf
+ sam2p -c:zip -s:gray1:stop test.tif test.pdf
+
+ If you get the error message
+
+ sam2p: Error: applyProfile: invalid combination, no applicable OutputRule
+
+ then your input test.tif is not really black-and-white. Open it in an
+ image editing program and ensure that the colors are #000000 and
+ #ffffff only.
+
+ > The tiff is black and white, bilevel - I just want to avoid the
+ > test.pdf from using 8bpp by default (like it does in imagemagick)
+
+ The default for sam2p is not 8bpp. To see what the default is, run sam2p
+ with the `-j' option and check `OutputRule #1' on the console output.
+ What you are interested in is the /SampleFormat field.
+
+Q43. Acrobat Reader (5.0 and 6.0) cannot read the PDFs converted from a JPEG
+ with sam2p. I get the message: `There was an error processing a page.
+ Expected `EI' while parsing an image.'.
+ (The same problem happens with Ghostscript 6.50 with a different error
+ message. xpdf-1.0 reports: bad DCT trailer.)
+
+A43. Very probably the JPEG stream of your original input image file is
+ rejected by the PDF viewers. (In fact, Ghostscript 7.x doesn't
+ complain.) sam2p doesn't do strict JPEG validation when converting JPEG
+ to PDF -- it just blindly assumes that the JPEG file is correct. To
+ ensure this, you have to re-encode the JPEG.
+
+ Instead of this:
+
+ sam2p bad.jpeg bad.pdf
+
+ do this:
+
+ sam2p -c ijg:50 bad.jpeg good.pdf # much slower!
+
+ or this:
+
+ <bad.jpeg djpeg | cjpeg -quality 50 | sam2p - good.pdf
+
+ or this:
+
+ djpeg <bad.jpeg >temp.pnm
+ cjpeg -quality 50 <temp.pnm >temp.jpeg
+ sam2p temp.jpeg good.pdf
+
+ The real reason why Acrobat Reader rejects the JPEG is unknown to me.
+ I also don't know of any baseline JPEG compliance testing software.
+ (But if you re-encode with djpeg and cjpeg, it becomes compliant.)
+
+ (thanks to Thomas Kraemer for reporting the problem)
+
+Q44. How do I create an 1x1 transparent GIF and PNG?
+
+A44. Do
+
+ echo "P1 1 1 0" >one.pbm
+ sam2p -transparent:ffffff one.pbm one.gif
+ sam2p -transparent:ffffff one.pbm one.png
+
+Q45. Is it possible to specify a resolution other than 72 DPI, so that the
+ dimensions of the resulting PDF are accurate for print-resolution images?
+
+A45. Yes, it is. Use `-m:dpi:144' to have the output EPS or PDF scaled to
+ double size, or use `-m:dpi:<real>' to have it scaled by a factor of
+ <real>/72, or 72/-<real>, if <real> is negative.
+
+ If you know that your input image resolution is <res> DPI, and you want
+ to sam2p to create an EPS or PDF keeping the image resolution, you
+ should use `-m:dpi:-<res>'.
+
+ Note that this works only for EPS and PDF output. For all other
+ FileFormat{}s, `-m:dpi:' is ignored. The `-m:dpi:' option doesn't scale
+ the values specified for the other `-m:...' options.
+
+ Some image file formats such as PNG an JPEG can contain resolution
+ information. sam2p ignores this and assumes that the input image
+ resolution is 72 DPI). It would be possible to improve sam2p to use
+ this information, but it would be too much work.
+
+ To proper way of scaling an image, however, is
+ using your DTP or word processor program to resize it properly. For
+ example, after running `sam2p foo.png foo.pdf', in LaTeX, use
+
+ % \usepackage{graphicx}
+ \includegraphics[height=10cm]{foo}
+
+Q46. Is it legal to use LZW compression?
+
+A46. I think so. Also look at Q17.
+
+Q47. Help! I cannot compile it on SunOS/Solaris. I get
+
+ /usr/include/sys/wait.h:90: type specifier omitted for parameter
+ /usr/include/sys/wait.h:90: parse error before `*'
+
+A47. Until someone adds a test to ./configure, try adding the line
+
+ #define siginfo_t void
+
+ to the end of config2.h, just before running `make'.
+
+Q48. Should I run sam2p over all my EPS (or PDF) files, to see if they
+ would become smaller?
+
+A48. No! This is a bad idea in general, because you lose information, since
+ the EPS output of sam2p is always rasterized, so it is not scalable
+ anymore.
+
+ But you may run sam2p over all those EPS files which contain raster
+ graphics. But please be aware that sam2p re-renders everything at 72
+ DPI (can be overridden by `-l:gs=-r<DPI>', and the gs rendering
+ sometimes adjusts RGB color values slightly (+-2 on in the 0..255
+ domain), so there might be quality loss during the _reading_ of the
+ original EPS. There is absolutely no quality loss when sam2p _writes_
+ the EPS.
+
+Q49. Should I run sam2p over all my GIF, TIFF and XPM files, to see if they
+ would become smaller?
+
+A49. Yes, run `sam2p <filename> --' if you have a backup copy of the
+ original. Otherwise, choose a different filename for output.
+
+Q50. Should I run sam2p over all my PNG files, to see if they
+ would become smaller?
+
+A50. You might try it, there will be no quality loss, but the general
+ experience of the author is that the tools using libpng (e.g. pnmtopng)
+ produce slightly smaller PNG than sam2p. If you are an image
+ compression specialist, please help the author to find the reason of
+ this, and enhance sam2p.
+
+Q51. Should I run sam2p over all my JPEG files, to see if they
+ would become smaller?
+
+A51. sam2p doesn't change the file by default. Use the `-c:ijg' option
+ (possibly with a JPEG quality parameter, e.g. `-c:ijg:50') to make
+ sam2p re-encode the JPEG. This is a lossy operation, and the size of
+ the output file depends on quality parameter specified, so it might
+ actually become larger than the original. Please also note that JPEG
+ meta-information (such as EXIF tags inserted by digital cameras) gets
+ completely lost with `-c:ijg'.
+
+Q52. How do I use ZIP (Deflate) compression in LanguageLevel 2?
+
+A52. Run this:
+
+ sam2p -c:zip PSL2: in.image out.eps
+
+ This will make sam2p emit the image decoding procedure so the image
+ will be viewable (veeeery slowly) on LanguageLevel 2 devices, too. It
+ doesn't affect the rendering speed on LanguageLevel 3 devices.
+
+Q53. How do I create a GIF from an image with more than 256 colors?
+
+A53. You need the pnmquant utility too from NetPbm. Run this:
+
+ sam2p in.image PPM:- | pnmquant 256 | sam2p - out.gif
+
+ Or, if you have the convert utility from ImageMagick, run:
+
+ sam2p in.image PPM:- | convert - out.gif
+
+Q54. What is the maximum image size sam2p supports?
+
+A54. As of version 0.45, the following limits apply for input images:
+
+ -- Input image height times image width must be <= 2000000000 pixels.
+ Individual dimensions can be as high as necessary.
+ -- Input image memory must be <= 1000000000 bytes (1 GiB). The memory is
+ computed by multiplying image width, image height and BPC. BPC is
+ number of bytes per pixels. It is 3 for RGB images, 1 for grayscale
+ and indexed (256-color palette) images. For some temporary
+ calculations BPC might go up to 3 even if it is smaller than 3 in
+ the input image, so to be safe, always assume that BPC is 3 in image
+ memory calculations.
+ -- For JPEG input or ouput, image width and height must be <= 65535
+ pixels.
+ This is an inherent limitation in the JPEG file format.
+
+ In earlier versions (0.44 or below) the following additional limits
+ applied:
+
+ -- Image width must be <= 65535 pixels.
+ -- Image height must be <= 65535 pixels.
+
+ sam2p is a fast image conversion tool: it isn't unnecessarily slow on
+ large images. Its speed is predictable for uncompressed images: it
+ slows down proportionally to the input image memory (see the
+ calculation below).
+
+Q55. How do I get the smallest PNG output?
+
+A55. If your input image is truecolor, please consider a lossy compression
+ file format (such as JPEG), because the ZIP compression used in PNG is
+ not particularly well-suited for truecolor images.
+
+ If your input image has only a few colors, specify `-c zip:25:9', which
+ forces the ZIP compression whith a high effort (9) and predictor
+ autodetection (25). This is considerably slower than not specifying any
+ `-c' flag at all, and getting `-c zip:25', because the high effort (9)
+ is slower than the default effort. Please note that `-c zip:25:9'
+ disables the predictor unless the SampleFormat is Rgb8 or Gray8. (This
+ is the same what libpng-1.2.15 does by default.) For large images (of
+ Rgb{1,2,4,8} or Gray{1,2,4,8}), you may want to specify `-c zip:15:9'
+ to forcibly enable the predictor, being autodetected for each image
+ row.
+
+ Please also note that the free software ``optipng'' and the free-to-use
+ closed-source software PNGOUT (for Win32, Linux and Mac OS X) can
+ produce PNGs about 10% smaller than what sam2p produces -- but they are
+ a 100 times (or even more) slower than sam2p. The tool ``pnmtopng''
+ (tested with one linked to libpng 1.2.20) does not produce smaller PNGs
+ than sam2p >= 0.46. For older versionf of sam2p, the output of
+ ``pnmtopng'' was about 5--10% smaller.
+
+ Please also note that the the PNG output of Ghostscript -sDEVICE=pngmono
+ etc. is not optimal. Convert it with sam2p or the tools mentioned above
+ to reduce the file size.
+
+Q56. How do I get the smallest PDF output?
+
+A56. If your input image is truecolor, specify `-c jpeg', possibly tuning it
+ with a low quality parameter e.g. `-c jpeg:30'.
+
+ If your input image has only a few colors, specify `-c zip:25:9' or
+ `-c zip:15:9', see also Q55.
+
+ Please also have a look at Q55. Unfortunately, sam2p doesn't yet
+ support calling external PNG optimizers and converting their output to
+ PDF.
+
+Q57. Does sam2p convert images to canonical form, i.e. if I have two
+ source images with identical width, height and RGB8 pixel
+ representation, and I convert both with sam2p with the same flags,
+ will the two output image files be byte-by-byte identical?
+
+A57. Yes, since version 0.46-2.
+
+ The only code code needed for that was sorting the indexed palette.
+
+ For blackbox input images which sam2p doesn't decompress (e.g. JPEG
+ with /Compression/JAI), the output is only guaranteed to be
+ byte-byte-byte identical, if the input was byte-byte-byte identical.
+
+Q58. Can sam2p generate a PDF which is scaled proportionally (i.e. keeping
+ the aspect ratio) to a specified page size, and centered on the page?
+
+A58. No, but the Perl script sam2p_pdf_scale.pl bundled with sam2p can
+ post-process the file created by sam2p. For example, to scale and
+ center a PDF on an A4 paper, do:
+
+ $ sam2p input.img output.pdf
+ $ sam2p_pdf_scale.pl 595 842 output.pdf
+
+ Please also have a look at the LaTeX package pdfpages.sty for more
+ options. It can also be used to concatenate multiple PDFs.
+ Its documentation:
+ http://www.ctan.org/get/macros/latex/contrib/pdfpages/pdfpages.pdf
+
+ Example output.tex file:
+
+ \documentclass{article}
+ \pdfcompresslevel9
+ \paperwidth 21cm \pdfpagewidth\paperwidth
+ \paperheight29.7cm \pdfpageheight\paperheight
+ \usepackage{pdfpages}
+ \begin{document}
+ \includepdf{output_tmp.pdf}
+ \end{document}
+
+ How to compile the .tex file above:
+
+ $ sam2p input.img output_tmp.pdf
+ $ pdflatex output.tex
+
+ Please note that a2ping.pl or pdftk won't work either.
+
+Q59. How does sam2p detect the bounding box of PostScript and EPS input?
+
+A59. For PostScript input, the paper size specified in the PostScript code
+ is used, reverting to the system's default paper size if missing.
+ PostScript input is detected by finding `%!PS-Adobe-' at the beginning
+ of the file, but `EPSF-' missing from the first line. Paper size can be
+ specified in the PostScript code using `<</PageSize[...]>> setpagedevice', 'a4', `letter' etc.
+ The comments `%%BoundingBox:' etc. are ignored.
+
+ For EPS input, the `%%ExactBoundingBox:' is used, reverting to
+ `%%HiResBoundingBox:', reverting to `%%BoundingBox:', reverting to the
+ system's default paper size. The paper size specified in the PostScript
+ code is ignored. EPS input is detected by finding `%!PS-Adobe-' at the
+ beginning of the file and `EPSF-' in the first line. When converting to
+ PostScript, EPS or PDF, the (in.llx, in.lly) coordinates of the input
+ bounding box are not preserved: the output file will always have (0, 0)
+ as its lower left corner and (in.urx-in.llx, in.ury-in.lly) as its
+ upper right corner.
+
+Q60. When compiling sam2p, the ./configure command prints an error:
+ ``running make Makedep... error configure: error: cannot compute depends''
+
+A60. Please download the newest sam2p:
+
+ $ git clone https://github.com/pts/sam2p
+
+ , and run ./configure again. If it still
+ fails, please report the issue on https://github.com/pts/sam2p/issues ,
+ and attach the config.log file generated by ./configure to your report.
+
+ Some more detailed analysis: ./configure runs `make Makedep', which
+ runs `perl -x -S ./ccdep.pl --FAL=assert,no,yes,checker g++', which
+ runs g++ to analyze the dependencies between .cpp files, and analyzes
+ the error and warning messages printed by g++. Newer versions of g++
+ (and clang++, which is typically run instead of g++ on macOS) tend to
+ print more warnings, which ccdep.pl doesn't understand, and fails.
+
+ Work is being done to make ccdep.pl more resilient
+ (https://github.com/pts/sam2p/issues/5).
+
+Standards
+~~~~~~~~~
+-- PSL1 is PostScript LanguageLevel1, as defined by Adobe's PostScript
+ Language Reference Manual.
+-- PSLC is PSL1 with the CMYK extension (including the `colorimage'
+ operator). Supersedes PSL1.
+-- PSL2 is PostScript LanguageLevel2, as defined by Adobe's PostScript
+ Language Reference Manual. Supersedes PSLC.
+-- PSL3 is PostScript LanguageLevel3, as defined by Adobe's PostScript
+ Language Reference Manual (PLRM.pdf). Supersedes PSL2.
+-- PDF1.0 is PDF version 1.0, as defined by Adobe's PDF Reference.
+-- PDF1.1 is PDF version 1.1, as defined by Adobe's PDF Reference.
+ Supersedes PDF1.0.
+-- PDF1.2 is PDF version 1.2, as defined by Adobe's PDF Reference.
+ Supersedes PDF1.1.
+-- PDF1.3 is PDF version 1.3, as defined by Adobe's PDF Reference.
+ Supersedes PDF1.2.
+-- PDF1.4 is PDF version 1.4, as defined by Adobe's PDF Reference
+ (PDFRef.pdf). Supersedes PDF1.3.
+-- PDF1.5 is PDF version 1.4, as defined by Adobe's PDF Reference
+ (PDFRef.pdf). Supersedes PDF1.4.
+-- PBM is Portable Bitmap file format, as defined in NetPBM's pbm(5) UNIX
+ manual page.
+-- PGM is Portable Graymap file format, as defined in NetPBM's pgm(5) UNIX
+ manual page.
+-- PPM is Portable Pixmap file format, as defined in NetPBM's ppm(5) UNIX
+ manual page.
+-- PNM is Portable Anymap file format, as defined in NetPBM's pnm(5) UNIX
+ manual page. It is the union of PGM, PPM and PPM.
+-- PAM is the new, Portable ...map file format, as defined in NetPBM's pam(5)
+ UNIX manual page. We don't support it yet.
+-- TIFF is ... v6.0.
+-- JPEG is baseline JPEG JFIF file format as defined by the Joint Picture
+ Expert Group.
+-- PNG is Portable Network Graphics file format v1.0, as defined by
+ RFC 2083.
+
+Compatibility notes
+~~~~~~~~~~~~~~~~~~~
+by pts@fazekas.hu at Wed Nov 14 12:14:15 CET 2001
+Fri Mar 22 11:48:36 CET 2002
+Sat Apr 20 19:57:44 CEST 2002
+Fri Feb 7 11:15:39 CET 2003
+
+-- Ghostscript 6.50 has problems with /FileFormat/PDFB1.0
+ /SampleFormat/JAI|/IJG/DCT
+ (Error: /syntaxerror in ID). The problem has been fixed in Ghostscript
+ 7.04. With the buggy Ghostscript use /FileFormat/PDF1.0 instead.
+-- /FileFormat/PDF[B]1.0 /SampleFormat/Mask|/Indexed1 doesn't
+ work on Acrobat Reader 5.0 on Linux: a fully opaque, one-color rectangle is
+ painted. This works fine on gs 6.50 and xpdf 1.0, so Acrobat Reader is
+ assumed to be buggy.
+-- The GIMP 1.0 cannot load PlanarConfig Separated TIFF images of type
+ GrayA. (But can load PlanarConfig Contiguous GrayA.)
+-- xv cannot display gray TIFF images with transparency.
+ xv: Sorry, can not handle 2-channel images.
+-- (lib)tiff FAX compression an PS /CCITTFaxEncode have black and white the
+ opposite way. So `/CCITTFaxEncode <</BlackIs1 true>>' has to be applied
+ when creating a TIFF file.
+-- libtiff 3.5.4 doesn't read or write an indexed image with transparency:
+ Sorry, can not handle contiguous data with PhotometricInterpretation=1,
+ and Samples/pixel=2. (Doesn't work with convert or GIMP.)
+-- libtiff 3.5.4 doesn't read or write a gray with transparency:
+ Sorry, can not handle contiguous data with PhotometricInterpretation=2,
+ and Samples/pixel=2. (Doesn't work with convert, works with GIMP.)
+-- libtiff doesn't read or write TIFFTAG_SUBFILETYPE/FILETYPE_MASK +
+ TIFFTAG_PHOTOMETRIC/PHOTOMETRIC_MASK. One has to use TIFFTAG_EXTRASAMPLES
+ instead.
+-- libtiff (and the TIFF file format) supports only /Predictor 1 and
+ /Predictor 2, with /Compression/LZW and /Compression/ZIP.
+-- libtiff supports only bpc=8 and bpc=16 with /Predictor 2
+-- libtiff and most TIFF-handling utils have buggy support for TIFF/JPEG.
+ See FAQ answer Q4.
+-- libtiff supports only files with all components having the same
+ BitsPerSample.
+-- acroread 4.0 can display all possible /Predictor values with /Indexed1.
+-- Ghostscript 5.50 renders (PDF?) images inaccurately: the last bit of
+ the 8-bit palette sometimes gets wrong.
+-- Netscape Navigator 4.7 displays transparent PNG images with their bKGD
+ (or an arbitrary color if bKGD not present) as a solid background. This
+ is a bug.
+-- pdftops 0.92 has serious problems displaying images if /Predictor != 1.
+ The image will be obscured without an error message. Ghostscript 5.50 and
+ Acrobat Reader 4 do not have such problems.
+-- Ghostscript 5.50 cannot display a PDF with /ColorSpace[/Indexed/DeviceRGB
+ ...]. Acrobat Reader 4, Ghostscript 7.04 and pdftops 0.92 can.
+-- /Decode is not required in PDF.
+-- GIMP 1.0 completely ignores the PNG tRNS chunk! (Thus it won't recognise
+ such a transparency in PNG.) Use `pngtopnm -alpha' instead!
+-- pngtopnm honors the PNG bKGD chunk only if called as `pngtopnm -mix'
+ (and does mixing)
+-- convert honors the PNG bKGD chunk (and does mixing)
+-- display doesn't honor the PNG bKGD chunk, but has `-bg' command line option
+-- xv honors the PNG bKGD chunk (and does mixing)
+-- PDF procsets (subsection 8.1 of PDFRef.pdf)
+ /PDF
+ /Text
+ /ImageB Grayscale images or image masks
+ /ImageC Color images
+ /ImageI Indexed (color-table) images
+-- Ghostscript always requires the /Decode entry in image dicts
+-- /DCTEncode and /DCTDecode supports only BitsPerComponent==8.
+-- Actually PostScript supports 1,2,4,8,12 BitsPerComponent. PDF1.3 supports
+ only 1,2,4,8. We support only 1, 2, 4 and 8.
+-- PostScript also supports the CMYK color space, not just gray and RGB.
+ (And also the HSB, which can be transformed to RGB in an ugly way.)
+-- PostScript supports PNG predictors to enhance compression.
+-- The PLRM 4.10.6 describes a trick with patterns and imagemask to do
+ transparent images. Unfortunately this doesn't work in Ghostscript 5.50
+ and xpdf 0.92 (but it works in acroread 4.0), so we don't use it. That's
+ why we have only two *-transparent-* entries.
+-- ImageMagick EPSI is an EPS with preview (%%BeginPreview .. %%EndPreview)
+-- ImageMagick EPSF and EPS are equivalent
+-- ImageMagick EPS* is incredibly slooow because of the bad design, even for
+ LanguageLevel 2.
+-- ImageMagick EPS* cannot display color images without the colorimage
+ opertor. (We could do some trickery with multiple calls to imagemask.)
+-- tiff2ps cannot display color images without the colorimage
+ opertor. (We could do some trickery with multiple calls to imagemask.)
+-- Timing: 1495 x 935 RGB, gs -sDEVICE=bmp16m -sOutputFile=/dev/null
+ time gs -q -sDEVICE=ppmraw -sOutputFile=t.ppm $IN.eps </dev/null
+ ImageMagick 6620 ms user
+ tiff2ps-readhexstring 2320 ms user
+ currentfile-colorimage 2120 ms user
+ readstring-colorimage 2170 ms user
+ currentfile-/FlateDecode-colorimage 2670 ms user
+-- There is a NullEncode filter, but NullDecode doesn't exist
+-- speed conclusions:
+ 1. Use currentfile as data source (LanguageLevel2) if possible.
+ 2. /FlateDecode adds a 25% speed penalty. But it compresses quite well,
+ so use it!
+-- PostScript LanguageLevel2 supports the indexed color space:
+
+ /colormap colors 3 mul string def
+ currentfile colormap readhexstring pop pop
+ [ /Indexed /DeviceRGB colors 1 sub colormap ] setcolorspace
+
+-- EPS comments: (ImageMagick)
+
+ %%DocumentData: Clean7Bit
+ %%LanguageLevel: 1
+
+-- PSL1/PSL2 supports the following color setting operators: (all operands
+ are between 0.0 and 1.0)
+
+ <num> setgray currentgray % PSL1, 0.0=black 1.0=white
+ <hue> <saturation> <brightness> sethsbcolor % PSL1
+ <red> <green> <blue> setrgbcolor % PSL1
+ <cyan> <magenta> <yellow> <black> setcmykcolor % PSL2; not in PSL1
+
+__END__