sng.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC 
   "-//OASIS//DTD DocBook XML V4.1.2//EN"
   "docbook/docbookx.dtd">
<refentry id='sng.1'>
<refmeta>
<refentrytitle>sng</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='source'>Open Source</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>sng</refname>
<refpurpose> compiler/decompiler for Scriptable Network Graphics</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>

<cmdsynopsis>
  <command>sng</command>  <arg choice='opt'>-vV </arg>
  <arg choice='opt' rep='repeat'><replaceable>file</replaceable></arg>
</cmdsynopsis>

</refsynopsisdiv>

<refsect1 id='description'><title>DESCRIPTION</title>

<para>The <command>sng</command> 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.</para>

<para>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).</para>

<para>Given no file arguments, <command>sng</command> 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;
<command>sng</command> 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; <command>sng</command> tries to translate
it to SNG.</para>

<para>For each file that <command>sng</command> 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.</para>

<para>The -V option makes <command>sng</command> identify itself and
its version, then exit.  <!-- The -i option causes IDAT chunks in a PNG to
be dumped in raw form as IDAT chunks rather than as a reassembled
IMAGE. -->  The -v option makes <command>sng</command> report on what
files it is converting.</para> </refsect1>

<refsect1 id='sng_language_syntax'><title>SNG LANGUAGE SYNTAX</title>
<para>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).</para>

<para>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.</para>

<para>The elements &lt;byte&gt;, &lt;short&gt;, &lt;long&gt;,
&lt;float&gt;, &lt;string&gt; are byte numeric, short-integer numeric,
long-integer numeric, and float numeric literals respectively (all
unsigned).  The &lt;slong&gt; 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).</para>

<para>The element &lt;string&gt; 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.</para>

<para>The element &lt;keyword&gt; 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.</para>

<para>A &lt;data&gt; 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.</para>

<para>1. <emphasis remap='B'>string</emphasis> format is an SNG string
literal or sequence of string literals (see above). The bytes of data
are the string contents.</para>

<para>2. <emphasis remap='B'>base64</emphasis> 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.</para>

<para>3. <emphasis remap='B'>hex</emphasis> 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.</para>

<para>4. <emphasis remap='B'>P1</emphasis> 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.</para>

<para>5. <emphasis remap='B'>P3</emphasis> 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.</para>

<para>An &lt;rgb&gt; element may be expanded to:</para>

<literallayout remap='.nf'>
(&lt;byte&gt;, &lt;byte&gt;, &lt;byte&gt;) | &lt;string&gt;
</literallayout> <!-- .fi -->

<para>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.</para>

<para>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.</para>

<para>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.</para>

<para>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.</para>

<para>Comments in the syntax diagram describe intended semantics.  This
specification should be read in conjunction with the PNG standard.</para>

<literallayout remap='.nf'>
IHDR {
   height &lt;long&gt;
   width &lt;long&gt;
   bitdepth &lt;byte&gt; 
   [using grayscale+color+palette+alpha]
   [with interlace]			# Adam7 assumed if interlacing on
}

PLTE {
   [&lt;rgb&gt;]*				# RGB triples or X color names
}

IDAT {
   &lt;data&gt;
}

gAMA {&lt;float&gt;}

cHRM {
   white (&lt;float&gt;,&lt;float&gt;)      # White point x and y
   red (&lt;float&gt;,&lt;float&gt;)
   green (&lt;float&gt;,&lt;float&gt;)
   blue (&lt;float&gt;,&lt;float&gt;)
}

sRGB {&lt;byte&gt;}                   # Colorimetry intent, range 0-3

iCCP {                          # International Color Consortium profile
   name &lt;keyword&gt;
   profile &lt;data&gt;
}

sBIT {
   red &lt;byte&gt;                   # Color images only
   blue &lt;byte&gt;                  # Color images only
   green &lt;byte&gt;                 # Color images only
   gray &lt;byte&gt;                  # Grayscale images only
   alpha &lt;byte&gt;                 # Images with alpha only
}

bKGD {
   red &lt;short&gt;                  # Color images only
   blue &lt;short&gt;                 # Color images only
   green &lt;short&gt;                # Color images only
   gray &lt;short&gt;                 # Grayscale images only
   index &lt;byte&gt;                 # Paletted images only
}

hIST {
   &lt;short&gt; [, &lt;short&gt;]*         # Count must match palette size
}

tRNS {
   [gray &lt;short&gt;]               # Grayscale images only
   [red &lt;short&gt;]                # True-color images only
   [green &lt;short&gt;]              # True-color images only
   [blue &lt;short&gt;]               # True-color images only
   [&lt;byte&gt;]*                    # Paletted images only
}

pHYs {
   xpixels &lt;long&gt;
   ypixels &lt;long&gt;
   [per meter]
}

tIME {
   year &lt;short&gt;
   month &lt;byte&gt;
   day &lt;byte&gt;
   hour &lt;byte&gt;
   minute &lt;byte&gt;
   second &lt;byte&gt;
}

tEXt {                          # Ordinary text chunk
  keyword &lt;keyword&gt;
  text &lt;string&gt;
}

zTXt {                          # Compressed text chunk
  keyword &lt;keyword&gt;
  text &lt;string&gt;
}

iTXt {                          # International UTF-8 keyword
  language &lt;keyword&gt;
  keyword &lt;keyword&gt;
  translated &lt;keyword&gt;          # Translation of the keyword
  text &lt;string&gt;
  [compressed]
}

oFFs {
  xoffset &lt;slong&gt;
  yoffset &lt;slong&gt; 
  [unit pixels|micrometers]*
}

sPLT {
   name &lt;keyword&gt;
   depth &lt;byte&gt;
   [&lt;rgb&gt;, &lt;short&gt;, &lt;short&gt;]*    # Color followed by alpha and frequency
}

pCAL {
   name &lt;keyword&gt;
   x0 &lt;slong&gt;
   x1 &lt;slong&gt;
   mapping linear|euler|exponential|hyperboli   unit &lt;string&gt;
   [parameters &lt;string&gt;] 
}

sCAL {
   unit meter|radian
   width &lt;string&gt;
   height &lt;string&gt;
}

IMAGE {
   options identity+packing+packswap+invert_mono
              +shift+bgr+swap_alpha+invert_alpha+swap_endian+strip_filler
   pixels &lt;data&gt;
}

gIFg {
   disposal &lt;byte&gt;
   input &lt;byte&gt;
   delay &lt;short&gt;
}

gIFx {
   identifier &lt;string&gt;                # Must be 8 characters
   code &lt;string&gt;                      # Must be 3 characters
   data &lt;data&gt;
}

private &lt;string&gt; {                    # Private chunk declaration
   &lt;data&gt;
}
</literallayout> <!-- .fi -->
</refsect1>

<refsect1 id='bugs'><title>BUGS</title>
<para>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.</para>
</refsect1>

<refsect1 id='files'><title>FILES</title>
<variablelist remap='TP'>
<varlistentry>
<term>rgb.txt</term>
<listitem>
<para>The X colorname database, used for RGB-to-name mappings in the
decompiler and name-to-RGB mappings in the compiler. </para>
</listitem>
</varlistentry>
</variablelist>

</refsect1>

<refsect1 id='see_also'><title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>pbm</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>ppm</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
</refsect1>

<refsect1 id='author'><title>AUTHOR</title>
<para>Eric S. Raymond <email>esr@snark.thyrsus.com</email> December 1999.
The SNG home page is at <ulink url='http://sng.sourceforge.net/'>http://sng.sourceforge.net/</ulink>.</para>

<para>For more information about PNG, see the
PNG website at &lt;<ulink url='http://www.libpng.org/pub/png/'>http://www.libpng.org/pub/png/</ulink>&gt;.</para>

<para>The W3C recommendation is 
<ulink
url="http://www.w3.org/TR/2003/PR-PNG-20030520/index-noobject.html">
Portable Network Graphics (PNG) Specification (Second
Edition)</ulink>.  The PNG specification is also ISO/IEC 15948.</para>

</refsect1>
</refentry>