crimp(n) 1.0.1 doc "Image Manipulation"

This method returns a list containing the names of the channels in the image. The order of channels is the same as expected by the remap method.

The method supports all image types.

This method returns the width and height of the image (in pixels). The result is a 2-element list containing width and height, in this order.

The method supports all image types.

This method returns the height of the image (in pixels).

The method supports all image types.

This method returns a nested dictionary as its result. The outer dictionary is indexed by the names of the channels in the image. Its values, the inner dictionaries, are indexed by pixel value. The associated values are the number of pixels with that value.

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

This method returns the raw pixels of the image as a Tcl ByteArray.

The method supports all image types.

This method returns a nested dictionary as its result. The outer dictionary contains basic information about the image, see the list of keys below. The inner dictionaries hold data about each (color) channel in the image, namely histogram and derived data like minumum pixel value, maximum, etc.

channels

List of the names for the channels in the image.

dimensions

2-element list holding image width and height, in this order.

height

Image height as separate value.

pixels

Number of pixels in the image, the product of its width and height.

type

Type of the image.

width

Image width as separate value.

channel *

Per channel named in key channels, where * is the place holder for the channel name. A dictionary holding the statistics for that channel.

min

The minimal pixel value with a non-zero population.

max

The maximal pixel value with a non-zero population.

mean

The arithmetic mean of pixel values.

median

The median pixel value.

stddev

The standard deviation of pixel values.

variance

The variance of pixel values, square of the standard deviation.

histogram

A dictionary mapping pixel values to population counts.

hf

The histogram reduced to the population counts, sorted by pixel value to direct indexing into the list by pixel values.

cdf

The cumulative density function of pixel values. The discrete integral of hf.

cdf255

Same as cdf, except scaled down so that the last value in the series is 255.

The method supports all image types except "grey32". Under the current system the result would contain internal dictionaries 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).

This method returns the type of the image.

The method supports all image types.

This method returns the width of the image (in pixels).

The method supports all image types.

This method combines the two input images into a result image by performing a pixelwise addition (image1 + image2) followed by division through scale and addition of the offset. They default to 1 and 0 respectively, if they are not specified.

This method takes two images of identical dimensions and a blending factor alpha and returns an image which is a mix of both, with each pixel blended per the formula

or, alternatively written

This means that the foreground is returned as is for "alpha == 255", and the background for "alpha == 0". I.e. the argument alpha controls the opacity of the foreground, with 1 and 0 standing for "fully opaque" and "fully transparent", respectively.

The following combinations of fore- and background image types are supported:

    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
    ------   ---------- ----------

This command takes two images, the input and a mask, and returns an image as result in which the mask is the alpha channel of the input. The result is therefore always of type rgba, as the only type supporting an alpha channel.

The input image can be of type rgb or rgba. In case of the latter the existing alpha channel is replaced, in case of the former an alpha channel is added.

For the mask images of type grey8 and rgba 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.

A convenience method over alpha set, giving the image a mask which makes it fully opaque.

This method is similar to blend above, except that there is no global blending parameter. This information is taken from the "alpha" channel of the foreground 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.

Due to the need for an alpha channel the foreground has to be of type rgba. For the background image the types rgb and rgba are supported.

This method returns a blank image of the given image type and dimensions. The values after the dimensions are the pixel values to fill the pixels in the image's channels with, per its type.

This method currently support only the types rgb, rgba, and grey8.

This method is the counterpart to the expand family of methods, shrinking an image by removing a border. The size of this border is specified by the four arguments ww, hn, we, and hs which provide the number of pixels to remove from the named edge. See the image below for a graphical representation.

This method cuts the rectangular region specified throught its x/y position relative to the upper-left corner of the input image and its dimensions, and returns it as its own image.

This is a convenience method combining the two steps of filtering an image (via filter convolve), followed by a downsample step. See the method interpolate for the complementary operation.

Note that while the kernel argument for filter convolve is expected to be the 1D form of a separable low-pass filter no checks are made. The method simply applies both the kernel and its transposed form.

The method pyramid gauss is a user of this method.

This method takes an image, runs it through an inverse gamma correction with parameter y, and returns the corrected image as it result. This is an application of method remap, using the mapping returned by "map degamma y". This method supports all image types supported by the method remap.

This method combines the two input images into a result image by taking the pixelwise absolute difference (|image1 - image2|).

This method returns an image containing only every factor pixel of the input image (in both dimensions). The effect is that the input is shrunken by factor. It is the complement of method upsample.

Using the method as is is not recommended because the simple subsampling will cause higher image frequencies to alias into the reduced spectrum, causing artifacts to appear in the result. This is normally avoided by running a low-pass filter over the image before doing downsampling, removing the problematic frequencies.

The decimate method is a convenience method combining these two steps into one.

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 ww, hn, we, and hs which provide the number of pixels to add at the named edge. See the image below for a graphical representation.

The contents of the border's pixels are specified via the border type, the first argument after expand, as per the list below.

const

The additional values 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 255. If no values are present they default to 0.

extend

This is a combination of mirror and replicate. The outside pixels are the result of subtracting the outside pixel for mirror from the outside pixel for replicate (and clamping to the range [0...255]).

mirror

The outside pixels take the value of the associated inside pixels, found by reflecting its coordinates along the relevant edges.

replicate

The outside pixels take the value of the associated edge pixels, i.e. replicating them into the border.

wrap

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.

This method runs the series of filters specified by the convolution kernels over the input and returns the filtered result. See the method kernel and its sub-methods for commands to create and manipulate suitable kernels.

The border specification determines how the input image is expanded (see method expand) to compensate for the shrinkage introduced by the filter itself. The spec argument is a list containing the name of the sub-method of expand to use, plus any additional arguments this method may need, except for the size of the expansion.

By default a black frame is used as the border, i.e. "spec == {const 0}".

This method runs a rank-filter over the input and returns the filtered result.

The border specification determines how the input image is expanded (see method expand) to compensate for the shrinkage introduced by the filter itself. The spec argument is a list containing the name of the sub-method of expand to use, plus any additional arguments this method may need, except for the size of the expansion.

By default a black frame is used as the border, i.e. "spec == {const 0}".

The radius specifies the (square) region around each pixel which is taken into account by the filter, with the pixel value selected according to the percentile. The filter region of each pixel is a square of dimensions "2*radius+1", centered around the pixel.

These two values default to 3 and 50, respectively.

Typical applications of rank-filters are min-, max-, and median-filters, for percentiles 0, 100, and 50, respectively.

Note that percentiles outside of the range 0...100 make no sense and are clamped to this range.

This method takes an image, runs it through a gamma correction with parameter y, and returns the corrected image as it result. This is an application of method remap, using the mapping returned by "map gamma y". This method supports all image types supported by the method remap.

This is a convenience method combining the two steps of an upsample, followed by a filter step (via filter convolve). See the method decimate for the complementary operation.

Note that while the kernel argument for filter convolve is expected to be 1D form of a separable low-pass filter no checks are made. The method simply applies both the kernel and its transposed form.

The methods pyramid gauss and pyramid laplace are users of this method.

This method takes an image, runs it through the inverse function, and returns the modified image as it result. This is an application of method remap, using the mapping returned by "map inverse". This method supports all image types supported by the method remap.

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.

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.

The operation supports only images of type rgba, and returns images of the same type.

This method combines the two input images into a result image by taking the pixelwise maximum.

This method combines the two input images into a result image by taking the pixelwise minimum.

The result of these methods is an image where the input images have been placed adjacent to each from left to right (horizontal), or top to bottom (vertical). The input images have to have the same type, and the same height, or width, respectively.

These two methods implement the basic set of morphology operations, erosion, and dilation using a flat 3x3 brick as their structuring element. For grayscale, which we have here, these are, mathematically, max and min rank-order filters, i.e.

    dilate = filter rank 1  0.00 (min)
    erode  = filter rank 1 99.99 (max)

These two methods add to the basic set of morphology operations, opening and closing. In terms of erosion and dilation:

    close = erode o dilate 
    open  = dilate o erode

The morphological gradient is defined as

    [dilate $image] - [erode $image]

This can also be expressed as the sum of the external and internal gradients, see below.

The morphological internal gradient is defined as

    $image - [erode image]

The morphological external gradient is defined as

    [dilate $image] - $image

The white tophat transformation is defined as

    $image - [open $image]

The black tophat transformation is defined as

    [close $image] - $image

This method combines the two input images into a result image by performing a pixelwise multiplication. Note that the result of each multiplication is divided by 255 to scale it back into the range [0...255].

This method creates an rgba image of the specified dimensions according to an algorithm devised by Andrew M. Goth. The frames argument specifies how many images are in the series.

Attention: 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.

This method provides the core functionality for the generation of image pyramids. The command prefix stepcmd is run steps times, first on the image, then on the result of the previous step.

The assumed signature of stepcmd is

<stepcmd> image

which is expected to return a list of two elements. The first element (result) is added to the pyramid in building, whereas the second element (iter) is used in the next step as the input of the step command.

The final result of the method is a list containing the input image as its first element, followed by the results of the step function, followed by the iter element returned by the last step, "steps+2" images in total.

This method generates a gaussian image pyramid steps levels deep and returns it as a list of images.

The first image in the result is the input, followed by steps successively smaller images, each decimated by a factor two compared to its predecessor, for a total length of "steps+1" images.

The convolution part of the decimation uses

 1/16 [1 4 6 4 1] 

as its kernel.

This method generates a laplacian image pyramid steps levels deep and returns it as a list of images.

The first image in the result is the input, followed by steps band pass images (differences of gaussians). The first band pass has the same size as the input image, and each successor is decimated by two. This is followed by one more image, the gaussian of the last step. This image is decimated by two compared to the preceding bandpass image. In total the result contains "steps+2" images.

The convolution part of the decimation uses

 1/16 [1 4 6 4 1] 

as its kernel. The internal interpolation used to generate the band pass images (resynthesis) doubles the weights of this kernel for its convolution step.

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.

Beyond the input image to transform one or more maps 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 identity, i.e. the channel copied as is, without changes.

The maps are not Tcl data structures, but images themselves. They have to be of type grey8, and be of dimension 256x1 (width by height).

The crimp map ... methods are sources for a number of predefined maps, whereas the mapof method allows the construction of maps from Tcl data structures, namely lists of values.

This method supports all image types with one or more single-byte channels, i.e. all but grey16, grey32, float, and bw.

This method combines the two input images by inverting the multiplication of the inverted input images. I.e.

This method takes an image, runs it through the solarize function with parameter threshold, and returns the modified image as it result. This is also known as the sabattier effect. This is an application of method remap, using the mapping returned by "map solarize threshold". This method supports all image types supported by the method remap.

This method combines the two input images into a result image by performing a pixelwise subtraction (image1 - image2) followed by division through scale and addition of the offset. They default to 1 and 0 respectively, if they are not specified.

This method takes an image, runs it through the threshold above function with parameter threshold, and returns the modified image as it result. As the result only contains black and white, i.e. 2 colors, this process is also called binarization or foreground/background segmentation. This is an application of method remap, using the mapping returned by "map threshold above threshold". This method supports all image types supported by the method remap.

This method takes an image, runs it through the threshold below function with parameter threshold, and returns the modified image as it result. As the result only contains black and white, i.e. 2 colors, this process is also called binarization, or foreground/background segmentation. This is an application of method remap, using the mapping returned by "map threshold below threshold". This method supports all image types supported by the method remap.

This method takes an image, runs it through the threshold inside function with parameters min and max, and returns the modified image as it result. As the result only contains black and white, i.e. 2 colors, this process is also called binarization or foreground/background segmentation. This is an application of method remap, using the mapping returned by "map threshold above threshold". This method supports all image types supported by the method remap.

This method takes an image, runs it through the threshold outside function with parameters min and max, and returns the modified image as it result. As the result only contains black and white, i.e. 2 colors, this process is also called binarization, or foreground/background segmentation. This is an application of method remap, using the mapping returned by "map threshold below threshold". This method supports all image types supported by the method remap.

This method takes an image and one or more threshold maps and returns an image where all pixels of the input which were larger or equal to the corresponding pixel in the map are set to black. All other pixels are set to white. Each map is applied to one color channel of the input image. If there are too many maps the remainder is ignored. If there are not enough maps the last map is replicated.

This is the core for all methods of non-global binarization, i.e. foreground/background segmentation. Their differences are just in the calculation of the maps.

This method supports all image types with one or more single-byte channels, i.e. all but grey16, grey32, and bw.

This method returns an image inserting factor black pixels between each pixel of the input image (in both dimensions). The effect is that the input is expanded by factor. It is the complement of method downsample.

Using the method as is is not recommended because this simple upsampling will cause copies of the image to appear at the higher image frequencies in the expanded spectrum. This is normally avoided by running a low-pass filter over the image after the upsampling, removing the problematic copies.

The interpolate method is a convenience method combining these two steps into one.

This method processes the input image according to an algorithm devised by Andrew M. Goth, according to the three parameters offset, adj1, and adjb, and returns the modified image as its result.

The operation supports only images of type rgba, and returns images of the same type.

This set of methods performs mirroring along the horizontal, vertical and diagonal axes of the input image, 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.

The methods currently support the image types rgb, rgba, hsv, and grey8.

This set of methods rotates the image in steps of 90 degrees, either clockwise and counter to it.

This methods rotates the image a half-turn, i.e. 180 degrees.

This set of methods all convert their input image to the specified type and returns it as their result. All converters accept an image of the destination type as input and will pass it through unchanged.

The converters returning a grey8 image support rgb and rgba as their input, using the ITU-R 601-2 luma transform to merge the three color channels

The converters to HSV support rgb and rgba as their input as well.

The conversion to rgba accepts only hsv as input, adding a blank (fully opaque) alpha channel. For more control over the contents of an image's alpha channel see the methods setalpha and join rgba.

At last, the conversion to rgb accepts both rgba and hsv images as input.

This set of methods is the complement of method split. Each take a set of grey8 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.

This method takes an image of one of the multi-channel types, i.e. rgb, const rgba], and hsv and returns a list of grey8 images, each of which contains the contents of one of the channels found in the input image.

The channel images in the result are provided in the same order as they are accepted by the complementary join method, see above.

This method returns an image of type grey8 containing the data of the portable grey map (PGM) stored in the string. The method recognizes images in both plain and raw sub-formats.

This method returns an image of type rgb containing the data of the portable pix map (PPM) stored in the string. The method recognizes images in both plain and raw sub-formats.

This method returns an image of type rgba containing the data of the strimj (string image) (See http://wiki.tcl.tk/1846) stored in the string.

The caller can override the standard mapping from pixel characters to colors by specifying a colormap. This argument is interpreted as dictionary mapping characters to triples of integers in the range [0...255], specifying the red, green, and blue intensities.

An example of a strimj is:

@...@.......@.@......
@...@.......@.@......
@...@..@@@..@.@..@@@.
@@@@@.@...@.@.@.@...@
@...@.@@@@@.@.@.@...@
@...@.@.....@.@.@...@
@...@.@...@.@.@.@...@
@...@..@@@..@.@..@@@.

This method takes the pixelmatrix, a list of rows, with each row a list of pixel values in the domain [0..255] and returns an image of type grey8 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 255.

This method takes the pixelmatrix, a list of rows, with each row a list of floating point values for pixel values and returns an image of type float 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 255.

This method returns an image of type rgba containing the data from the specified Tk photo image.

This method writes the input image to the specified Tk photo image.

The method supports the writing of rgb, rgba, and grey8 images.

This family of methods either returns the input image as a binary string in the specified format, or writes this string to the open channel chan, or the named file at path.

The image types accepted for writing are format dependent, and listed below, with the supported formats.

The currently supported formats are

pgm-plain

The plain ASCII format of portable grey maps, as per http://en.wikipedia.org/wiki/Netpbm_format.

The methods support the writing of rgb, rgba, hsv, and grey8 images.

pgm-raw

The raw binary format of portable grey maps, as per http://en.wikipedia.org/wiki/Netpbm_format.

The methods support the writing of rgb, rgba, hsv, and grey8 images.

ppm-plain

The plain ASCII format of portable pix maps, as per http://en.wikipedia.org/wiki/Netpbm_format.

The methods support the writing of rgb, rgba, hsv, and grey8 images.

ppm-raw

The raw binary format of portable pix maps, as per http://en.wikipedia.org/wiki/Netpbm_format.

The methods support the writing of rgb, rgba, hsv, and grey8 images.

This method takes a matrix of weights and an optional scale factor and returns a structure containing the associated convolution kernel, ready for use by method filter convolve.

If scale is left unspecified it defaults to the sum of all weights in the matrix.

If offset is left unspecified it defaults to 128 if the sum of weights is 0, and 0 else. In effect zero-sum kernels, like the basic edge-detectors, are shifted so that results in the range -128..127 correspond to 0..255.

The matrix has the same general format as the pixel matrix for method read tcl grey8, 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 128. The values are expected to be integer numbers in the range -128..127.

This method is like kernel make except that the generated kernel is based on floating-point values. Because of this it is not accpeting a scale argument either, it is expected that the kernel weights already have the proper sum.

The matrix has the same general format as the pixel matrix for method read tcl float, 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 255. The values are expected to be floating-point numbers.

This method takes a kernel as returned by the method kernel make and returns a transposed kernel, i.e. one where the x- and y-axes are switched. For example

                    (1)
                    (2)
    {1 2 4 2 1} ==> (4)
                    (2)
                    (1)

This method is its own inverse, i.e. application to its result returns the original input, i.e.

    [transpose [transpose $K]] == $K

This method accepts the same sub-methods and arguments as are accepted by the table method below. In contrast to table the result is not a list of values, but a map image directly suitable as argument to the remap method.

This method accepts a list of 256 values, constructs a map image directly suitable as argument to the remap method, and returns this map image as its result.

This accepts two lookup tables (aka functions) specified as lists of 256 values, constructs the composite function f(g(x)), and then returns this new function as its result.

This method returns a list of 256 values, the result of running the values 0 to 255 through the function specified by the command prefix cmd. The results returned by the command prefix are rounded to the nearest integer and then forced into the domain [0..255] by either wrapping them around (modulo 256), or clamping them to the appropriate border, i.e 0, and 255 respectively. This is controlled by the presence of the option -wrap. When present the values are wrapped, otherwise (default) they are clamped.

The signature of the command prefix is

<cmd> x

which is expected to return a number in the range [0..255]. While the result should be an integer number it is allowed to be a float, the caller takes care to round the result to the nearest integer.

This method returns a list of 256 values, the result of running the values 0 to 255 through the inverse gamma correction with parameter y. This inverse correction, defined in the domain of [0..1] for both argument and result, is defined as:

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

This method returns a list of 256 values, the result of running the values 0 to 255 through the gamma correction with parameter y. This correction, defined in the domain of [0..1] for both argument and result, is defined as:

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

This method returns a list of 256 values, the result of running the values 0 to 255 through the sampled gauss function with parameter sigma. This function is defined as:

This method returns a list of 256 values, the result of running the values 0 to 255 through the identity function, which is defined as

This method returns a list of 256 values, the result of running the values 0 to 255 through the inverse function, which is defined as

This method returns a list of 256 values, the result of running the values 0 to 255 through a simple linear function with parameters gain (the slope) and offset. The results are rounded to the nearest integer and then forced into the domain [0..255] by either wrapping them around (modulo 256), or clamping them to the appropriate border, i.e 0, and 255 respectively. This is controlled by the presence of the option -wrap. When present the values are wrapped, otherwise (default) they are clamped. Thus the relevant definitions are

for the wrapped case, and

when clamping.

This method returns a list of 256 values, the result of running the values 0 to 255 through the log-compression function with parameter max. This parameter is the maximum pixel value the function is for, this value, and all larger will be mapped to 255. This function is defined as:

This method returns a list of 256 values, the result of running the values 0 to 255 through the solarize function, with parameter threshold. This function is defined as:

Note how the function is the identity for values under the threshold, and the inverse for values at and above it. Its application to an image produces what is known as either solarization or sabattier effect.

This method returns a list of 256 values, the result of running the values 0 to 255 through the sqrt-compression function with parameter max. This parameter is the maximum pixel value the function is for, this value, and all larger will be mapped to 255. This function is defined as:

This is a convenience method around table linear which maps min to 0, and max to 255, with linear interpolation in between. Values below min and above max are clamped to 0 and 255 respectively.

This method returns a list of 256 values, the result of running the values 0 to 255 through a thresholding (or binarization) function, with parameter threshold. This function is defined as:

This method returns a list of 256 values, the result of running the values 0 to 255 through a thresholding (or binarization) function, with parameter threshold. This function is defined as:

This method returns a list of 256 values, the result of running the values 0 to 255 through a thresholding (or binarization) function, with parameters min and max. This function is defined as:

This method returns a list of 256 values, the result of running the values 0 to 255 through a thresholding (or binarization) function, with parameters min and max. This function is defined as: