hist hacking

libvips/histograms_lut/im_histeq.c

@@ -1,14 +1,4 @@
-/* @(#) Takes as input a histogram and creates a lut which when applied
+/* histogram normalisation and cumulativisation
- * @(#) on the original image, histogram equilises it.
- * @(#) 
- * @(#) Histogram equalisation is carried out for each band of hist 
- * @(#) individually.
- * @(#) 
- * @(#) int im_histeq( IMAGE *hist, IMAGE *lut )
- * @(#)
- * @(#) Returns 0 on sucess and -1 on error
- *
- * Copyright: 1991, N. Dessipris
  *
  * Author: N. Dessipris
  * Written on: 02/08/1990
@@ -27,6 +17,9 @@
  * 	- eek, off by 1 for more than 1 band hists
  * 12/5/08
  * 	- histcum works for signed hists now as well
+ * 24/3/10
+ * 	- gtkdoc
+ * 	- small cleanups
  */
 
 /*
@@ -82,7 +75,16 @@
 	} \
 }
 
-/* Form cumulative histogram.
+/**
+ * im_histcum:
+ * @in: input image
+ * @out: output image
+ *
+ * Form cumulative histogram. 
+ *
+ * See also: im_histnorm().
+ *
+ * Returns: 0 on success, -1 on error
  */
 int 
 im_histcum( IMAGE *in, IMAGE *out )
@@ -145,8 +147,18 @@ im_histcum( IMAGE *in, IMAGE *out )
 	return( 0 );
 }
 
-/* Normalise histogram ... normalise range to make it square (ie. max ==
+
+/**
+ * im_histnorm:
+ * @in: input image
+ * @out: output image
+ *
+ * Normalise histogram ... normalise range to make it square (ie. max ==
  * number of elements). Normalise each band separately.
+ *
+ * See also: im_histcum().
+ *
+ * Returns: 0 on success, -1 on error
  */
 int 
 im_histnorm( IMAGE *in, IMAGE *out )
@@ -193,7 +205,16 @@ im_histnorm( IMAGE *in, IMAGE *out )
 	return( 0 );
 }
 
-/* Histogram equalisation. 
+/**
+ * im_histeq:
+ * @in: input image
+ * @out: output image
+ *
+ * Histogram equalisation: normalised cumulative histogram. 
+ *
+ * See also: im_heq().
+ *
+ * Returns: 0 on success, -1 on error
  */
 int 
 im_histeq( IMAGE *in, IMAGE *out )
@@ -202,7 +223,9 @@ im_histeq( IMAGE *in, IMAGE *out )
 
 	/* Normalised cumulative.
 	 */
-	if( !t1 || im_histcum( in, t1 ) || im_histnorm( t1, out ) )
+	if( !(t1 = im_open_local( out, "im_histeq:1", "p" )) ||
+		im_histcum( in, t1 ) || 
+		im_histnorm( t1, out ) )
 		return( -1 );
 
 	return( 0 );

libvips/histograms_lut/im_histgr.c

@@ -1,16 +1,4 @@
-/* @(#) im_histgr: make a histogram of an image and saves it into hist.
+/* find histograms
- * @(#) If input is uchar, output is 256 by 1 image of uint. If input is
- * @(#) ushort, output is max(image) + 1 by 1 image of uint. If bandno is
- * @(#) zero, then output is has same number of bands as input, with each
- * @(#) band being a separate histogram. Otherwise, bandno selects a band
- * @(#) to find the histogram of.
- * @(#) 
- * @(#) Usage:
- * @(#) int im_histgr(image, hist, bandno)
- * @(#) IMAGE *image, *hist;
- * @(#) int bandno;
- * @(#)
- * @(#)  Returns 0 on success and -1 on error
  *
  * Copyright: 1990, 1991, N. Dessipris.
  *
@@ -29,6 +17,9 @@
  *	- tiny speed ups
  * 21/1/07
  * 	- number bands from zero
+ * 24/3/10
+ * 	- gtkdoc
+ * 	- small celanups
  */
 
 /*
@@ -292,6 +283,22 @@ find_ushort_hist_extract( REGION *reg, void *seq, void *a, void *b )
 	return( 0 );
 }
 
+/**
+ * im_histgr:
+ * @in: input image
+ * @out: output image
+ * @bandno: band to equalise
+ *
+ * Find the histogram of @in. Find the histogram for band @bandno (producing a
+ * one-band histogram), or for all bands (producing an n-band histogram) if 
+ * @bandno is -1. 
+ *
+ * @in must be u8 or u16. @out is always u32.
+ *
+ * See also: im_histgr(), im_histeq().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int 
 im_histgr( IMAGE *in, IMAGE *out, int bandno )
 {
@@ -304,30 +311,19 @@ im_histgr( IMAGE *in, IMAGE *out, int bandno )
 
 	/* Check images. PIO from in, WIO to out.
 	 */
-	if( im_pincheck( in ) || im_outcheck( out ) )
+	if( im_check_uncoded( "im_histgr", in ) || 
+		im_check_u8or16( "im_histgr", in ) ||
+		im_check_bandno( "im_histgr", in, bandno ) ||
+		im_pincheck( in ) || 
+		im_outcheck( out ) )
 		return( -1 );
-	if( in->Coding != IM_CODING_NONE ) {
-		im_error( "im_histgr", "%s", _( "uncoded images only" ) );
-		return( -1 );
-	}
 
 	/* Find the range of pixel values we must handle.
 	 */
-	if( in->BandFmt == IM_BANDFMT_UCHAR ) 
+	size = in->BandFmt == IM_BANDFMT_UCHAR ? 256 : 65536;
-		size = 256;
-	else if( in->BandFmt == IM_BANDFMT_USHORT )
-		size = 65536;
-	else {
-		im_error( "im_histgr", "%s", _( "input not uchar or ushort" ) );
-		return( -1 );
-	}
 
 	/* How many output bands?
 	 */
-	if( bandno > in->Bands || bandno < -1 ) {
-		im_error( "im_histgr", "%s", _( "bad band parameter" ) );
-		return( -1 );
-	}
 	if( bandno == -1 ) 
 		bands = in->Bands;
 	else 

libvips/include/vips/check.h

@@ -54,6 +54,7 @@ int im_check_bands_1or3( const char *domain, IMAGE *in );
 int im_check_bands( const char *domain, IMAGE *im, int bands );
 int im_check_bands_1orn( const char *domain, IMAGE *im1, IMAGE *im2 );
 int im_check_bands_same( const char *domain, IMAGE *im1, IMAGE *im2 );
+int im_check_bandno( const char *domain, IMAGE *im, int bandno );
 int im_check_int( const char *domain, IMAGE *im );
 int im_check_uint( const char *domain, IMAGE *im );
 int im_check_noncomplex( const char *domain, IMAGE *im );

libvips/iofuncs/check.c

@@ -971,6 +971,34 @@ im_check_bands_same( const char *domain, IMAGE *im1, IMAGE *im2 )
 	return( 0 );
 }
 
+/**
+ * im_check_bandno:
+ * @domain: the originating domain for the error message
+ * @im: image to check
+ * @bandno: band number
+ *
+ * @bandno should be a valid band number (ie. 0 to im->Bands - 1), or can be
+ * -1, meaning all bands. 
+ * If not, set an error message
+ * and return non-zero.
+ *
+ * See also: im_error().
+ *
+ * Returns: 0 if OK, -1 otherwise.
+ */
+int
+im_check_bandno( const char *domain, IMAGE *im, int bandno )
+{
+	if( bandno < -1 ||
+		bandno > im->Bands - 1 ) {
+		im_error( domain, "bandno must be -1, or less than %d",
+			im->Bands );
+		return( -1 );
+	}
+
+	return( 0 );
+}
+
 /**
  * im_check_format_same:
  * @domain: the originating domain for the error message