-
Notifications
You must be signed in to change notification settings - Fork 16
/
README
2868 lines (2306 loc) · 116 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
-*- coding: UTF-8 -*-
README for sam2p
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 -e:false : /Scale/None
-- -e -e:1 -e:scale -e:true : /Scale/OK
-- -e:rot -e:rotate : /Scale/RotateOK
-- -e:(false-bool) : /Scale/None
-- -e:(true-bool) : /Scale/OK
-- 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:zip:25:9 : [pts,tiffcp] ZIP, maximum effort, best predictor
-- -c:zip:(1..99):(-1..9) : [pts] hint /Compression/ZIP /Predictor ... /Effort ...
-- -c:zip:(1..99) : [pts] same as -c:zip(1..99):5
-- -c:zip : [pts,tiffcp] same as -c:zip:1:5
-- -c:lzw:25 : [pts] LZW, best predictor
-- -c:lzw:(1..99) : [pts] hint /Compression/LZW /Predictor ...
-- -c:lzw : [pts,tiffcp] same as -c:lzw:1
-- -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:
-- TL;DR You need these tools on the $PATH: sh perl g++ as ld
-- a UNIX system
-- sh: a Bourne-compatible shell (preferably GNU Bash >=2.0, but can be dash,
ksh, zsh, busybox sh or others)
-- g++: 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, g++-4.0,
g++-4.4, g++-4.8, g++-6.3, g++-7.3)
-- perl: Perl >=5.004 (no external Perl modules are required)
-- (optional) make: GNU Make
-- (optional) autoconf: GNU autoconf >=2.53 (version number is important,
see AC_C_CONST)
-- (not required): the following libraries are _not_ required: libjpeg,
libtiff, libpng, libungif, PDFlib, zlib, libm
Compilation (it creates the executable file sam2p):
sh compile.sh
If it doesn't work with your sh, you may want to try bash instead.
Alternative compilation if you don't want to link against libstdc++:
sh compile_minigxx.sh
Alternative compilation for some targets, including cross-compilation: use
the ./compile_*.sh scripts.
If you want to use the ./configure script, run
#sh configure --enable-gif --enable-lzw # optional, make does it
make
# the stand-alone utility `./sam2p' is now built
make install # optional, may not work
If you have GNU Make as gmake on the $PATH, run this:
sh configure MAKE=gmake --enable-gif --enable-lzw # optional, gmake does it
gmake
# the stand-alone utility `./sam2p' is now built
gmake 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 <[email protected]>. 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