'\"
'\" Generated from file '/net/nas/data/andreask/trans/tim-ak/cr/dev/embedded/man/files/crimp.n' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2010 Andreas Kupries
'\" Copyright (c) 2010 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" n 1.0.1 doc "Image Manipulation"
.BS
.SH NAME
crimp \- Image Manipulation (not yet independent of Tk)
.SH SYNOPSIS
package require \fBTcl 8.5\fR
.sp
package require \fBTk 8.5\fR
.sp
package require \fBcrimp ?1?\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 \fBhistogram\fR \fIimage\fR
.sp
\fB::crimp\fR \fBtype\fR \fIimage\fR
.sp
\fB::crimp\fR \fBwidth\fR \fIimage\fR
.sp
\fB::crimp\fR \fBalpha blend\fR \fIforeground\fR \fIbackground\fR \fIalpha\fR
.sp
\fB::crimp\fR \fBalpha set\fR \fIimage\fR \fImask\fR
.sp
\fB::crimp\fR \fBalpha opaque\fR \fIimage\fR
.sp
\fB::crimp\fR \fBalpha over\fR \fIforeground\fR \fIbackground\fR
.sp
\fB::crimp\fR \fBblank\fR \fItype\fR \fIwidth\fR \fIheight\fR \fIvalue\fR...
.sp
\fB::crimp\fR \fBdegamma\fR \fIimage\fR \fIy\fR
.sp
\fB::crimp\fR \fBexpand const\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR ?\fIvalue\fR...?
.sp
\fB::crimp\fR \fBexpand extend\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.sp
\fB::crimp\fR \fBexpand mirror\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.sp
\fB::crimp\fR \fBexpand replicate\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.sp
\fB::crimp\fR \fBexpand wrap\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.sp
\fB::crimp\fR \fBfilter convolve\fR ?\fB-border\fR \fIspec\fR? \fIkernel\fR...
.sp
\fB::crimp\fR \fBfilter rank\fR ?\fB-border\fR \fIspec\fR? ?\fIradius\fR ?\fIpercentile\fR??
.sp
\fB::crimp\fR \fBgamma\fR \fIimage\fR \fIy\fR
.sp
\fB::crimp\fR \fBinvert\fR \fIimage\fR
.sp
\fB::crimp\fR \fBmatrix\fR \fIimage\fR \fImatrix\fR
.sp
\fB::crimp\fR \fBpsychedelia\fR \fIwidth\fR \fIheight\fR \fIframes\fR
.sp
\fB::crimp\fR \fBpyramid run\fR \fIimage\fR \fIsteps\fR \fIstepcmd\fR
.sp
\fB<stepcmd>\fR \fIimage\fR
.sp
\fB::crimp\fR \fBpyramid gauss\fR \fIimage\fR \fIsteps\fR
.sp
\fB::crimp\fR \fBpyramid laplace\fR \fIimage\fR \fIsteps\fR
.sp
\fB::crimp\fR \fBremap\fR \fIimage\fR \fImap\fR...
.sp
\fB::crimp\fR \fBsolarize\fR \fIimage\fR \fIthreshold\fR
.sp
\fB::crimp\fR \fBthreshold-ge\fR \fIimage\fR \fIthreshold\fR
.sp
\fB::crimp\fR \fBthreshold-le\fR \fIimage\fR \fIthreshold\fR
.sp
\fB::crimp\fR \fBwavy\fR \fIimage\fR \fIoffset\fR \fIadj1\fR \fIadjb\fR
.sp
\fB::crimp\fR \fBflip horizontal\fR \fIimage\fR
.sp
\fB::crimp\fR \fBflip transpose\fR \fIimage\fR
.sp
\fB::crimp\fR \fBflip transverse\fR \fIimage\fR
.sp
\fB::crimp\fR \fBflip vertical\fR \fIimage\fR
.sp
\fB::crimp\fR \fBconvert 2grey8\fR \fIimage\fR
.sp
\fB::crimp\fR \fBconvert 2hsv\fR \fIimage\fR
.sp
\fB::crimp\fR \fBconvert 2rgba\fR \fIimage\fR
.sp
\fB::crimp\fR \fBconvert 2rgb\fR \fIimage\fR
.sp
\fB::crimp\fR \fBjoin 2hsv\fR \fIhueImage\fR \fIsatImage\fR \fIvalImage\fR
.sp
\fB::crimp\fR \fBjoin 2rgba\fR \fIredImage\fR \fIgreenImage\fR \fIblueImage\fR \fIalphaImage\fR
.sp
\fB::crimp\fR \fBjoin 2rgb\fR \fIredImage\fR \fIgreenImage\fR \fIblueImage\fR
.sp
\fB::crimp\fR \fBsplit\fR \fIimage\fR
.sp
\fB::crimp\fR \fBread tcl\fR \fIpixelmatrix\fR
.sp
\fB::crimp\fR \fBread tk\fR \fIphoto\fR
.sp
\fB::crimp\fR \fBwrite 2tk\fR \fIphoto\fR \fIimage\fR
.sp
\fB::crimp\fR \fBkernel make\fR \fImatrix\fR ?\fIscale\fR?
.sp
\fB::crimp\fR \fBkernel transpose\fR \fIkernel\fR
.sp
\fB::crimp\fR \fBmap\fR \fIarg\fR...
.sp
\fB::crimp\fR \fBtable degamma\fR \fIy\fR
.sp
\fB::crimp\fR \fBtable gainw\fR \fIgain\fR \fIbias\fR
.sp
\fB::crimp\fR \fBtable gain\fR \fIgain\fR \fIbias\fR
.sp
\fB::crimp\fR \fBtable gamma\fR \fIy\fR
.sp
\fB::crimp\fR \fBtable gauss\fR \fIsigma\fR
.sp
\fB::crimp\fR \fBtable identity\fR
.sp
\fB::crimp\fR \fBtable invers\fR
.sp
\fB::crimp\fR \fBtable solarize\fR \fIthreshold\fR
.sp
\fB::crimp\fR \fBtable threshold-ge\fR \fIthreshold\fR
.sp
\fB::crimp\fR \fBtable threshold-le\fR \fIthreshold\fR
.sp
.BE
.SH DESCRIPTION
This package provides image manipulation commands which are mostly
independent of Tk. The only parts currently depending on Tk are for
the import and export of images from and to Tk photos, necessary for
display.
.PP
Note that the intended audience of this document are the users of
\fBcrimp\fR. Developers wishing to work on the internals of the
package, but unfamiliar with them, should read ... instead.
.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, avoid this, use only the crimp commands to access the
images. The only part of them you are not able to access through these
is the pixel data. And requiring access to that in a Tcl script is,
IMHO, highly unusual. In such a situation it is likely better and
easier to simply become a developer and extend the C level parts of
crimp with the operation which would have required that access.
.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
.PP
Support for the various types varies by operation. The exact image
types supported by each operation are listed 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:
.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.
.sp
The list of manipulators, their syntax, and detailed meaning can be
found in section \fBManipulators\fR.
.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.
.sp
The list of converters, their syntax, and detailed meaning can be
found in section \fBConverters\fR.
.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.
.sp
The list of supporting commands, their syntax, and detailed meaning
can be found in section \fBSupport\fR.
.PP
.SH API
.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 \fBhistogram\fR \fIimage\fR
This method returns a nested dictionary as its result. The outer
dictionary is indexed by the names of the channels in the \fIimage\fR.
Its values, the inner dictionaries, are indexed by pixel value. The
associated values are the number of pixels with that value.
.sp
The method supports all image types except "grey32". Under the
current system the result would be a dictionary with 2^32 keys and
values, taking up, roughly, 192 GiByte of memory in the worst case,
and 96 GiByte in best case (all counter values shared in a single
object).
.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 MANIPULATORS
.TP
\fB::crimp\fR \fBalpha blend\fR \fIforeground\fR \fIbackground\fR \fIalpha\fR
This method takes two images of identical dimensions and a blending
factor \fIalpha\fR and returns an image which is a mix of both, with
each pixel blended per the formula
.sp
.PS
.nf
Z = F\\alpha + B(1-\\alpha)
.fi
.PE
.sp
or, alternatively written
.sp
.PS
.nf
Z = (F - B)\\alpha + B
.fi
.PE
.sp
This means that the \fIforeground\fR is returned as is for
"\fIalpha\fR == 255", and the \fIbackground\fR for
"\fIalpha\fR == 0".
I.e. the argument \fIalpha\fR controls the \fIopacity\fR of the
foreground, with \fB1\fR and \fB0\fR standing for "fully opaque"
and "fully transparent", respectively.
.sp
The following combinations of fore- and background image types are
supported:
.nf
Result = Foreground Background
------ ---------- ----------
grey8 grey8 grey8
hsv hsv hsv
rgb rgb grey8
rgb rgb rgb
rgb rgb rgba
rgba rgba grey8
rgba rgba rgb
rgba rgba rgba
------ ---------- ----------
.fi
.TP
\fB::crimp\fR \fBalpha set\fR \fIimage\fR \fImask\fR
This command takes two images, the input and a \fImask\fR, and returns
an image as result in which the mask is the alpha channel of the
input.
The result is therefore always of type \fBrgba\fR, as the only type
supporting an alpha channel.
.sp
The input image can be of type \fBrgb\fR or \fBrgba\fR. In
case of the latter the existing alpha channel is replaced, in case of
the former an alpha channel is added.
.sp
For the mask images of type \fBgrey8\fR and \fBrgba\fR are
accepted. In the case of the latter the mask's alpha channel is used
as the new alpha channel, in case of the former the mask itself is
used.
.TP
\fB::crimp\fR \fBalpha opaque\fR \fIimage\fR
A convenience method over \fBalpha set\fR, giving the \fIimage\fR
a mask which makes it fully opaque.
.TP
\fB::crimp\fR \fBalpha over\fR \fIforeground\fR \fIbackground\fR
This method is similar to \fBblend\fR above, except that there is
no global blending parameter. This information is taken from the
"alpha" channel of the \fIforeground\fR image instead. The blending
formula is the same, except that the alpha parameter is now a
per-pixel value, and not constant across the image.
.sp
Due to the need for an alpha channel the \fIforeground\fR has to be of
type \fBrgba\fR. For the \fIbackground\fR image the types
\fBrgb\fR and \fBrgba\fR are supported.
.TP
\fB::crimp\fR \fBblank\fR \fItype\fR \fIwidth\fR \fIheight\fR \fIvalue\fR...
This method returns a blank image of the given image type and
dimensions. The \fIvalue\fRs after the dimensions are the pixel
values to fill the pixels in the image's channels with, per its type.
.sp
This method currently support only the types \fBrgb\fR,
\fBrgba\fR, and \fBgrey8\fR.
.TP
\fB::crimp\fR \fBdegamma\fR \fIimage\fR \fIy\fR
This method takes an image, runs it through an
\fBinverse gamma correction\fR with parameter \fIy\fR, and returns
the corrected image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap degamma\fR \fIy\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBexpand const\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR ?\fIvalue\fR...?
.TP
\fB::crimp\fR \fBexpand extend\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.TP
\fB::crimp\fR \fBexpand mirror\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.TP
\fB::crimp\fR \fBexpand replicate\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
.TP
\fB::crimp\fR \fBexpand wrap\fR \fIimage\fR \fIww\fR \fIhn\fR \fIwe\fR \fIhs\fR
This set of methods takes an image and expands it by adding a border.
The size of this border is specified by the four arguments \fIww\fR,
\fIhn\fR, \fIwe\fR, and \fIhs\fR which provide the number of pixels to
add at the named edge. See the image below for a graphical
representation.
.sp
.PS
.nf
|< ww >| |< we >|
- +------+-----------+------+
^ | | | |
hn | | | |
V | | | |
- +------+-----------+------+
| | | |
| | | |
| | | |
| | | |
- +------+-----------+------+
^ | | | |
hs | | | |
V | | | |
- +------+-----------+------+
.fi
.PE
.sp
The contents of the border's pixels are specified via the border type,
the first argument after \fBexpand\fR, as per the list below.
.RS
.TP
\fBconst\fR
The additional \fIvalue\fRs specify the values to use for the color
channels of the image. Values beyond the number of channels in the
image are ignored.
Missing values are generated by replicating the last value, except for
the alpha channel, which will be set to \fB255\fR. If no values are
present they default to \fB0\fR.
.TP
\fBextend\fR
This is a combination of \fBmirror\fR and \fBreplicate\fR. The
outside pixels are the result of subtracting the outside pixel for
\fBmirror\fR from the outside pixel for \fBreplicate\fR (and
clamping to the range [0...255]).
.TP
\fBmirror\fR
The outside pixels take the value of the associated inside pixels,
found by reflecting its coordinates along the relevant edges.
.TP
\fBreplicate\fR
The outside pixels take the value of the associated edge pixels, i.e.
replicating them into the border.
.TP
\fBwrap\fR
The outside pixels take the value of the associated inside pixels,
found by toroidial (cyclic) wrapping its coordinates along the
relevant edges. This is also called tiling.
.RE
.TP
\fB::crimp\fR \fBfilter convolve\fR ?\fB-border\fR \fIspec\fR? \fIkernel\fR...
This method runs the series of filters specified by the convolution
\fIkernel\fRs over the input and returns the filtered result. See the
method \fBkernel\fR and its sub-methods for commands to create and
manipulate suitable kernels.
.sp
The border specification determines how the input image is
expanded (see method \fBexpand\fR) to compensate for the shrinkage
introduced by the filter itself. The \fIspec\fR argument is a list
containing the name of the sub-method of \fBexpand\fR to use, plus
any additional arguments this method may need, except for the size of
the expansion.
.sp
By default a black frame is used as the border, i.e.
"\fIspec\fR == {const 0}".
.TP
\fB::crimp\fR \fBfilter rank\fR ?\fB-border\fR \fIspec\fR? ?\fIradius\fR ?\fIpercentile\fR??
This method runs a rank-filter over the input and returns the filtered
result.
.sp
The border specification determines how the input image is
expanded (see method \fBexpand\fR) to compensate for the shrinkage
introduced by the filter itself. The \fIspec\fR argument is a list
containing the name of the sub-method of \fBexpand\fR to use, plus
any additional arguments this method may need, except for the size of
the expansion.
.sp
By default a black frame is used as the border, i.e.
"\fIspec\fR == {const 0}".
.sp
The \fIradius\fR specifies the (square) region around each
pixel which is taken into account by the filter, with the pixel value
selected according to the \fIpercentile\fR. The filter region of each
pixel is a square of dimensions "2*\fIradius\fR+1", centered around
the pixel.
.sp
These two values default to \fB3\fR and \fB50\fR, respectively.
.sp
Typical applications of rank-filters are min-, max-, and
median-filters, for percentiles 0, 100, and 50, respectively.
.sp
Note that percentiles outside of the range \fB0\fR...\fB100\fR
make no sense and are clamped to this range.
.TP
\fB::crimp\fR \fBgamma\fR \fIimage\fR \fIy\fR
This method takes an image, runs it through a \fBgamma correction\fR
with parameter \fIy\fR, and returns the corrected image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap gamma\fR \fIy\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBinvert\fR \fIimage\fR
This method takes an image, runs it through the \fBinverse\fR
function, and returns the modified image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap inverse\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBmatrix\fR \fIimage\fR \fImatrix\fR
This method takes an image and a 3x3 matrix specified as nested Tcl
list (row major order), applies the projective transform represented
by the matrix to the image and returns the transformed image as its
result.
.sp
Notes: It is currently unclear how the output pixel is computed
(nearest neighbour, bilinear, etc.) (code inherited from AMG). This
requires more reading, and teasing things apart. The transfomred image
is clipped to the dimensions of the input image, i.e. pixels from the
input may be lost, and pixels in the output may be unset as their
input would come from outside of the input.
.sp
The operation supports only images of type \fBrgba\fR, and returns
images of the same type.
.TP
\fB::crimp\fR \fBpsychedelia\fR \fIwidth\fR \fIheight\fR \fIframes\fR
This method creates an \fBrgba\fR image of the specified dimensions
according to an algorithm devised by Andrew M. Goth. The \fIframes\fR
argument specifies how many images are in the series.
.sp
\fIAttention:\fR This method keeps internal global state,
ensuring that each call returns a slightly different image. Showing a
series of such images as animation provides an effect similar to a
lava lamp or hallucination.
.TP
\fB::crimp\fR \fBpyramid run\fR \fIimage\fR \fIsteps\fR \fIstepcmd\fR
This method provides the core functionality for the generation of image
pyramids. The command prefix \fIstepcmd\fR is run \fIsteps\fR times,
first on the \fIimage\fR, then on the result of the previous step.
.sp
The assumed signature of \fIstepcmd\fR is
.RS
.TP
\fB<stepcmd>\fR \fIimage\fR
which is expected to return a list of two elements. The first element
(\fIresult\fR) is added to the pyramid in building, whereas the second
element (\fIiter\fR) is used in the next step as the input of the step
command.
.RE
.sp
The final result of the method is a list containing the input
\fIimage\fR as its first element, followed by the results of the step
function, followed by the \fIiter\fR element returned by the last step,
"\fIsteps\fR+2" images in total.
.sp
IMAGE: pyramid
.TP
\fB::crimp\fR \fBpyramid gauss\fR \fIimage\fR \fIsteps\fR
This method generates a gaussian image pyramid \fIsteps\fR levels deep and
returns it as a list of images.
.sp
The first image in the result is the input, followed by \fIsteps\fR
successively smaller images, each \fBdecimate\fRd by a factor two
compared to its predecessor, for a total length of "\fIsteps\fR+1" images.
.sp
The convolution part of the decimation uses
.nf
1/16 [1 4 6 4 1]
.fi
as its kernel.
.sp
IMAGE: pyramid_gauss
.TP
\fB::crimp\fR \fBpyramid laplace\fR \fIimage\fR \fIsteps\fR
This method generates a laplacian image pyramid \fIsteps\fR levels deep and
returns it as a list of images.
.sp
The first image in the result is the input, followed by \fIsteps\fR
band pass images (differences of gaussians). The first band pass has the same
size as the input image, and each successor is \fBdecimate\fRd by two. This
is followed by one more image, the gaussian of the last step. This image has
the same dimensions as the preceding bandpass image. In total the result
contains "\fIsteps\fR+2" images.
.sp
The convolution part of the decimation uses
.nf
1/16 [1 4 6 4 1]
.fi
as its kernel. The internal interpolation used to generate the band pass
images (resynthesis) doubles the weights of this kernel for its convolution
step.
.sp
IMAGE: pyramid_laplace
.TP
\fB::crimp\fR \fBremap\fR \fIimage\fR \fImap\fR...
This method is the core primitive for the per-pixel transformation of
images, with each pixel (and channels within, if any) handled
independently of all others.
Applications of this operator provided by this package are (inverse)
gamma correction, pixel inversion, and solarization. Many more are
possible, especially when considering other colorspaces like
HSV. There, for example, it is possible change the saturation of
pixels, or shift the hue in arbitrary manner.
.sp
Beyond the input \fIimage\fR to transform one or more \fImaps\fR are
specified which define how each pixel value in the input is mapped to
a pixel value in the output. The command will accept at most that many
maps as the input image has channels. If there are less maps than
channel the last map specified is replicated to cover the other
channels. An exception of this is the handling of the alpha channel,
should the input image have such. There a missing map is handle as
\fBidentity\fR, i.e. the channel copied as is, without changes.
.sp
The maps are not Tcl data structures, but images themselves. They
have to be of type \fBgrey8\fR, and be of dimension 256x1 (width by
height).
.sp
The \fBcrimp map ...\fR methods are sources for a number of
predefined maps. And the \fBread tcl\fR method allows the
construction of maps from Tcl data structures, namely nested lists.
.sp
This method supports all image types with one or more
single-byte channels, i.e. all but \fBgrey16\fR, \fBgrey32\fR, and
\fBbw\fR.
.TP
\fB::crimp\fR \fBsolarize\fR \fIimage\fR \fIthreshold\fR
This method takes an image, runs it through the \fBsolarize\fR
function with parameter \fIthreshold\fR, and returns the modified
image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap solarize\fR \fIthreshold\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBthreshold-ge\fR \fIimage\fR \fIthreshold\fR
This method takes an image, runs it through the \fBthreshold-ge\fR
function with parameter \fIthreshold\fR, and returns the modified
image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap threshold-ge\fR \fIthreshold\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBthreshold-le\fR \fIimage\fR \fIthreshold\fR
This method takes an image, runs it through the \fBthreshold-le\fR
function with parameter \fIthreshold\fR, and returns the modified
image as it result.
This is an application of method \fBremap\fR, using the mapping
returned by "\fBmap threshold-le\fR \fIthreshold\fR".
This method supports all image types supported by the method
\fBremap\fR.
.TP
\fB::crimp\fR \fBwavy\fR \fIimage\fR \fIoffset\fR \fIadj1\fR \fIadjb\fR
This method processes the input \fIimage\fR according to an algorithm
devised by Andrew M. Goth, according to the three parameters
\fIoffset\fR, \fIadj1\fR, and \fIadjb\fR, and returns the modified
image as its result.
.sp
The operation supports only images of type \fBrgba\fR, and returns
images of the same type.
.TP
\fB::crimp\fR \fBflip horizontal\fR \fIimage\fR
.TP
\fB::crimp\fR \fBflip transpose\fR \fIimage\fR
.TP
\fB::crimp\fR \fBflip transverse\fR \fIimage\fR
.TP
\fB::crimp\fR \fBflip vertical\fR \fIimage\fR
This set of methods performs mirroring along the horizontal, vertical
and diagonal axes of the input \fIimage\fR, returning the mirrored
image as their output. Transpose mirrors along the main diagonal,
transverse along the secondary diagonal. These two methods also
exchange width and height of the image in the output.
.sp
The methods currently support the image types \fBrgb\fR,
\fBrgba\fR, \fBhsv\fR, and \fBgrey8\fR.
.PP
.SS CONVERTERS
.TP
\fB::crimp\fR \fBconvert 2grey8\fR \fIimage\fR
.TP
\fB::crimp\fR \fBconvert 2hsv\fR \fIimage\fR
.TP
\fB::crimp\fR \fBconvert 2rgba\fR \fIimage\fR
.TP
\fB::crimp\fR \fBconvert 2rgb\fR \fIimage\fR
This set of methods all convert their input \fIimage\fR to the
specified type and returns it as their result.
.sp
The converters returning a \fBgrey8\fR image support \fBrgb\fR and
\fBrgba\fR as their input, using the ITU-R 601-2 luma transform to
merge the three color channels
.sp
The converters to HSV support \fBrgb\fR and \fBrgba\fR as their
input as well.
.sp
The conversion to \fBrgba\fR accepts only \fBhsv\fR as input,
adding a blank (fully opaque) alpha channel. For more control over the
contents of an image's alpha channel see the methods \fBsetalpha\fR
and \fBjoin rgba\fR.
.sp
At last, the conversion to \fBrgb\fR accepts both \fBrgba\fR and
\fBhsv\fR images as input.
.TP
\fB::crimp\fR \fBjoin 2hsv\fR \fIhueImage\fR \fIsatImage\fR \fIvalImage\fR
.TP
\fB::crimp\fR \fBjoin 2rgba\fR \fIredImage\fR \fIgreenImage\fR \fIblueImage\fR \fIalphaImage\fR
.TP
\fB::crimp\fR \fBjoin 2rgb\fR \fIredImage\fR \fIgreenImage\fR \fIblueImage\fR
This set of methods is the complement of method \fBsplit\fR. Each
take a set of \fBgrey8\fR images and fuse them together into an
image of the given type, with each input image becoming one channel of
the fusing result, which is returned as the result of the command. All
input images have to have the same dimensions.
.TP
\fB::crimp\fR \fBsplit\fR \fIimage\fR
This method takes an image of one of the multi-channel types, i.e.
\fBrgb\fR, const rgba], and \fBhsv\fR and returns a list of
\fBgrey8\fR images, each of which contains the contents of one of
the channels found in the input image.
.sp
The channel images in the result are provided in the same order as
they are accepted by the complementary \fBjoin\fR method, see
above.
.PP
.SS "I/O COMMANDS"
.TP
\fB::crimp\fR \fBread tcl\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
\fB255\fR.
.TP
\fB::crimp\fR \fBread tk\fR \fIphoto\fR
This method returns an image of type \fBrgba\fR containing the data
from the specified Tk \fIphoto\fR image.
.TP
\fB::crimp\fR \fBwrite 2tk\fR \fIphoto\fR \fIimage\fR
This method writes the input \fIimage\fR to the specified Tk
\fIphoto\fR image.
.sp
The method supports the witing of \fBrgb\fR, \fBrgba\fR,
and \fBgrey8\fR images.
.PP
.SS SUPPORT
.TP
\fB::crimp\fR \fBkernel make\fR \fImatrix\fR ?\fIscale\fR?
This method takes a \fImatrix\fR of weights and an optional
\fIscale\fR factor and returns a structure containing the associated
convolution kernel, ready for use by method \fBconvole\fR.
.sp
If \fIscale\fR is left unspecified it defaults to the sum of
all weights in the matrix.
.sp
The \fImatrix\fR has the same general format as the pixel
matrix for method \fBread tcl\fR, i.e. a list of lists (rows) of
values, and is treated in the same way, i.e. the number of columns is
the maxium length over the row lists, and shorter lists are padded
with \fB255\fR.
.TP
\fB::crimp\fR \fBkernel transpose\fR \fIkernel\fR
This method takes a \fIkernel\fR as returned by the method
\fBkernel make\fR and returns a transposed kernel, i.e. one where
the x- and y-axes are switched.
For example
.sp
.nf
(1)
(2)
{1 2 4 2 1} ==> (4)
(2)
(1)
.fi
.sp
This method is its own inverse, i.e. application to its result returns
the original input, i.e.
.nf
[transpose [transpose $K]] == $K
.fi
.TP
\fB::crimp\fR \fBmap\fR \fIarg\fR...
This method accepts the same sub-methods and arguments as are accepted
by the \fBtable\fR method below. In contrast to \fBtable\fR the
result is not a list of values, but a map image directly suitable as
argument to the \fBremap\fR method.
.TP
\fB::crimp\fR \fBtable degamma\fR \fIy\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBinverse gamma correction\fR with
parameter \fIy\fR.
This inverse correction, defined in the domain of [0..1] for
both argument and result, is defined as:
.sp
.PS
.nf
gamma^{-1}_y (x) = x^{\\frac{1}{y}}
.fi
.PE
.sp
Scaling of argument and result into the domain [0..255] of pixel
values, and rounding results to the nearest integer, causes the actual
definition used to be
.sp
.PS
.nf
gamma^{-1}_y (x) = [ 255 (\\frac{x}{255})^{\\frac{1}{y}} ]
.fi
.PE
.TP
\fB::crimp\fR \fBtable gainw\fR \fIgain\fR \fIbias\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through a simple linear function with parameters
\fIgain\fR and \fIbias\fR. The results are rounded to the nearest
integer and forced into the domain [0..255] by wrapping them
around (modulo), making the definition:
.sp
.PS
.nf
f^{wrap}_{gain,bias} (x) = [ gain x + bias ] \\oplus_{256} 0
.fi
.PE
.TP
\fB::crimp\fR \fBtable gain\fR \fIgain\fR \fIbias\fR
This method is like \fBgainw\fR, except that it deals with results
out of the domain [0..255] by clamping them to 0 and 255
respectively instead of wrapping around. I.e. its definition is
.sp
.PS
.nf
f^{clamp}_{gain,bias} (x) = min (0, max (255, [ gain x + bias ]))
.fi
.PE
.TP
\fB::crimp\fR \fBtable gamma\fR \fIy\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBgamma correction\fR with parameter
\fIy\fR.
This correction, defined in the domain of [0..1] for both
argument and result, is defined as:
.sp
.PS
.nf
gamma_y (x) = x^y
.fi
.PE
.sp
Scaling of argument and result into the domain [0..255] of pixel
values, and rounding results to the nearest integer, causes the actual
definition used to be
.sp
.PS
.nf
gamma_y (x) = [ 255 (\\frac{x}{255})^y ]
.fi
.PE
.TP
\fB::crimp\fR \fBtable gauss\fR \fIsigma\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBsampled gauss\fR function with
parameter \fIsigma\fR.
This function is defined as:
.sp
.PS
.nf
gauss_\\sigma (x) = [255 e^{-\\frac{x-127.5}{2\\sigma^2}}]
.fi
.PE
.sp
.TP
\fB::crimp\fR \fBtable identity\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBidentity\fR function, defined as
.sp
.PS
.nf
identity (x) = x
.fi
.PE
.TP
\fB::crimp\fR \fBtable invers\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBinverse\fR function, defined as
.sp
.PS
.nf
inverse (x) = 255 - x
.fi
.PE
.TP
\fB::crimp\fR \fBtable solarize\fR \fIthreshold\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through the \fBsolarize\fR function, with parameter
\fIthreshold\fR. The function is defined as:
.sp
.PS
.nf
solarize_{threshold} (x) = \\left\\{\\begin{eqnarray}
x & x < threshold \\\\
255 - x & x \\ge threshold \\\\
\\end{eqnarray}\\right
.fi
.PE
.sp
Note how the function is the \fBidentity\fR for values under the
threshold, and the \fBinverse\fR for values at and above it.
.TP
\fB::crimp\fR \fBtable threshold-ge\fR \fIthreshold\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through a \fBthresholding\fR function, with parameter
\fIthreshold\fR. The function is defined as:
.sp
.PS
.nf
threshold_{threshold} (x) = \\left\\{\\begin{eqnarray}
0 & x \\ge threshold \\\\
255 & x < threshold \\\\
\\end{eqnarray}\\right
.fi
.PE
.sp
.TP
\fB::crimp\fR \fBtable threshold-le\fR \fIthreshold\fR
This method returns a list of 256 values, the result of running the
values 0 to 255 through a \fBthresholding\fR function, with parameter
\fIthreshold\fR. The function is defined as:
.sp
.PS
.nf
threshold_{threshold} (x) = \\left\\{\\begin{eqnarray}
0 & x \\le threshold \\\\
255 & x > threshold \\\\
\\end{eqnarray}\\right
.fi
.PE
.sp
.PP
.SH KEYWORDS
affine transform, alpha, alpha blending, alpha channel, binarization, blending, channels, composite blending, composition, const expansion, convolution filter, cyclic wrap expansion, dimensions, expansion, extend expansion, filter, flip, gamma correction, histogram, image, inversion, matrix, max-filter, median-filter, min-filter, mirror expansion, photo, pixel mapping, projective transform, rank-order filter, remapping, replicate edge expansion, sabatier effect, solarization, thresholding, toroidal wrap expansion, transform, wrap expansion
.SH COPYRIGHT
.nf
Copyright (c) 2010 Andreas Kupries
Copyright (c) 2010 Documentation, Andreas Kupries
.fi