.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "SNG" 1 "" "" ""
.SH NAME
sng \- compiler/decompiler for Scriptable Network Graphics
.SH "SYNOPSIS"
.ad l
.hy 0
.HP 4
\fBsng\fR [\-ivV] [\fIfile\fR...]
.ad
.hy

.SH "DESCRIPTION"

.PP
The \fBsng\fR program translates between PNG (Portable Network Graphics) format and SNG (Scriptable Network Graphics) format\&. SNG is a printable and editable minilanguage for describing PNG files\&. With sng, it is easy to view and edit exotic PNG chunks not supported by graphics editors; also, since SNG is easy to generate from scripts, sng may be useful at the end of a pipeline that programmatically generates PNG images\&.

.PP
An SNG description consists of a series of chunk specifications in a simple editable text format\&. These generally correspond one\-for\-one to PNG chunks\&. There is one exception; the IMAGE chunk specification is automatically translated into an IDAT chunk (doing appropriate interlacing, compression, etcetera)\&.

.PP
Given no file arguments, \fBsng\fR translates stdin to stdout\&. In this mode, it checks the first character\&. If that character is printable, the input stream is assumed to contain SNG; \fBsng\fR looks for an #SNG leader and tries to translate the file to PNG\&. If the character is non\-printable, the input stream is assumed to contain PNG; \fBsng\fR tries to translate it to SNG\&.

.PP
For each file that \fBsng\fR operates on, it does its conversion according to the file extension (\&.png or \&.sng)\&. The result file has the same name left of the dot as the original, but the opposite extension and type\&.

.PP
The \-V option maskes \fBsng\fR identify itself and its version, then exit\&. The \-i option causes IDAT chunks in a PNG to be dumped in raw form as IDAT chanks rather than as a reassembled IMAGE\&. The \-v option makes \fBsng\fR report on what files it is converting\&.

.SH "SNG LANGUAGE SYNTAX"

.PP
In general, the SNG language is token\-oriented with tokens separated by whitespace\&. Anywhere that whitespace may appear, a `#' comment leader causes all characters up to the next following newline to be ignored\&. The characters `:' and `;' are treated as whitespace, except the `;' terminates a data element (see below)\&.

.PP
In the syntax descriptions below, lines between {} may occur in any order\&. Elements bracketed in [] are optional; a sequence bracketed by []* may be repeated any number of times\&. Elements separated by | are alternatives\&. Elements separated by plus signs are an attribute set; any sequence of one or more of those element tokens is valid\&.

.PP
The elements <byte>, <short>, <long>, <float>, <string> are byte numeric, short\-integer numeric, long\-integer numeric, float numeriliterals respectively (all unsigned)\&. The <slong> element is a signed long\-numeric literal\&. All numerics use C conventions; that is, they are decimal unless led by 0x (hex) or 0 (octal)\&.

.PP
The element <string> is any number of doublequote\-delimited character string literals\&. C\-style escapes (\\n, \\t, \\b, \\r or \\ followed by octal or hex digits) are interpreted\&. The result is the concatenation of all the literals\&.

.PP
The element <keyword> is a doublequote\-delimited PNG keyword; that is, a string of no more than 79 printable Latin\-1 characters or spaces, with no leading and no trailing and no consecutive spaces\&.

.PP
A <data> element consists of a sequence of byte specifications in any of the following formats\&. Either '}' or ';' ends a data literal; `}' also ends the enclosing chunk\&.

.PP
1\&. string format is an SNG string literal or sequence of string literals (see above)\&. The bytes of data are the string contents\&.

.PP
2\&. base64 format is signaled by the leading token `base64'\&. It is RFC2045 base\-64 encoding, with decimal digits representing values 0\-9, followed by A\-Z for 10\-35, followed by a\-z for 36\-61, followed by + for 62 and / for 63\&. Base64 format can be used if the image either has total (color plus alpha) bit depth of four or less, or it is a spaletted image with 64 or fewer colors\&. Whitespace is ignored\&.

.PP
3\&. hex format is signaled by the leading token `hex'\&. In hex format, each byte is specified by two hex digits (0123456789abcdef), most significant first\&. Whitespace is ignored\&.

.PP
4\&. P1 format is Portable Bit Map (PBM) format P1\&. A decimal height and width follow; it is a fatal error for them to fail to match the IHDR dimensions\&. Following this, the only non\-whitespace charaters are expected to be `0' and `1', with the obvious values\&. Whitespace is ignored\&.

.PP
5\&. P3 format is Portable Pixel Map (PPM) format P3\&. A decimal height and width follow; it is a fatal error for them to fail to match the IHDR dimensions\&. A maximum channel value in decimal follows; it is a fatal error for any following channel value to exceed this value\&. Following this are triples of decimal channel values representing RGB triples\&. Whitespace separates decimal channel values but is otherwise ignored\&.

.PP
An <rgb> element may be expanded to:

(<byte>, <byte>, <byte>) | <string>

.PP
That is, it is either a paren\-enclosed list of RGB values or a string naming a color named in the X RGB database\&. Note that color names are not necessarily portable between hosts or even displays, due to different screen gammas and colorimetric biases\&. For this reason, the SNG decompiler generates color names in comments\&.

.PP
IMAGE segments contain unpacked and uninterlaced raster data\&. There will be exactly one IMAGE per SNG dump, containing the pixel data from all IDAT chunks, unless the \-i option is on\&. In that case, there will be multiple IDAT chunks containing raw (compressed) image data\&.

.PP
The options member of an IMAGE chunk (if present) sets image write transformations, supplying the third argument of the png_write_png() call used for output\&. Note that for images with a bit depth of less than 8, there is a default `packing' transformation\&. Consult the libpng(3) manual page for details\&.

.PP
Every SNG file must begin with the string "#SNG", followed by optional SNG version information, followed by a colon (`:', ASCII 58) character\&. The remainder of the first line is ignored by SNG\&.

.PP
Comments in the syntax diagram describe intended semantics\&. This specification should be read in conjunction with the PNG standard\&.

IHDR {
   height <long>
   width <long>
   bitdepth <byte> 
   [using grayscale+color+palette+alpha]
   [with interlace]			# Adam7 assumed if interlacing on
}

PLTE {
   [<rgb>]*				# RGB triples or X color names
}

IDAT {
   <data>
}

gAMA {<float>}

cHRM {
   white (<float>,<float>)      # White point x and y
   red (<float>,<float>)
   green (<float>,<float>)
   blue (<float>,<float>)
}

sRGB {<byte>}                   # Colorimetry intent, range 0\-3

iCCP {                          # International Color Consortium profile
   name <keyword>
   profile <data>
}

sBIT {
   red <byte>                   # Color images only
   blue <byte>                  # Color images only
   green <byte>                 # Color images only
   gray <byte>                  # Grayscale images only
   alpha <byte>                 # Images with alpha only
}

bKGD {
   red <short>                  # Color images only
   blue <short>                 # Color images only
   green <short>                # Color images only
   gray <short>                 # Grayscale images only
   index <byte>                 # Paletted images only
}

hIST {
   <short> [, <short>]*         # Count must match palette size
}

tRNS {
   [gray <short>]               # Grayscale images only
   [red <short>]                # True\-color images only
   [green <short>]              # True\-color images only
   [blue <short>]               # True\-color images only
   [<byte>]*                    # Paletted images only
}

pHYs {
   xpixels <long>
   ypixels <long>
   [per meter]
}

tIME {
   year <short>
   month <byte>
   day <byte>
   hour <byte>
   minute <byte>
   second <byte>
}

tEXt {                          # Ordinary text chunk
  keyword <keyword>
  text <string>
}

zTXt {                          # Compressed text chunk
  keyword <keyword>
  text <string>
}

iTXt {                          # International UTF\-8 keyword
  language <keyword>
  keyword <keyword>
  translated <keyword>          # Translation of the keyword
  text <string>
  [compressed]
}

oFFs {
  xoffset <slong>
  yoffset <slong> 
  [unit pixels|micrometers]*
}

sPLT {
   name <keyword>
   depth <byte>
   [<rgb>, <short>, <short>]*    # Color followed by alpha and frequency
}

pCAL {
   name <keyword>
   x0 <slong>
   x1 <slong>
   mapping linear|euler|exponential|hyperboli   unit <string>
   [parameters <string>] 
}

sCAL {
   unit meter|radian
   width <string>
   height <string>
}

IMAGE {
   options identity+packing+packswap+invert_mono
              +shift+bgr+swap_alpha+invert_alpha+swap_endian+strip_filler
   pixels <data>
}

gIFg {
   disposal <byte>
   input <byte>
   delay <short>
}

gIFx {
   identifier <string>                # Must be 8 characters
   code <string>                      # Must be 3 characters
   data <data>
}

private <string> {                    # Private chunk declaration
   <data>
}

.SH "BUGS"

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

.SH "FILES"

.TP
rgb\&.txt
The X colorname database, used for RGB\-to\-name mappings in the decompiler and name\-to\-RGB mappings in the compiler\&.

.SH "SEE ALSO"

.PP
 \fBpbm\fR(5), \fBppm\fR(5)\&.

.SH "AUTHOR"

.PP
Eric S\&. Raymond <esr@snark\&.thyrsus\&.com> December 1999\&. The SNG home page is at http://sng\&.sourceforge\&.net/: \fIhttp://sng.sourceforge.net/\fR\&.

.PP
For more information about PNG, see the PNG website at <http://www\&.libpng\&.org/pub/png/: \fIhttp://www.libpng.org/pub/png/\fR>\&.

.PP
The W3C recommendation is Portable Network Graphics (PNG) Specification (Second Edition): \fIhttp://www.w3.org/TR/2003/PR\-PNG\-20030520/index-noobject.html\fR\&. The PNG specification is also ISO/IEC 15948\&.