crimp_devguide(n) 1 doc "C Raster Image Manipulation Package"

Architecture & Concepts

Most of the overall architecture and concepts like images (image values), image-types, and the general design, are all introduced in the user documentation, namely

1. CRIMP - Introduction to CRIMP, and

2. CRIMP - Foundation

Here we concentrate on some details of the internals. First, the main data structures and their relationships:

Yellow structures are allocated on the heap, whereas blue structures are statically allocated as (static, i.e. non-public) global variables.

The named image_types declare the structure of image pixels, i.e. how many channels they have, their names, and the number of bytes per channel. This can be queried at Tcl level. The relevant declarations and definitions are in the files "c/image_type.h" and "c/image_type.c".

Regarding the images themselves, each is represented by a single heap-allocated structure with references to the type, i.e. pixel structure, and user-specified meta data (held by a standard Tcl_Obj of type dictionary), dimensions, and the pixel data itself. The latter is part of the structure, and not allocated separately. The relevant declarations and definitions are in the files "c/image.h" and "c/image.c".

From the Tcl level, i.e. string representation, things looks a bit differently

Each of the elements of an image are elements in a Tcl list, with the type string a pointer into the database of pixel structures and the pixel data represented by a bytearray.

Directory structure

Helpers

"tools/"

This directory contains helper scripts.

"tools/makedoc.sh"

"tools/makefigures.sh"

"tools/makedocfigures.sh"

These helper scripts, when run, (re)generate the embedded documentation from the documentation sources, or the figures, or both. This requires the applications mimetex, convert (ImageMagick), dtplite, and dia. The latter is, for example, installed by ActiveTcl.

"tools/validatedoc.sh"

This helper script validates that the documentation markup conforms to the syntax of doctools. Nothing is generated.

Documentation

"doc/"

This directory contains the documentation sources. The texts are written in doctools format, whereas the figures are a mixture of TeX (math formulas), and tklib's dia(gram) package and application.

"embedded/"

This directory contains the documentation converted to regular manpages (nroff) and HTML. It is called embedded because these files, while derived, are part of the fossil repository, i.e. embedded into it. This enables fossil to access and display these files when serving the repositories' web interface. The "Command Reference" link at http://chiselapp.com/user/andreas_kupries/repository/crimp/home is, for example, accessing the generated HTML.

"specs/"

This directory contains specifications of the image file formats for which CRIMP provides readers and/or writers. Currently this is only PGM and PPM, i.e "Portable Grey Map" and "Portable Pix Map" respectively, and Windows's BMP format.

Demonstration Application and Framework

"demos.tcl"

This is the demo application & framework.

"demos/"

This directory is searched by "demos.tcl" for the demonstrations to make available to its user. See Writing a new demo for information on the structure of a demonstration.

"images/"

This directory is searched by "demos.tcl" for the images to make available to its user and the demos. See Adding a new demo image for more information.

Package Code, General structure

"crimp*.tcl"

These are the master files of the packages. Based on critcl (v3) they contain all the necessary declarations to build their package.

Each file reads the primitives to implement from the files in the sub-directories "core/" (crimp_core), "operator/" (crimp), and "format/" (crimp_*, except for core).

"support.tcl"

This is a shared helper file used by the package master files. It contains the general code to load and convert ".crimp" files.

"policy*.tcl"

These are the companions to the "crimp*.tcl" files which implement the higher-level interfaces on top of the C-based primitive operations, and determine policies.

The documentation (see "doc/") mainly describes this higher-level API, plus the few primitives which are passed through unchanged, i.e. without getting wrapped into Tcl procedures.

"plot.tcl"

This is a companion Tcl file to "crimp_tk.tcl" and "policy_tk.tcl" which implements a simple plot widget. It essentially wraps Tklib's Plotchart package into a simpler interface.

The main user of this functionality is currently the demonstration framework, "demos.tcl".

"operator/"

This directory contain the sources of the C-level primitives implemented by CRIMP.

The master file "crimp.tcl" reads all the ".crimp" files found in this directory, converting them into proper critcl::cprocs.

"core/"

This directory contain the sources of the core C-level primitives implemented by CRIMP.

The master file "crimp_core.tcl" reads all the ".crimp" files found in this directory, converting them into proper critcl::cprocs.

"format/"

This directory contain the sources of the C-level primitives for file and other I/O implemented by the various I/O packages.

The master files "crimp_*.tcl" read all the associated ".crimp" files found in this directory, converting them into proper critcl::cprocs. I.e.

"crimp_bmp.tcl"

"format/*bmp*.crimp"

"crimp_pcx.tcl"

"format/*pcx*.crimp"

"crimp_pfm.tcl"

"format/*pfm*.crimp"

"crimp_pgm.tcl"

"format/*pgm*.crimp"

"crimp_ppm.tcl"

"format/*ppm*.crimp"

"crimp_sgi.tcl"

"format/*sgi*.crimp"

"crimp_sun.tcl"

"format/*sun*.crimp"

"crimp_tk.tcl"

"format/*tk*.crimp"

"cop/"

(speak: C op ;) For a few of the primitives in operator/ (see above) the implementations were very similar. This directory contains "templates" for these implementations, with the actual primitives #include'ing them. The templates are configured through a number a C #define's for the parts where the primitives differ.

The files all belong to package crimp.

This is a first attempt at templating some of the C code. It works, but isn't really very nicely done.

While I (AK) have the general ida of using Tcl and Tcl-based macro-processors (like "expand", see Wiki) bouncing around in my head for a better templating and C code generation mechanism there is nothing concrete yet.

"c/"

This directory contain the C sources for common/shared functionality, mainly the Tcl_ObjType's for "image type"-values and "image"-values, and complex functions I really did not wish to duplicate in the C primitives (AHE support, Rank-Order Filter support, geometry functions, FFT).

As such some of it belongs to package crimp::core, with the large remainder belonging to package crimp.

"reader/"

This directories contains the read procedures for image formats done in pure Tcl, and outside of the main I/O packages.

Currently this is Richard Suchenwirth's strimj'es.

The files in these directories are declared as Tcl companion files of "crimp.tcl", causing them to be sourced automatically by the critcl framework when CRIMP is loaded.

Package Code, Per Package

crimp::core

"crimp_core.tcl"

"policy_core.tcl"

"core/*.crimp"

"c/coreInt.h"

"c/image.[ch]"

"c/volume.[ch]"

"c/image_type.[ch]"

"c/buffer.[ch]"

crimp

"crimp.tcl"

"policy.tcl"

"operator/*.crimp"

"reader/*"

"cop/*"

"c/*"

Regarding "c/*" only those not claimed by crimp::core, see above.

crimp::bmp

"crimp_bmp.tcl"

"policy_bmp.tcl"

"format/*bmp*.crimp"

"format/bmp.[ch]"

crimp::pcx

"crimp_pcx.tcl"

"policy_pcx.tcl"

"format/*pcx*.crimp"

crimp::pfm

"crimp_pfm.tcl"

"policy_pfm.tcl"

"format/*pfm*.crimp"

crimp::pgm

"crimp_pgm.tcl"

"policy_pgm.tcl"

"format/*pgm*.crimp"

crimp::ppm

"crimp_ppm.tcl"

"policy_ppm.tcl"

"format/*ppm*.crimp"

crimp::sgi

"crimp_sgi.tcl"

"policy_sgi.tcl"

"format/*sgi*.crimp"

crimp::sun

"crimp_sun.tcl"

"policy_sun.tcl"

"format/*sun*.crimp"

crimp::tk

"crimp_tk.tcl"

"policy_tk.tcl"

"plot.tcl"

"format/*tk*.crimp"

Writing a new primitive

The individual primitive C level operations of CRIMP are found in the sub-directories "core/", "operator/", and "format/". See the Directory structure.

Each primitive is handled by a single file with the extension ".crimp".

Note that all files found in these directories and which do not have the extension ".crimp" are by default ignored when "crimp.tcl" loads and processes the primitives. The exception is if a package policy file declares them to be a part of the package in question.

To write a new primitive simply add a new file with the extension ".crimp" to the directory and fill it with content according to the rules below, which specify the format of ".crimp" files.

1. A ".crimp" file is a plain text file.

2. The first line in the file contains the name of the primitive it implements.

3. All following lines, until the first empty line, describe the arguments of the primitive, i.e. their types and names. Note that a line containing only whitespace (space and tab characters) is not empty.

4. Each line in the argument block describes a single argument.

5. All lines after the empty line terminating the argument block, to the end of the file, contain the C code implementing the primitive.

As an example, here are the contents of the ".crimp" file for one of the primitives with one of the smallest implementations:

[1]     width
[2]     Tcl_Obj* imageObj
[3]
[4]     crimp_image* image;
[5]
[6]     crimp_input_any (imageObj, image);
[7]
[8]     Tcl_SetObjResult (interp, Tcl_NewIntObj (crimp_w (image)));
[9]     return TCL_OK;

Line 1 contains the name of the primitive, "width". Line 2 is the first line of the argument block. Line 3 terminates this argument block. Lines 4 to 9 are the implementation.

This specific primitive extracts the width from the image it was given as argument and returns it as its result.

Writing a new high-level command

The high-level commands wrapping around most of the C level primitives reside in the files matching the pattern "policy*.tcl".

They usually have one of the following purposes:

1. Aggregating a group of related primitives into a single command which chooses the primitive to use automatically, based on the type(s) of its image argument(s). The command ::crimp max is an example of this, choosing and dispatching to the group of max_*_* primitives.

2. A nicer (more tcl-ish) interface to a (group of) primitive(s). The command ::crimp meta is an example of that, implementing a dict-like API on top of the raw meta_set and meta_get primitives.

3. Convenience methods which aggregate other commands, not necessarily primitives, into a larger functionality. The group of ::crimper filter sobel methods is an example of this, wrapping around ::crimp filter convolve (itself an example of (1)) and the commands for creating convolution kernels, implementing a specific well-known filter with a fixed kernel.

4. Implementing functionality fully in Tcl, where primitives are not needed, or mostly not. The ::crimp transform and ::crimp table commands are examples of this, computing projective transformations and pixel mapping tables, respectively. A better example might be the "::crimp pyramid" methods which encapsulate the higher-order structure of image pyramid processing, leaving the details callback commands.

Their implementation has to obey the following rules:

1. The CRIMP package has the namespace "::crimp" reserved for its use. All new procedures have to be defined in this namespace, or sub-ordinate namespaces.

2. New procedures extending an existing ensemble have to be defined in the namespace of that ensemble. (Rule (1) above could have been subsumed into this, because the main command, "::crimp", is an ensemble).

3. Any new command defined directly in the "::crimp" namespace, i.e. at the top-level of the hierarchy, has to be listed in the namespace export clauses at the bottom of file "policy.tcl".

4. Public procedures have to have a name starting with a lowercase character.

5. Internal procedures have to have a name starting with an uppercase character.

Writing a new demo

The individual demos used by "demos.tcl" reside in the sub-directory "demos/" of the sources.

Each demo is handled by a single file with the extension ".tcl".

Note that all files found in the directory and which do not have the extension ".tcl" are ignored when "demos.tcl" looks for demos it can use.

To write a new demo simply add a new file with the extension ".tcl" to the directory and fill it with content according to the rules below, which specify the format of the demo files.

1. A demo file is a Tcl script. As such it is a plain text file.

2. A demo file contains a single command "def", taking two arguments, the name of the demo, and a Tcl dictionary describing it.

3. The dictionary describing the demo may contain the keys and values listed below. Some of the keys must exist, others are optional. Both will be noted in the desciptions of the keys, below.

   label

   Must exist. Its value is the name of the demo, as shown to and seen by the user of "demos.tcl".

   active

   Optional. Its value is a script which will be executed by demos.tcl whenever it has to decide which demos to show in the list, based on the selection of images. The result has to be a boolean value, with True signaling that the demo is suitable for the selection, and False that it should not be shown.

   setup

   Optional. Its value is a script which is run whenever this demo has been chosen by the user. It is expected to create any commands and state it may need during the processing of an image.

   shutdown

   Optional. Its value is a script which is run whenever this demo has been de-selected by the user (and possibly some other demo chosen). It is expected to clean up any dynamic resources the demo may have aquired (like timers, open files, etc.). The script does not have to care about procedures and state in the ::DEMO namespace. These are automatically destroyed by the framework.

   setup_image

   Optional, technically. Its value is a script which is run whenever the image for the demo has changed. Its responsibility is to apply the demo to the image and show any results. As such leaving this key out of the description makes pretty much no sense at all.

4. All scripts (see demo description, above) are executed within the ::DEMO namespace and have access to its variables and commands

5. The demo framework exports a number of supporting commands for use by the scripts in the individual demos. These are:

   crimp

   Of course, as demos have to have access to CRIMP's functionality. All known crimp packages are loaded, i.e.

   1. crimp

   2. crimp::bmp

   3. crimp::pcx

   4. crimp::pfm

   5. crimp::pgm

   6. crimp::ppm

   7. crimp::sgi

   8. crimp::sun

   9. crimp::tk

   appdir

   Returns the path of the directory the demo application is contained in.

   base ?N?

   Returns the N'th image selected by the user. Counted from 0. If not specified 'N' defaults 0.

   bases

   Returns the number of selected images. Most useful to the 'active' script.

   demodir

   Returns the path of the directory the demo's sources are contained in.

   thebases

   Returns a list containing all selected images.

   show_image I

   Takes an image I and displays it in the demo result area for the user to see.

   show_slides LI

   Takes a list of images and displays them in the demo result area for the user to see, as a slideshow which cycles through the images. The user gets a bevy of buttons to start/stop the cycling, change cycle interval, and direction.

   log T

   Writes the text T to the demo log window, followed by a newline

   log* T

   Writes the text T to the demo log window. No newline is added after the text.

6. The demo framework has a number of hook points in the GUI for use by demos. These are:

   • .left

   • .right

   • .top

   • .bottom

   These widgets are ttk::frames placed to the left, right, top and bottom of the demo result area and usually empty. The demo can put its own interface elements there, buttons, sliders, plots, etc. pp. When not empty the layout roughly looks like:

   

   The demo's UI elements underneath these hooks are automatically destroyed when the demo is shut down, before its 'shutdown' script is run.

Adding a new demo image

The individual demonstration images used by "demos.tcl" reside in the sub-directory "image/" of the sources.

Each image is handled by a single file with the extension ".png", whose contents have to be in the PNG image file format.

Note that all files found in the directory, and which do not have the extension ".png", are ignored when "demos.tcl" looks for images it can use.

To add a new image simply copy the image file into the directory, assuming that it has the correct extension and file format. Otherwise convert the image to PNG and change the extension to suit.