hist hacking

ChangeLog

@@ -2,6 +2,7 @@
 - added progress feedback to threadpool
 - --vips-wbuffer2 switch does all wbuffer use now
 - im_wbuffer2() renamed as vips_discsink(), some cleanups
+- im_gammacorrect() can do 16-bit iamges too
 
 16/1/10 started 7.21.2
 - "invalidate" is careful to keep images alive, so invalidate callbacks can do

TODO

@@ -1,4 +1,7 @@
 
+- im_render() should be renamed as vips_sink_screen()? also vips_sink_disc()
+  instead of vips_discsink()?
+
 - nip2 image display does not work with threading disabled
 
 - docs: histogram_lut next

libvips/histograms_lut/hist_dispatch.c

@@ -49,6 +49,17 @@
  * @see_also: <link linkend="libvips-image">image</link>
  * @include: vips/vips.h
  *
+ * Histograms and look-up tables are 1xn or nx1 images, where n is less than
+ * 256 or less than 65536, corresponding to 8- and 16-bit images. They are
+ * tagged with a #VipsType of IM_TYPE_HISTOGRAM and usually displayed by
+ * user-interfaces such as nip2 as plots rather than images.
+ *
+ * You can make a LUT by scanning an image (see im_histgr()), from a
+ * matrix (see im_buildlut()), or using arithmetic operators on an identity
+ * LUT (see im_identity()).
+ *
+ * Once you have a LUT you can manipulate it in various ways (see im_historm()
+ * and friends) and use it to transform other images (see im_maplut()).
  */
 
 /* One image in, one out.

libvips/histograms_lut/im_buildlut.c

@@ -1,22 +1,4 @@
-/* @(#) Build a LUT from a set of x/y points. Eg. if input is
+/* Build a LUT from a set of x/y points. 
- * @(#) 
- * @(#)   0   0
- * @(#)   255 100
- * @(#) 
- * @(#) we generate
- * @(#) 
- * @(#)   index  value
- * @(#)   0      0
- * @(#)   1      0.4
- * @(#)   .. etc. linear interpolation
- * @(#)   255    100
- * @(#)
- * @(#) (we don't generate the index column, that's just there to show the
- * @(#) position in the table)
- * @(#)
- * @(#) The x/y points don't need to be sorted: we do that. You can have 
- * @(#) several Ys: each becomes a band in the output LUT. You don't need to
- * @(#) start at zero: any integer will do, including negatives.
  *
  * Written on: 26/9/06
  * 	- from im_invertlut()
@@ -28,6 +10,8 @@
  * 	- argh, fixed again
  * 22/6/09
  *	- more fixes for tables that don't start at zero (thanks Jack)
+ * 23/3/10
+ * 	- gtkdoc
  */
 
 /*
@@ -226,6 +210,69 @@ buildlut( State *state )
 	return( 0 );
 }
 
+/**
+ * im_buildlut:
+ * @input: input mask
+ * @output: output image
+ *
+ * This operation builds a lookup table from a set of points. Intermediate
+ * values are generated by piecewise linear interpolation. 
+ *
+ * For example, consider this 2 x 2 matrix of (x, y) coordinates:
+ *
+ *   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ *     <tbody>
+ *       <row>
+ *         <entry>0</entry>
+ *         <entry>0</entry>
+ *       </row>
+ *       <row>
+ *         <entry>255</entry>
+ *         <entry>100</entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ * 
+ * We then generate:
+ *
+ *   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+ *     <thead>
+ *       <row>
+ *         <entry>Index</entry>
+ *         <entry>Value</entry>
+ *       </row>
+ *     </thead>
+ *     <tbody>
+ *       <row>
+ *         <entry>0</entry>
+ *         <entry>0</entry>
+ *       </row>
+ *       <row>
+ *         <entry>1</entry>
+ *         <entry>0.4</entry>
+ *       </row>
+ *       <row>
+ *         <entry>...</entry>
+ *         <entry>etc. by linear interpolation</entry>
+ *       </row>
+ *       <row>
+ *         <entry>255</entry>
+ *         <entry>100</entry>
+ *       </row>
+ *     </tbody>
+ *   </tgroup>
+ *
+ * This is then written as the output image, with the left column giving the
+ * index in the image to place the value.
+ * 
+ * The (x, y) points don't need to be sorted: we do that. You can have 
+ * several Ys, each becomes a band in the output LUT. You don't need to
+ * start at zero, any integer will do, including negatives.
+ *
+ * See also: im_identity(), im_invertlut().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int
 im_buildlut( DOUBLEMASK *input, IMAGE *output )
 {

libvips/histograms_lut/im_gammacorrect.c

@@ -1,12 +1,4 @@
-/* @(#) Gamma-correct uchar image with factor gammafactor.
+/* Gamma-correct image with factor gammafactor.
- * @(#)
- * @(#)  int im_gammacorrect(in, out, exponent)
- * @(#)  IMAGE *in, *out;
- * @(#)  double exponent;
- * @(#)
- * @(#)  Returns 0 on sucess and -1 on error
- * @(#)
- *
  *
  * Copyright: 1990, N. Dessipris.
  * 
@@ -14,6 +6,9 @@
  * Modified on:
  * 19/6/95 JC
  *	- redone as library function
+ * 23/3/10
+ * 	- gtkdoc
+ * 	- 16 bit as well
  */
 
 /*
@@ -55,27 +50,37 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * im_gammacorrect:
+ * @in: input image
+ * @out: output image
+ * @exponent: gamma factor
+ *
+ * Gamma-correct an 8- or 16-bit unsigned image with a lookup table. The
+ * output format is the same as the input format.
+ *
+ * See also: im_identity(), im_powtra(), im_maplut()
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int 
 im_gammacorrect( IMAGE *in, IMAGE *out, double exponent )
 {
-	IMAGE *t1 = im_open_local( out, "im_gammacorrect:#1", "p" );
+	IMAGE *t[4];
-	IMAGE *t2 = im_open_local( out, "im_gammacorrect:#2", "p" );
+	double mx1, mx2;
-	IMAGE *t3 = im_open_local( out, "im_gammacorrect:#2", "p" );
 
-	if( !t1 || !t2 || !t3 )
+	if( im_open_local_array( out, t, 4, "im_gammacorrect", "p" ) ||
-		return( -1 );
+		im_check_u8or16( "im_gammacorrect", in ) ||
-
+		im_piocheck( in, out ) ||
-        if( im_piocheck( in, out ) )
+		(in->BandFmt == IM_BANDFMT_UCHAR ?
-                return( -1 );
+			im_identity( t[0], 1 ) :
-	if( in->BandFmt != IM_BANDFMT_UCHAR ) {
+			im_identity_ushort( t[0], 1, 65536 )) ||
-		im_error( "im_gammacorrect", "%s", _( "uchar images only" ) );
+		im_powtra( t[0], t[1], exponent ) ||
-		return( -1 );
+		im_max( t[0], &mx1 ) ||
-	}
+		im_max( t[1], &mx2 ) ||
-
+		im_lintra( mx1 / mx2, t[1], 0, t[2] ) ||
-	if( im_identity( t1, 1 ) ||
+		im_clip2fmt( t[2], t[3], in->BandFmt ) ||
-		im_powtra( t1, t2, exponent ) ||
+		im_maplut( in, out, t[3] ) )
-		im_scale( t2, t3 ) ||
-		im_maplut( in, out, t3 ) )
 		return( -1 );
 
 	return( 0 );

libvips/histograms_lut/im_heq.c

@@ -1,15 +1,4 @@
-/* @(#)  Histogram equalises the input uchar image; result in uchar
+/* Histogram-equalise an image.
- * @(#) If bandno=0 all bands are equilised independantly
- * @(#) else input image is equilised using the histogram of bandno only.
- * @(#)  Image descriptors should have been set properly by the calling program
- * @(#)
- * @(#)  Usage: heq imagein imageout bandno
- * @(#)  int im_heq(in, out, bandno)
- * @(#)  IMAGE *in, *out;
- * @(#)  int bandno;
- * @(#)
- * @(#)  Returns 0 on sucess and -1 on error
- * @(#)
  *
  * Copyright: 1991, N. Dessipris.
  *
@@ -22,6 +11,8 @@
  *	- ANSIfied and tidied up
  * 3/3/01 JC
  *	- more cleanup
+ * 23/3/10
+ * 	- gtkdoc
  */
 
 /*
@@ -63,16 +54,28 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * im_heq:
+ * @in: input image
+ * @out: output image
+ * @bandno: band to equalise
+ *
+ * Histogram-equalise @in. Equalise using band @bandno, or if @bandno is -1,
+ * equalise all bands.
+ *
+ * See also: im_histgr(), im_histeq().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int 
 im_heq( IMAGE *in, IMAGE *out, int bandno )
 {
-	IMAGE *t1 = im_open_local( out, "im_heq:1", "p" );
+	IMAGE *t[2];
-	IMAGE *t2 = im_open_local( out, "im_heq:2", "p" );
 
-	if( !t1 || !t2 ||
+	if( im_open_local_array( out, t, 2, "im_heq", "p" ) ||
-		im_histgr( in, t1, bandno ) ||
+		im_histgr( in, t[0], bandno ) ||
-		im_histeq( t1, t2 ) ||
+		im_histeq( t[0], t[1] ) ||
-		im_maplut( in, out, t2 ) )
+		im_maplut( in, out, t[1] ) )
 		return( -1 );
 
 	return( 0 );

libvips/histograms_lut/im_hist.c

@@ -1,14 +1,4 @@
-/* @(#) Creates a displayable historam of in result in hist
+/* Plot the histogram of an image.
- * @(#) If bandno=0 histogram of all bands is created
- * @(#) else the histogram of bandno only is created.
- * @(#)
- * @(#)  Usage:
- * @(#)  int im_hist(in, out, bandno)
- * @(#)  IMAGE *in, *out;
- * @(#)  int bandno;
- * @(#)
- * @(#)  Returns 0 on sucess and -1 on error
- * @(#)
  *
  * Copyright: 1991, N. Dessipris.
  *
@@ -60,13 +50,25 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * im_hist:
+ * @in: input image
+ * @out: output image
+ * @bandno: band to equalise
+ *
+ * Find and plot the histogram of @in. If @bandno is -1, plot all bands. 
+ * Otherwise plot the specified band.
+ *
+ * See also: im_histgr(), im_histplot().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int 
 im_hist( IMAGE *in, IMAGE *out, int bandno )
 {
-	IMAGE *hist = im_open_local( out, "im_hist:#1", "p" );
+	IMAGE *hist;
 
-	if( !hist || 
+	if( !(hist = im_open_local( out, "im_hist", "p" )) ||
-		im_iocheck( in, out ) ||
 		im_histgr( in, hist, bandno ) ||
 		im_histplot( hist, out ) )
 		return( -1 );