From dfc7f859cd7b1fef23f6969b1365b4c8f963360f Mon Sep 17 00:00:00 2001
From: John Cupitt <jcupitt@gmail.com>
Date: Thu, 18 Nov 2010 14:09:56 +0000
Subject: [PATCH] docs

---
 TODO                                |  4 ----
 libvips/mask/rw_mask.c              |  3 ++-
 libvips/morphology/morph_dispatch.c | 36 ++++++++++++++++++++++++++++-
 3 files changed, 37 insertions(+), 6 deletions(-)

diff --git a/TODO b/TODO
index 57cfd8db..60614b97 100644
--- a/TODO
+++ b/TODO
@@ -1,7 +1,3 @@
-- check that the section intros for the new docs include all the material from
-  the old reference guide
-
-
 
 
 - nip2-7.22.3 on Windows is not adding the path you load from to the set of
diff --git a/libvips/mask/rw_mask.c b/libvips/mask/rw_mask.c
index 9d65a75a..49a1167e 100644
--- a/libvips/mask/rw_mask.c
+++ b/libvips/mask/rw_mask.c
@@ -102,7 +102,8 @@
  *
  * These operations load, save and process mask objects. Masks are used as
  * paramaters to convolution and morphology operators, and to represent
- * matrices. 
+ * matrices. There are two types of matrix: integer #INTMASK and double 
+ * precision floating point #DOUBLEMASK.
  *
  * This API is horrible and clunky. Surely it will be replaced soon.
  */
diff --git a/libvips/morphology/morph_dispatch.c b/libvips/morphology/morph_dispatch.c
index 23d33ffc..dc010e0d 100644
--- a/libvips/morphology/morph_dispatch.c
+++ b/libvips/morphology/morph_dispatch.c
@@ -50,7 +50,41 @@
  * @stability: Stable
  * @include: vips/vips.h
  *
- * Erode, dilate, rank, count lines, number regions, etc.
+ * The morphological functions search images
+ * for particular patterns of pixels, specified with the mask argument,
+ * either adding or removing pixels when they find a match. They are useful
+ * for cleaning up images --- for example, you might threshold an image, and
+ * then use one of the morphological functions to remove all single isolated
+ * pixels from the result.
+ *
+ * If you combine the morphological operators with the mask rotators
+ * im_rotate_imask45(), for example) and apply them repeatedly, you
+ * can achieve very complicated effects: you can thin, prune, fill, open edges,
+ * close gaps, and many others. For example, see `Fundamentals  of  Digital
+ * Image Processing' by A.  Jain, pp 384-388, Prentice-Hall, 1989 for more 
+ * ideas.
+ *
+ * Beware that VIPS reverses the usual image processing convention, by 
+ * assuming white objects (non-zero pixels) on a black background (zero
+ * pixels).
+ *
+ * The mask you give to the morphological functions should contain only the
+ * values 0 (for background), 128 (for don't care) and 255 (for object). The
+ * mask must have odd length sides --- the origin of the mask is taken to be
+ * the centre value. For example, the mask:
+ *
+ *   3 3 
+ *   128 255 128
+ *   255 0   255
+ *   128 255 128
+ *
+ * applied to an image with im_erode(), will find all black pixels
+ * 4-way connected with white pixels. Essentially, im_dilate()
+ * sets pixels in the output if any part of the mask matches, whereas
+ * im_erode() sets pixels only if all of the mask matches.
+ *
+ * See im_andimage(), im_orimage() and im_eorimage()
+ * for analogues of the usual set difference and set union operations.
  */
 
 /* Args to im_profile.