'\"
'\" Generated from file '/net/nas/data/andreask/Dev/Crimp/dev-trunk/embedded/man/files/crimp_core.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2011 Andreas Kupries
'\" Copyright (c) 2011 Documentation, Andreas Kupries
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\" # BS - start boxed text
'\" # ^y = starting y location
'\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\" # VS - start vertical sidebar
'\" # ^Y = starting y location
'\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\" # Special macro to handle page bottom: finish off current
'\" # box/sidebar if in box/sidebar mode, then invoked standard
'\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\" # DS - begin display
.de DS
.RS
.nf
.sp
..
'\" # DE - end display
.de DE
.fi
.RE
.sp
..
'\" # SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\" # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
'\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
'\" # CE - end code excerpt
.de CE
.fi
.RE
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH "crimp_core" n 0.1 doc "C Raster Image Manipulation Package"
.BS
.SH NAME
crimp_core \- CRIMP - Foundation
.SH SYNOPSIS
package require \fBTcl 8.5\fR
.sp
package require \fBcrimp::core ?0.1?\fR
.sp
\fB::crimp\fR \fI...\fR
.sp
\fB::crimp\fR \fBchannels\fR \fIimage\fR
.sp
\fB::crimp\fR \fBdimensions\fR \fIimage\fR
.sp
\fB::crimp\fR \fBheight\fR \fIimage\fR
.sp
\fB::crimp\fR \fBmeta append\fR \fIimage\fR \fIkey\fR ?\fIstring\fR...?
.sp
\fB::crimp\fR \fBmeta create\fR \fIimage\fR ?\fIkey\fR \fIvalue\fR...?
.sp
\fB::crimp\fR \fBmeta exists\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...?
.sp
\fB::crimp\fR \fBmeta filter\fR \fIimage\fR \fIargs\fR...
.sp
\fB::crimp\fR \fBmeta for\fR \fIimage\fR {\fIkeyVar\fR \fIvalueVar\fR} \fIbody\fR
.sp
\fB::crimp\fR \fBmeta get\fR \fIimage\fR ?\fIkey\fR...?
.sp
\fB::crimp\fR \fBmeta incr\fR \fIimage\fR \fIkey\fR ?\fIincrement\fR?
.sp
\fB::crimp\fR \fBmeta info\fR \fIimage\fR
.sp
\fB::crimp\fR \fBmeta keys\fR \fIimage\fR ?\fIglobPattern\fR?
.sp
\fB::crimp\fR \fBmeta lappend\fR \fIimage\fR \fIkey\fR ?\fIvalue\fR...?
.sp
\fB::crimp\fR \fBmeta merge\fR \fIimage\fR ?\fIdictionaryValue\fR...?
.sp
\fB::crimp\fR \fBmeta remove\fR \fIimage\fR ?\fIkey\fR...?
.sp
\fB::crimp\fR \fBmeta replace\fR \fIimage\fR ?\fIkey\fR \fIvalue\fR...?
.sp
\fB::crimp\fR \fBmeta set\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...? \fIvalue\fR
.sp
\fB::crimp\fR \fBmeta size\fR \fIimage\fR
.sp
\fB::crimp\fR \fBmeta unset\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...?
.sp
\fB::crimp\fR \fBmeta values\fR \fIimage\fR ?\fIglobPattern\fR?
.sp
\fB::crimp\fR \fBpixel\fR \fIimage\fR
.sp
\fB::crimp\fR \fBtype\fR \fIimage\fR
.sp
\fB::crimp\fR \fBwidth\fR \fIimage\fR
.sp
\fB::crimp\fR \fBread\fR \fI...\fR
.sp
\fB::crimp\fR \fBread tcl grey8\fR \fIpixelmatrix\fR
.sp
\fB::crimp\fR \fBread tcl float\fR \fIpixelmatrix\fR
.sp
\fB::crimp\fR \fBwrite\fR \fI...\fR
.sp
\fB::crimp\fR \fBwrite 2string\fR \fIformat\fR \fIimage\fR
.sp
\fB::crimp\fR \fBwrite 2chan\fR \fIformat\fR \fIchan\fR \fIimage\fR
.sp
\fB::crimp\fR \fBwrite 2file\fR \fIformat\fR \fIpath\fR \fIimage\fR
.sp
.BE
.SH DESCRIPTION
This package is the foundation for the whole of CRIMP, the C Raster
Image Manipulation Package.
.PP
For a basic introduction of the whole CRIMP eco-system please read
the \fICRIMP - Introduction to CRIMP\fR (sic!).
.PP
As the foundation its location is in the bottom-most layer of the
system's architecture, as shown at
.PP
IMAGE: arch_core
.PP
The core provides both C and Tcl level data types and accessors for
images, plus rudimentary IO capabilities (conversion to and
construction from matrices of numbers, represented by nested Tcl
lists).
.PP
The following sections first describe the basic concepts of the
system, like images and image types, general organization of the
command space, etc. After that follows a reference of the Tcl API
provided by the core. The C API is not really of interest to users
of CRIMP, only to developers wishing to extend the system. As such
it is not described here, but in separate manpages targeted at
developers and maintainers.
.SH IMAGES
Images are values. This means that they have a string
representation. It is however strongly recommended to not access this
representation at all, and to only use the accessor commands provided
by crimp to obtain the information stored in the internal
representation of image values.
.PP
The reason behind this is simple: Memory and speed. Images can be
large. Generating the string representation from the internal one
roughly doubles the memory needed to store it, actually a bit more,
due to the necessary quoting of bytes in UTF-8 and list-quting them as
well. Furthermore such a conversion takes time, roughly proportional
to the size of the image itself, in either direction. Properly
accessing the image information without the package's accessor
commands requires list commands. This causes the loss of the internal
representation, thus forcing later a reconversion to the image's
internal represention when it is used as image again. I.e. the
shimmering forces us to convert twice.
.PP
Therefore, to avoid this, use only the crimp commands to access the
images. Even the raw pixel data is accessible in this manner. While
access to that in a Tcl script is, IMHO, highly unusual, there are
situations where it is beneficial. An example of such a situation are
the commands exporting images to raw portable any-maps (PNMs). Our
pixel data fits these formats exactly, and with access to it these
commands could be written in Tcl instead of requiring C level primitives.
.SH "IMAGE TYPES"
Each image has a \fItype\fR, a string implicitly describing features
like the colorspace the image is in, the number of (color) channels,
the domain, i.e. bit-depth, of pixel values in the channels, etc.
.PP
All type strings have the form \fBcrimp::image::\fR\fBfoo\fR.
.PP
The package currently knows the following types:
.TP
\fBrgba\fR
.RS
.TP
Colorspace
RGB also known as Red, Green, and Blue.
.TP
Channels
4, named "red", "green", and "blue",
plus an "alpha" channel controlling
pixel opacity.
.TP
Bit-depth
1 byte/channel (8 bit, values 0-255).
.TP
Pixel-size
4 bytes.
.RE
.TP
\fBrgb\fR
.RS
.TP
Colorspace
RGB also known as Red, Green, and Blue.
.TP
Channels
3, named "red", "green", and "blue".
.TP
Bit-depth
1 byte/channel (8 bit, values 0-255).
.TP
Pixel-size
3 bytes.
.RE
.TP
\fBhsv\fR
.RS
.TP
Colorspace
HSV, also known as Hue, Saturation, and Value.
.TP
Channels
3, named "hue", "saturation", and "value".
.TP
Bit-depth
1 byte/channel (8 bit, values 0-255).
.TP
Pixel-size
3 bytes.
.RE
.TP
\fBgrey8\fR
.RS
.TP
Colorspace
Greyscale.
.TP
Channels
1, named "luma".
.TP
Bit-depth
1 byte/channel (8 bit, values 0-255).
.TP
Pixel-size
1 byte.
.RE
.TP
\fBgrey16\fR
.RS
.TP
Colorspace
Greyscale.
.TP
Channels
1, named "luma".
.TP
Bit-depth
2 byte/channel (16 bit, values 0-65,535).
.TP
Pixel-size
2 bytes.
.RE
.TP
\fBgrey32\fR
.RS
.TP
Colorspace
Greyscale.
.TP
Channels
1, named "luma".
.TP
Bit-depth
4 byte/channel (16 bit, values 0-4,294,967,296).
.TP
Pixel-size
4 bytes.
.RE
.TP
\fBbw\fR
.RS
.TP
Colorspace
Binary.
.TP
Channels
1, named "bw".
.TP
Bit-depth
1 bit/channel.
.TP
Pixel-size
1 byte. I.e. 7 bits/channel are wasted.
.RE
.TP
\fBfloat\fR
.RS
.TP
Colorspace
N.A / Floating Point.
.TP
Channels
1, named "value".
.TP
Bit-depth
4 byte/channel.
.TP
Pixel-size
4 byte.
.RE
.TP
\fBfpcomplex\fR
.RS
.TP
Colorspace
N.A / Floating Point.
.TP
Channels
2, named "real", and "imaginary".
.TP
Bit-depth
4 byte/channel.
.TP
Pixel-size
8 byte.
.RE
.PP
Support for the various types varies by operation. The exact image
types supported by each operation will be listed in the operation's
description. Invoking an operation for a type it doesn't support will
generally cause it to throw an error.
.SH "GENERAL DESIGN"
All commands operate in a pipeline fashion, taking zero or more image
values, zero or more other arguments, and returning zero or more
images or other values. None are operating in place, i.e. taking an
image variable and writing back to it.
.PP
They fall into five categories, namely:
.PP
.PS
.nf
+-----------------------+-----+---+
| CRIMP | Tcl | C |
+-----------------------+-----+---+
| I/O Read | | |
| ----------+-----+---+
| Write | | |
+-----------------------+-----+---+
| Converters | | |
+-----------------------+-----+---+
| Manipulators Geometry | | |
| ----------+-----+---+
| Color | | |
+-----------------------+-----+---+
| Accessors | | |
+-----------------------+-----+---+
| Support | | |
+-----------------------+-----+---+
.fi
.PE
.TP
Accessors
They take one or more images, extract information about them, and
return this information as their result. This can be a simple as
querying the image's height, to something as complex as counting pixel
values for a histogram.
.sp
The list of accessors, their syntax, and detailed meaning can be found
in section \fBAccessors\fR.
.TP
Manipulators
These take an image and transform its contents in some way, leaving
the image type unchanged. Examples of commands in category are
inversion, gamma conversion, etc. They fall into two sub-categories,
manipulation of the image geometry, and of the intensity values or
colors.
.TP
Converters
Similar to manipulators, except that they change the image's type,
preserving the content instead. Here reside operations like conversion
between the HSV and RGB colorspaces, to greyscale and back, etc.
.TP
I/O
Another variant of the same theme, i.e. akin to converters and
manipulators, yet not the same, these commands read and write images
from and to files or other data structures. I.e. they convert between
different serializations of image content and type.
.sp
The list of I/O commands, their syntax, and detailed meaning can be
found in section \fBI/O commands\fR.
.TP
Support
Lastly, but not leastly a number of commands, which, while not image
commands themselves, support the others.
.PP
The core package specified here provides only Accessors and
rudimentary I/O commands. All other sections are filled out by the
other packages of the CRIMP eco-system.
.SH "TCL API"
.TP
\fB::crimp\fR \fI...\fR
Any and all functionality of CRIMP, regardless of which package
in the system provides it, will be made accessible through a
(set of) method(s) of this ensemble command.
.sp
In other words, this command serves as the umbrella
underneath which anything else is arranged and made available.
.PP
.SS ACCESSORS
.TP
\fB::crimp\fR \fBchannels\fR \fIimage\fR
This method returns a list containing the names of the channels in the
\fIimage\fR. The order of channels is the same as expected by the
\fBremap\fR method.
.sp
The method supports all image types.
.TP
\fB::crimp\fR \fBdimensions\fR \fIimage\fR
This method returns the width and height of the \fIimage\fR (in
pixels). The result is a 2-element list containing width and height,
in this order.
.sp
The method supports all image types.
.TP
\fB::crimp\fR \fBheight\fR \fIimage\fR
This method returns the height of the \fIimage\fR (in pixels).
.sp
The method supports all image types.
.TP
\fB::crimp\fR \fBmeta append\fR \fIimage\fR \fIkey\fR ?\fIstring\fR...?
.TP
\fB::crimp\fR \fBmeta create\fR \fIimage\fR ?\fIkey\fR \fIvalue\fR...?
.TP
\fB::crimp\fR \fBmeta exists\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...?
.TP
\fB::crimp\fR \fBmeta filter\fR \fIimage\fR \fIargs\fR...
.TP
\fB::crimp\fR \fBmeta for\fR \fIimage\fR {\fIkeyVar\fR \fIvalueVar\fR} \fIbody\fR
.TP
\fB::crimp\fR \fBmeta get\fR \fIimage\fR ?\fIkey\fR...?
.TP
\fB::crimp\fR \fBmeta incr\fR \fIimage\fR \fIkey\fR ?\fIincrement\fR?
.TP
\fB::crimp\fR \fBmeta info\fR \fIimage\fR
.TP
\fB::crimp\fR \fBmeta keys\fR \fIimage\fR ?\fIglobPattern\fR?
.TP
\fB::crimp\fR \fBmeta lappend\fR \fIimage\fR \fIkey\fR ?\fIvalue\fR...?
.TP
\fB::crimp\fR \fBmeta merge\fR \fIimage\fR ?\fIdictionaryValue\fR...?
.TP
\fB::crimp\fR \fBmeta remove\fR \fIimage\fR ?\fIkey\fR...?
.TP
\fB::crimp\fR \fBmeta replace\fR \fIimage\fR ?\fIkey\fR \fIvalue\fR...?
.TP
\fB::crimp\fR \fBmeta set\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...? \fIvalue\fR
.TP
\fB::crimp\fR \fBmeta size\fR \fIimage\fR
.TP
\fB::crimp\fR \fBmeta unset\fR \fIimage\fR \fIkey\fR ?\fIkey\fR...?
.TP
\fB::crimp\fR \fBmeta values\fR \fIimage\fR ?\fIglobPattern\fR?
These methods provide access to the meta data slot of images, treating
its contents as a dictionary. As such all the methods provided here
have an appropriate counterpart in the methods of Tcl's builtin
command \fBdict\fR, with the image's metadata taking the place of the
dictionary value or vqariable.
The converse is not true, as \fBdict\fR's methods \fBupdate\fR and
\fBwith\fR are not supported here.
.sp
Please read the documentation of Tcl's \fBdict\fR command for reference.
.sp
\fINOTE\fR that the toplevel key \fBcrimp\fR is reserved for
use by CRIMP itself.
.TP
\fB::crimp\fR \fBpixel\fR \fIimage\fR
This method returns the raw pixels of the \fIimage\fR as a Tcl ByteArray.
.sp
The method supports all image types.
.TP
\fB::crimp\fR \fBtype\fR \fIimage\fR
This method returns the type of the \fIimage\fR.
.sp
The method supports all image types.
.TP
\fB::crimp\fR \fBwidth\fR \fIimage\fR
This method returns the width of the \fIimage\fR (in pixels).
.sp
The method supports all image types.
.PP
.SS "I/O COMMANDS"
.TP
\fB::crimp\fR \fBread\fR \fI...\fR
This ensemble command is the umbrella underneath which any and all
functionality for reading images from external formats must be placed.
.sp
This command is an \fIextension point\fR. I.e., other packages
are allowed to extend this ensemble by providing commands of the form
\fB::crimp::read::\fBFOO\fR\fR, where \fIFOO\fR should be the name of
the format the command is able to read, or related to it.
Note that only commands beginning with a lower-case alphanumerical
character, i.e. [a-z0-9] will be exported by the ensemble. This
means that it is possible to put private helper commands into the
\fB::crimp::read\fR namespace which will not be visible to the user,
by naming them appropriately. However, even so it is recommended to put
private commands into a sub-namespace instead, named after the package
in question, to reduce the probability of naming conflicts.
.sp
The commands used to extend the ensemble are not restricted in
their argument signature, although they are expected to return an image.
.sp
This package provides only rudimentary import facilities from
Tcl data structures, as described next.
.TP
\fB::crimp\fR \fBread tcl grey8\fR \fIpixelmatrix\fR
This method takes the \fIpixelmatrix\fR, a list of rows, with each row
a list of pixel values in the domain [0..255] and returns an
image of type \fBgrey8\fR whose height is the number of rows, i.e.
the length of the outer list, and whose width is the maximum length
found among the inner lists. Rows whose inner list is shorter than the
maximum length are padded with black pixels, i.e. a pixel value of
\fB0\fR.
.TP
\fB::crimp\fR \fBread tcl float\fR \fIpixelmatrix\fR
This method takes the \fIpixelmatrix\fR, a list of rows, with each row
a list of floating point values for pixel values and returns an image
of type \fBfloat\fR whose height is the number of rows, i.e. the
length of the outer list, and whose width is the maximum length found
among the inner lists. Rows whose inner list is shorter than the
maximum length are padded with a pixel value of \fB0\fR.
.TP
\fB::crimp\fR \fBwrite\fR \fI...\fR
This ensemble command is the umbrella underneath which any and all
functionality for writing images to external formats must be placed.
.sp
This command is an \fIextension point\fR. I.e., other packages
are allowed to extend this ensemble by providing commands of the form
\fB::crimp::write::\fBFOO\fR\fR, where \fIFOO\fR should be the name of
the format the command is able to write, or related to it.
Note that only commands beginning with a lower-case alphanumerical
character, i.e. [a-z0-9] will be exported by the ensemble. This
means that it is possible to put private helper commands into the
\fB::crimp::write\fR namespace which will not be visible to the user,
by naming them appropriately. However, even so it is recommended to put
private commands into a sub-namespace instead, named after the package
in question, to reduce the probability of naming conflicts.
.sp
The commands used to extend the ensemble are not restricted in
their argument signature, although they are expected to take at least
an image as argument.
.TP
\fB::crimp\fR \fBwrite 2string\fR \fIformat\fR \fIimage\fR
.TP
\fB::crimp\fR \fBwrite 2chan\fR \fIformat\fR \fIchan\fR \fIimage\fR
.TP
\fB::crimp\fR \fBwrite 2file\fR \fIformat\fR \fIpath\fR \fIimage\fR
This family of methods extends the basic \fB::crimp write\fR ensemble.
The input \fIimage\fR is returned as either a binary string in the
specified \fIformat\fR, or written to the open channel \fIchan\fR, or
the named file at \fIpath\fR.
.sp
By default the only supported format is \fBtcl\fR, a representation
of an image as a nested Tcl list. This format supports, i.e. accepts, images
with the types \fBgrey8\fR, \fBrga\fR, \fBrgba\fR, and \fBhsv\fR for
export.
.sp
This family of commands is an \fIextension point\fR. Other packages
can extend it to support additional formats by providing commands of the
form \fB::crimp::write::Str_\fBFOO\fR_\fBTYPE\fR\fR
and \fB::crimp::write::Chan_\fBFOO\fR_\fBTYPE\fR\fR
where \fBFOO\fR is the name of the format, to specify as the argument
\fIformat\fR, and \fBTYPE\fR the type of image handled by the command.
.sp
Note that the \fBChan_\fR form is optional. If this form is missing
the system will use the \fBStr_\fR form to convert the image before
writing it to channel or file.
.sp
The commands must match the following signatures:
.RS
.TP
\fBStr_...\fR \fIimage\fR
.TP
\fBChan_...\fR \fIchannel\fR \fIimage\fR
.RE
.PP
.SH "C API"
The C API of the core is of no interest to users of CRIMP, the audience
towards which this manpage is geared to.
.SH KEYWORDS
channels, computer vision, dimensions, document processing, image, image accessors, image type, matrix, photo, vector
.SH COPYRIGHT
.nf
Copyright (c) 2011 Andreas Kupries
Copyright (c) 2011 Documentation, Andreas Kupries
.fi