1SNG(1)                           User Commands                          SNG(1)
2
3
4

NAME

6       sng - compiler/decompiler for Scriptable Network Graphics
7

SYNOPSIS

9       sng [-vV] [file...]
10

DESCRIPTION

12       The sng program translates between PNG (Portable Network Graphics)
13       format and SNG (Scriptable Network Graphics) format. SNG is a printable
14       and editable minilanguage for describing PNG files. With sng, it is
15       easy to view and edit exotic PNG chunks not supported by graphics
16       editors; also, since SNG is easy to generate from scripts, sng may be
17       useful at the end of a pipeline that programmatically generates PNG
18       images.
19
20       An SNG description consists of a series of chunk specifications in a
21       simple editable text format. These generally correspond one-for-one to
22       PNG chunks. There is one exception; the IMAGE chunk specification is
23       automatically translated into an IDAT chunk (doing appropriate
24       interlacing, compression, etcetera).
25
26       Given no file arguments, sng translates stdin to stdout. In this mode,
27       it checks the first character. If that character is printable, the
28       input stream is assumed to contain SNG; sng looks for an #SNG leader
29       and tries to translate the file to PNG. If the character is
30       non-printable, the input stream is assumed to contain PNG; sng tries to
31       translate it to SNG.
32
33       For each file that sng operates on, it does its conversion according to
34       the file extension (.png or .sng). The result file has the same name
35       left of the dot as the original, but the opposite extension and type.
36
37       The -V option makes sng identify itself and its version, then exit.
38       The -v option makes sng report on what files it is converting.
39

SNG LANGUAGE SYNTAX

41       In general, the SNG language is token-oriented with tokens separated by
42       whitespace. Anywhere that whitespace may appear, a `#' comment leader
43       causes all characters up to the next following newline to be ignored.
44       The characters `:' and `;' are treated as whitespace, except the `;'
45       terminates a data element (see below).
46
47       In the syntax descriptions below, lines between {} may occur in any
48       order. Elements bracketed in [] are optional; a sequence bracketed by
49       []* may be repeated any number of times. Elements separated by | are
50       alternatives. Elements separated by plus signs are an attribute set;
51       any sequence of one or more of those element tokens is valid.
52
53       The elements <byte>, <short>, <long>, <float>, <string> are byte
54       numeric, short-integer numeric, long-integer numeric, and float numeric
55       literals respectively (all unsigned). The <slong> element is a signed
56       long-numeric literal. All numerics use C conventions; that is, they are
57       decimal unless led by 0x (hex) or 0 (octal).
58
59       The element <string> is any number of doublequote-delimited character
60       string literals. C-style escapes (\n, \t, \b, \r or \ followed by octal
61       or hex digits) are interpreted. The result is the concatenation of all
62       the literals.
63
64       The element <keyword> is a doublequote-delimited PNG keyword; that is,
65       a string of no more than 79 printable Latin-1 characters or spaces,
66       with no leading and no trailing and no consecutive spaces.
67
68       A <data> element consists of a sequence of byte specifications in any
69       of the following formats. Either '}' or ';' ends a data literal; `}'
70       also ends the enclosing chunk.
71
72       1.  string format is an SNG string literal or sequence of string
73       literals (see above). The bytes of data are the string contents.
74
75       2.  base64 format is signaled by the leading token `base64'. This
76       encoding can only be used when the values of all bytes is less than 64.
77       It encodes each byte as a single character, with decimal digits
78       representing values 0-9, followed by A-Z for 10-35, followed by a-z for
79       36-61, followed by + for 62 and / for 63. Base64 format can be used if
80       the image either has total (color plus alpha) bit depth of four or
81       less, or it is a spaletted image with 64 or fewer colors. Whitespace is
82       ignored. Note that this encoding is only very loosely related to
83       RFC2045 base-64 encoding, which uses a different mapping of bytes to
84       values, and supports encoding of arbitrary binary data.
85
86       3.  hex format is signaled by the leading token `hex'. In hex format,
87       each byte is specified by two hex digits (0123456789abcdef), most
88       significant first. Whitespace is ignored.
89
90       4.  P1 format is Portable Bit Map (PBM) format P1. A decimal height and
91       width follow; it is a fatal error for them to fail to match the IHDR
92       dimensions. Following this, the only non-whitespace charaters are
93       expected to be `0' and `1', with the obvious values. Whitespace is
94       ignored.
95
96       5.  P3 format is Portable Pixel Map (PPM) format P3. A decimal height
97       and width follow; it is a fatal error for them to fail to match the
98       IHDR dimensions. A maximum channel value in decimal follows; it is a
99       fatal error for any following channel value to exceed this value.
100       Following this are triples of decimal channel values representing RGB
101       triples. Whitespace separates decimal channel values but is otherwise
102       ignored.
103
104       An <rgb> element may be expanded to:
105
106           (<byte>, <byte>, <byte>) | <string>
107
108       That is, it is either a paren-enclosed list of RGB values or a string
109       naming a color named in the X RGB database. Note that color names are
110       not necessarily portable between hosts or even displays, due to
111       different screen gammas and colorimetric biases. For this reason, the
112       SNG decompiler generates color names in comments.
113
114       IMAGE segments contain unpacked and uninterlaced raster data. There
115       will be exactly one IMAGE per SNG dump, containing the pixel data from
116       all IDAT chunks, unless the -i option is on. In that case, there will
117       be multiple IDAT chunks containing raw (compressed) image data.
118
119       The options member of an IMAGE chunk (if present) sets image write
120       transformations, supplying the third argument of the png_write_png()
121       call used for output. Note that for images with a bit depth of less
122       than 8, there is a default `packing' transformation. Consult the
123       libpng(3) manual page for details.
124
125       Every SNG file must begin with the string "#SNG", followed by optional
126       SNG version information, followed by a colon (`:', ASCII 58) character.
127       The remainder of the first line is ignored by SNG.
128
129       Comments in the syntax diagram describe intended semantics. This
130       specification should be read in conjunction with the PNG standard.
131
132           IHDR {
133              height <long>
134              width <long>
135              bitdepth <byte>
136              [using grayscale+color+palette+alpha]
137              [with interlace]           # Adam7 assumed if interlacing on
138           }
139
140           PLTE {
141              [<rgb>]*                   # RGB triples or X color names
142           }
143
144           IDAT {
145              <data>
146           }
147
148           gAMA {<float>}
149
150           cHRM {
151              white (<float>,<float>)      # White point x and y
152              red (<float>,<float>)
153              green (<float>,<float>)
154              blue (<float>,<float>)
155           }
156
157           sRGB {<byte>}                   # Colorimetry intent, range 0-3
158
159           iCCP {                          # International Color Consortium profile
160              name <keyword>
161              profile <data>
162           }
163
164           sBIT {
165              red <byte>                   # Color images only
166              blue <byte>                  # Color images only
167              green <byte>                 # Color images only
168              gray <byte>                  # Grayscale images only
169              alpha <byte>                 # Images with alpha only
170           }
171
172           bKGD {
173              red <short>                  # Color images only
174              blue <short>                 # Color images only
175              green <short>                # Color images only
176              gray <short>                 # Grayscale images only
177              index <byte>                 # Paletted images only
178           }
179
180           hIST {
181              <short> [, <short>]*         # Count must match palette size
182           }
183
184           tRNS {
185              [gray <short>]               # Grayscale images only
186              [red <short>]                # True-color images only
187              [green <short>]              # True-color images only
188              [blue <short>]               # True-color images only
189              [<byte>]*                    # Paletted images only
190           }
191
192           pHYs {
193              xpixels <long>
194              ypixels <long>
195              [per meter]
196           }
197
198           tIME {
199              year <short>
200              month <byte>
201              day <byte>
202              hour <byte>
203              minute <byte>
204              second <byte>
205           }
206
207           tEXt {                          # Ordinary text chunk
208             keyword <keyword>
209             text <string>
210           }
211
212           zTXt {                          # Compressed text chunk
213             keyword <keyword>
214             text <string>
215           }
216
217           iTXt {                          # International UTF-8 keyword
218             language <keyword>
219             keyword <keyword>
220             translated <keyword>          # Translation of the keyword
221             text <string>
222             [compressed]
223           }
224
225           oFFs {
226             xoffset <slong>
227             yoffset <slong>
228             [unit pixels|micrometers]*
229           }
230
231           sPLT {
232              name <keyword>
233              depth <byte>
234              [<rgb>, <short>, <short>]*    # Color followed by alpha and frequency
235           }
236
237           pCAL {
238              name <keyword>
239              x0 <slong>
240              x1 <slong>
241              mapping linear|euler|exponential|hyperboli   unit <string>
242              [parameters <string>]
243           }
244
245           sCAL {
246              unit meter|radian
247              width <string>
248              height <string>
249           }
250
251           IMAGE {
252              options identity+packing+packswap+invert_mono
253                         +shift+bgr+swap_alpha+invert_alpha+swap_endian+strip_filler
254              pixels <data>
255           }
256
257           gIFg {
258              disposal <byte>
259              input <byte>
260              delay <short>
261           }
262
263           gIFx {
264              identifier <string>                # Must be 8 characters
265              code <string>                      # Must be 3 characters
266              data <data>
267           }
268
269           private <string> {                    # Private chunk declaration
270              <data>
271           }
272

BUGS

274       The -i option doesn't work yet, and won't until libpng's ability to
275       suppress special handling of IDATs is working. See the distribution
276       TODO file for other minor problems.
277

FILES

279       rgb.txt
280           The X colorname database, used for RGB-to-name mappings in the
281           decompiler and name-to-RGB mappings in the compiler.
282

SEE ALSO

284       pbm(5), ppm(5).
285

AUTHOR

287       Eric S. Raymond <esr@snark.thyrsus.com> December 1999. The SNG home
288       page is at http://sng.sourceforge.net/.
289
290       For more information about PNG, see the PNG website at
291       <http://www.libpng.org/pub/png/>.
292
293       The W3C recommendation is Portable Network Graphics (PNG) Specification
294       (Second Edition)[1]. The PNG specification is also ISO/IEC 15948.
295

NOTES

297        1. Portable Network Graphics (PNG) Specification (Second Edition)
298           http://www.w3.org/TR/2003/PR-PNG-20030520/index-noobject.html
299
300
301
302Open Source                       01/12/2016                            SNG(1)
Impressum