'\" t
.\" Title: sng
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1
.\" Date: 01/12/2016
.\" Manual: User Commands
.\" Source: Open Source
.\" Language: English
.\"
.TH "SNG" "1" "01/12/2016" "Open Source" "User Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sng \- compiler/decompiler for Scriptable Network Graphics
.SH "SYNOPSIS"
.HP \w'\fBsng\fR\ 'u
\fBsng\fR [\-vV] [\fIfile\fR...]
.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 makes
\fBsng\fR
identify itself and its version, then exit\&.
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 `#\*(Aq comment leader causes all characters up to the next following newline to be ignored\&. The characters `:\*(Aq and `;\*(Aq are treated as whitespace, except the `;\*(Aq 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 , , , , are byte numeric, short\-integer numeric, long\-integer numeric, and float numeric literals respectively (all unsigned)\&. The 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 is any number of doublequote\-delimited character string literals\&. C\-style escapes (\en, \et, \eb, \er or \e followed by octal or hex digits) are interpreted\&. The result is the concatenation of all the literals\&.
.PP
The element 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 element consists of a sequence of byte specifications in any of the following formats\&. Either \*(Aq}\*(Aq or \*(Aq;\*(Aq ends a data literal; `}\*(Aq also ends the enclosing chunk\&.
.PP
1\&.
\fBstring\fR
format is an SNG string literal or sequence of string literals (see above)\&. The bytes of data are the string contents\&.
.PP
2\&.
\fBbase64\fR
format is signaled by the leading token `base64\*(Aq\&. This encoding can only be used when the values of all bytes is less than 64\&. It encodes each byte as a single character, 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\&. Note that this encoding is only very loosely related to RFC2045 base\-64 encoding, which uses a different mapping of bytes to values, and supports encoding of arbitrary binary data\&.
.PP
3\&.
\fBhex\fR
format is signaled by the leading token `hex\*(Aq\&. In hex format, each byte is specified by two hex digits (0123456789abcdef), most significant first\&. Whitespace is ignored\&.
.PP
4\&.
\fBP1\fR
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 characters are expected to be `0\*(Aq and `1\*(Aq, with the obvious values\&. Whitespace is ignored\&.
.PP
5\&.
\fBP3\fR
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 element may be expanded to:
.sp
.if n \{\
.RS 4
.\}
.nf
(, , ) |
.fi
.if n \{\
.RE
.\}
.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\*(Aq 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 (`:\*(Aq, 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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
IHDR {
height
width
bitdepth
[using grayscale+color+palette+alpha]
[with interlace] # Adam7 assumed if interlacing on
}
PLTE {
[]* # RGB triples or X color names
}
IDAT {
}
gAMA {}
cHRM {
white (,) # White point x and y
red (,)
green (,)
blue (,)
}
sRGB {} # Colorimetry intent, range 0\-3
iCCP { # International Color Consortium profile
name
profile
}
sBIT {
red # Color images only
blue # Color images only
green # Color images only
gray # Grayscale images only
alpha # Images with alpha only
}
bKGD {
red # Color images only
blue # Color images only
green # Color images only
gray # Grayscale images only
index # Paletted images only
}
hIST {
[, ]* # Count must match palette size
}
tRNS {
[gray ] # Grayscale images only
[red ] # True\-color images only
[green ] # True\-color images only
[blue ] # True\-color images only
[]* # Paletted images only
}
pHYs {
xpixels
ypixels
[per meter]
}
tIME {
year
month
day
hour
minute
second
}
tEXt { # Ordinary text chunk
keyword
text
}
zTXt { # Compressed text chunk
keyword
text
}
iTXt { # International UTF\-8 keyword
language
keyword
translated # Translation of the keyword
text
[compressed]
}
oFFs {
xoffset
yoffset
[unit pixels|micrometers]*
}
sPLT {
name
depth
[, , ]* # Color followed by alpha and frequency
}
pCAL {
name
x0
x1
mapping linear|euler|exponential|hyperboli unit
[parameters ]
}
sCAL {
unit meter|radian
width
height
}
IMAGE {
options identity+packing+packswap+invert_mono
+shift+bgr+swap_alpha+invert_alpha+swap_endian+strip_filler
pixels
}
gIFg {
disposal
input
delay
}
gIFx {
identifier # Must be 8 characters
code # Must be 3 characters
data
}
private { # Private chunk declaration
}
.fi
.if n \{\
.RE
.\}
.SH "BUGS"
.PP
The \-i option doesn\*(Aqt work yet, and won\*(Aqt until libpng\*(Aqs ability to suppress special handling of IDATs is working\&. See the distribution TODO file for other minor problems\&.
.SH "FILES"
.PP
rgb\&.txt
.RS 4
The X colorname database, used for RGB\-to\-name mappings in the decompiler and name\-to\-RGB mappings in the compiler\&.
.RE
.SH "SEE ALSO"
.PP
\fBpbm\fR(5),
\fBppm\fR(5)\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
December 1999\&. The SNG home page is at
\m[blue]\fBhttp://sng\&.sourceforge\&.net/\fR\m[]\&.
.PP
For more information about PNG, see the PNG website at <\m[blue]\fBhttp://www\&.libpng\&.org/pub/png/\fR\m[]>\&.
.PP
The W3C recommendation is
\m[blue]\fBPortable Network Graphics (PNG) Specification (Second Edition)\fR\m[]\&\s-2\u[1]\d\s+2\&. The PNG specification is also ISO/IEC 15948\&.
.SH "NOTES"
.IP " 1." 4
Portable Network Graphics (PNG) Specification (Second Edition)
.RS 4
\%http://www.w3.org/TR/2003/PR-PNG-20030520/index-noobject.html
.RE