more relational stuff

ChangeLog

@@ -43,6 +43,8 @@
 - added im_shift*_vec()
 - renamed im_eor_vec() as im_eorimage_vec() for consistency, also and, or
 - renamed im_eorconst() as im_eorimage_const() for consistency, also and, or
+- relational revised: smaller, more general, faster
+- im_blend() allows many-band conditional, 1-band then/else
 
 25/3/09 started 7.18.0
 - revised version numbers

TODO

@@ -1,4 +1,16 @@
-- relational next
+- test im_blend, including new n-band cond + n-band a/b mode
+
+- do the same to im_ifthenelse
+
+- should we bandup then/else too? could have
+
+	4 band cond
+	1 band then
+	4 band else
+
+  I guess
+
+
 
 - we have tools/ and contrib/ argh
 

doc/reference/libvips-docs.sgml.in

@@ -17,30 +17,37 @@
 
   <chapter>
     <title>API by section</title>
+    <xi:include href="xml/image.xml"/>
+    <xi:include href="xml/arithmetic.xml"/>
+    <xi:include href="xml/boolean.xml"/>
+    <xi:include href="xml/relational.xml"/>
+    <xi:include href="xml/buf.xml"/>
+  </chapter>
+
+  <chapter>
+    <title>API by section (no gtkdoc comments yet)</title>
     <xi:include href="xml/format.xml"/>
     <xi:include href="xml/interpolate.xml"/>
     <xi:include href="xml/object.xml"/>
     <xi:include href="xml/proto.xml"/>
     <xi:include href="xml/colour.xml"/>
     <xi:include href="xml/region.xml"/>
-    <xi:include href="xml/arithmetic.xml"/>
     <xi:include href="xml/meta.xml"/>
-    <xi:include href="xml/image.xml"/>
     <xi:include href="xml/transform.xml"/>
     <xi:include href="xml/util.xml"/>
     <xi:include href="xml/threadgroup.xml"/>
     <xi:include href="xml/version.xml"/>
     <xi:include href="xml/type.xml"/>
     <xi:include href="xml/rect.xml"/>
-    <xi:include href="xml/buf.xml"/>
     <xi:include href="xml/semaphore.xml"/>
     <xi:include href="xml/dispatch.xml"/>
-
   </chapter>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
   </chapter>
+
   <index id="api-index-full">
     <title>API Index</title>
     <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>

libvips/boolean/boolean.c

@@ -303,13 +303,12 @@ CONSTN_BUFFER( AND, & )
 
 /**
  * im_andimage_vec:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @n: array length
  * @c: array of constants
  *
- * This operation calculates @in1 & @c (bitwise and of image pixels with array
+ * This operation calculates @in & @c (bitwise and of image pixels with array
  * @c) and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimage_vec().
@@ -328,12 +327,11 @@ im_andimage_vec( IMAGE *in, IMAGE *out, int n, double *c )
 
 /**
  * im_andimageconst:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @c: constant
  *
- * This operation calculates @in1 & @c (bitwise and of image pixels with
+ * This operation calculates @in & @c (bitwise and of image pixels with
  * constant
  * @c) and writes the result to @out. 
  *
@@ -353,13 +351,12 @@ CONSTN_BUFFER( OR, | )
 
 /**
  * im_orimage_vec:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @n: array length
  * @c: array of constants
  *
- * This operation calculates @in1 | @c (bitwise or of image pixels with array
+ * This operation calculates @in | @c (bitwise or of image pixels with array
  * @c) and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimageconst().
@@ -378,12 +375,11 @@ im_orimage_vec( IMAGE *in, IMAGE *out, int n, double *c )
 
 /**
  * im_orimageconst:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @c: constant
  *
- * This operation calculates @in1 | @c (bitwise or of image pixels with
+ * This operation calculates @in | @c (bitwise or of image pixels with
  * constant
  * @c) and writes the result to @out. 
  *
@@ -403,13 +399,12 @@ CONSTN_BUFFER( EOR, ^ )
 
 /**
  * im_eorimage_vec:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @n: array length
  * @c: array of constants
  *
- * This operation calculates @in1 ^ @c (bitwise exclusive-or of image pixels 
+ * This operation calculates @in ^ @c (bitwise exclusive-or of image pixels 
  * with array
  * @c) and writes the result to @out. 
  *
@@ -429,12 +424,11 @@ im_eorimage_vec( IMAGE *in, IMAGE *out, int n, double *c )
 
 /**
  * im_eorimageconst:
- * @in1: input #IMAGE 1
+ * @in: input #IMAGE 1
- * @in2: input #IMAGE 2
  * @out: output #IMAGE
  * @c: constant
  *
- * This operation calculates @in1 ^ @c (bitwise exclusive-or of image pixels 
+ * This operation calculates @in ^ @c (bitwise exclusive-or of image pixels 
  * with
  * constant
  * @c) and writes the result to @out. 
@@ -460,7 +454,7 @@ CONSTN_BUFFER( SHIFTL, << )
  * @n: array length
  * @c: array of constants
  *
- * This operation calculates @in1 << @c (left-shift by @c bits
+ * This operation calculates @in << @c (left-shift by @c bits
  * with array
  * @c) and writes the result to @out. 
  *
@@ -484,7 +478,7 @@ im_shiftleft_vec( IMAGE *in, IMAGE *out, int n, double *c )
  * @out: output #IMAGE
  * @n: constant
  *
- * This operation calculates @in1 << @n (left-shift by @n bits)
+ * This operation calculates @in << @n (left-shift by @n bits)
  * and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimageconst().
@@ -510,7 +504,7 @@ CONSTN_BUFFER( SHIFTR, >> )
  * @n: array length
  * @c: array of constants
  *
- * This operation calculates @in1 << @c (right-shift by @c bits
+ * This operation calculates @in << @c (right-shift by @c bits
  * with array
  * @c) and writes the result to @out. 
  *
@@ -534,7 +528,7 @@ im_shiftright_vec( IMAGE *in, IMAGE *out, int n, double *c )
  * @out: output #IMAGE
  * @n: constant
  *
- * This operation calculates @in1 >> @n (right-shift by @n bits)
+ * This operation calculates @in >> @n (right-shift by @n bits)
  * and writes the result to @out. 
  *
  * See also: im_andimage(), im_orimageconst().

libvips/include/vips/Makefile.am

@@ -1,5 +1,6 @@
 pkginclude_HEADERS = \
 	arithmetic.h \
+	relational.h \
 	colour.h \
 	boolean.h \
 	debug.h \

libvips/include/vips/relational.h

@@ -0,0 +1,66 @@
+/* relational.h
+ *
+ * 23/9/09
+ * 	- from proto.h
+ */
+
+/*
+
+    This file is part of VIPS.
+
+    VIPS is free software; you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+ */
+
+/*
+
+    These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
+
+ */
+
+#ifndef IM_RELATIONAL_H
+#define IM_RELATIONAL_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif /*__cplusplus*/
+
+int im_equal( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_notequal( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_less( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_lesseq( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_more( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_moreeq( IMAGE *in1, IMAGE *in2, IMAGE *out );
+int im_equal_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_notequal_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_less_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_lesseq_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_more_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_moreeq_vec( IMAGE *in, IMAGE *out, int n, double *c );
+int im_equalconst( IMAGE *in, IMAGE *out, double c );
+int im_notequalconst( IMAGE *in, IMAGE *out, double c );
+int im_lessconst( IMAGE *in, IMAGE *out, double c );
+int im_lesseqconst( IMAGE *in, IMAGE *out, double c );
+int im_moreconst( IMAGE *in, IMAGE *out, double c );
+int im_moreeqconst( IMAGE *in, IMAGE *out, double c );
+
+int im_ifthenelse( IMAGE *c, IMAGE *a, IMAGE *b, IMAGE *out );
+int im_blend( IMAGE *c, IMAGE *a, IMAGE *b, IMAGE *out );
+
+#ifdef __cplusplus
+}
+#endif /*__cplusplus*/
+
+#endif /*IM_RELATIONAL_H*/

libvips/iofuncs/predicate.c

@@ -377,7 +377,7 @@ im_check_bands_1orn( const char *domain, IMAGE *im1, IMAGE *im2 )
 		(im1->Bands != 1 && im2->Bands != 1) ) {
 		im_error( domain, "%s", 
 			_( "images must have the same number of bands, "
-			"or one muct be single-band" ) );
+			"or one must be single-band" ) );
 		return( -1 );
 	}
 

libvips/relational/im_blend.c

@@ -1,22 +1,14 @@
-/* @(#) Two images as input: must match in size and type. Build an output
+/* im_blend.c --- blend images with a condition image
- * @(#) image blending pixels together according to a conditional image.
- * @(#)
- * @(#) The conditional image can have n bands or 1 band. If n bands, then we
- * @(#) choose from the two source images an element at a time. If 1 band,
- * @(#) then choose from the source images a pixel at a time.
- * @(#)
- * @(#)		int
- * @(#)		im_blend( c, a, b, out )
- * @(#)		IMAGE *c, *a, *b;
- * @(#)		IMAGE *out;
- * @(#)
- * @(#) Returns either 0 (success) or -1 (fail).
  *
  * Modified:
  * 15/4/05
  *	- from im_ifthenelse()
  * 8/7/05
  *	- oops, broken for some combinations of band differences (thanks Joe)
+ * 23/9/09
+ * 	- gtkdoc comments
+ * 	- use im_check*()
+ * 	- allow many-band conditional and single-band a/b
  */
 
 /*
@@ -50,9 +42,8 @@
 #endif /*HAVE_CONFIG_H*/
 #include <vips/intl.h>
 
-#include <assert.h>
-
 #include <vips/vips.h>
+#include <vips/internal.h>
 
 #ifdef WITH_DMALLOC
 #include <dmalloc.h>
@@ -173,7 +164,7 @@ blend1_buffer( PEL *qp, PEL *c, PEL *ap, PEL *bp, int width, IMAGE *im )
 		cblend1( double ); break;
 
 	default:
-		assert( 0 );
+		g_assert( 0 );
 	}
 }
 
@@ -209,7 +200,7 @@ blendn_buffer( PEL *qp, PEL *c, PEL *ap, PEL *bp, int width, IMAGE *im )
 		cblendn( double ); break;
 
 	default:
-		assert( 0 );
+		g_assert( 0 );
 	}
 }
 
@@ -289,78 +280,102 @@ blend_gen( REGION *or, void *seq, void *client1, void *client2 )
 	return( 0 );
 }
 
+/**
+ * im_blend:
+ * @c: condition #IMAGE
+ * @a: then #IMAGE
+ * @b: else #IMAGE
+ * @out: output #IMAGE
+ *
+ * This operation scans the condition image @c (which must be unsigned char) 
+ * and uses it to blend pixels from either the then image @a or the else
+ * image @b. 255 means @a only, 0 means @b only, and intermediate values are a
+ * mixture.
+ *
+ * The conditional image @c can have either 1 band, in which case entire pels
+ * come either from @a or @b, or n bands, where n is the number of bands in 
+ * both @a and @b, in which case individual band elements are chosen from 
+ * @a and @b. Finally, @c may have n bands while @a and @b are single band. In
+ * this case, @a and @b are copied n times to make n band images and those are
+ * operated upon.
+ *
+ * Images @a and @b must match exactly in size, bands and format.
+ *
+ * See also: im_ifthenelse(), im_equal().
+ *
+ * Returns: 0 on success, -1 on error
+ */
 int
 im_blend( IMAGE *c, IMAGE *a, IMAGE *b, IMAGE *out )
 {
-	IMAGE **in;
-
 	/* If a and b are both LABPACK, repack agan after the blend.
 	 */
-	if( a->Coding == IM_CODING_LABQ || b->Coding == IM_CODING_LABQ ) {
+	const int repack = a->Coding == IM_CODING_LABQ && 
-		IMAGE *t[3];
+		b->Coding == IM_CODING_LABQ;
-		int repack = a->Coding == IM_CODING_LABQ && 
-			b->Coding == IM_CODING_LABQ;
 
-		if( im_open_local_array( out, t, 3, "relational-1", "p" ) )
+	IMAGE *t[5];
+	IMAGE **in;
+
+	/* Unpack LABPACK as a courtesy.
+	 */
+	if( im_open_local_array( out, t, 5, "im_blend", "p" ) )
+		return( -1 );
+	if( a->Coding == IM_CODING_LABQ ) {
+		if( im_LabQ2Lab( a, t[0] ) )
 			return( -1 );
-
+		a = t[0];
-		if( a->Coding == IM_CODING_LABQ ) {
+	}
-			if( im_LabQ2Lab( a, t[0] ) )
+	if( b->Coding == IM_CODING_LABQ ) {
-				return( -1 );
+		if( im_LabQ2Lab( b, t[1] ) )
-			a = t[0];
+			return( -1 );
-		}
+		b = t[1];
-
-		if( b->Coding == IM_CODING_LABQ ) {
-			if( im_LabQ2Lab( b, t[1] ) )
-				return( -1 );
-			b = t[1];
-		}
-
-		if( repack ) 
-			return( im_blend( c, a, b, t[2] ) ||
-				im_Lab2LabQ( t[2], out ) );
-		else
-			return( im_blend( c, a, b, out ) );
 	}
 
 	/* Check args.
 	 */
-        if( a->Coding != IM_CODING_NONE || b->Coding != IM_CODING_NONE ||
+	if( im_check_uncoded( "im_blend", c ) ||
-		c->Coding != IM_CODING_NONE ) {
+		im_check_uncoded( "im_blend", a ) ||
-                im_error( "im_blend", "%s", _( "images not uncoded" ) );
+		im_check_uncoded( "im_blend", b ) ||
-                return( -1 );
+		im_check_uchar( "im_blend", c ) ||
-        }
+		im_check_format( "im_blend", a, b ) ||
-	if( a->BandFmt != b->BandFmt ||
+		im_check_bands( "im_blend", a, b ) ||
-		a->Bands != b->Bands ) {
+		im_check_bands_1orn( "im_blend", c, a ) || 
-		im_error( "im_blend", 
+		im_piocheck( c, out ) || 
-			"%s", _( "size and format of then and else "
+		im_pincheck( a ) || 
-			"must match" ) );
+		im_pincheck( b ) )
-		return( -1 );
-	}
-	if( c->BandFmt != IM_BANDFMT_UCHAR ) {
-		im_error( "im_blend", 
-			"%s", _( "conditional image must be uchar" ) );
-		return( -1 );
-	}
-	if( c->Bands != 1 && c->Bands != a->Bands ) {
-		im_error( "im_blend", 
-			"%s", _( "conditional image must be one band or "
-			"same as then and else images" ) );
-		return( -1 );
-	}
-        if( im_piocheck( c, out ) || im_pincheck( a ) || im_pincheck( b ) )
                 return( -1 );
 	if( im_demand_hint( out, IM_THINSTRIP, a, b, c, NULL ) )
 		return( -1 );
 
 	/* Make output image.
 	 */
-	if( im_cp_descv( out, a, b, c, NULL ) || 
+	if( im_cp_descv( out, a, b, c, NULL ) )
-		!(in = im_allocate_input_array( out, c, a, b, NULL )) ||
-		im_generate( out, 
-			im_start_many, blend_gen, im_stop_many, 
-				in, NULL ) )
 		return( -1 );
+	out->Bands = IM_MAX( c->Bands, a->Bands );
+
+	/* Force a/b bands up to the same as out.
+	 */
+	if( im_open_local_array( out, t, 2, "im_blend", "p" ) )
+		return( -1 );
+	if( im__bandup( a, t[2], out->Bands ) ||
+		im__bandup( a, t[3], out->Bands ) )
+		return( -1 );
+	a = t[2];
+	b = t[3];
+
+	if( !(in = im_allocate_input_array( out, c, a, b, NULL )) ||
+		im_generate( t[4], 
+			im_start_many, blend_gen, im_stop_many, in, NULL ) )
+		return( -1 );
+
+	if( repack ) {
+		if( im_Lab2LabQ( t[4], out ) )
+			return( -1 );
+	}
+	else {
+		if( im_copy( t[4], out ) )
+			return( -1 );
+	}
 
 	return( 0 );
 }

libvips/relational/im_ifthenelse.c

@@ -1,17 +1,4 @@
-/* @(#) Two images as input: must match in size and type. Build an output
+/* im_ifthenelse.c --- use a condition image to join two images together
- * @(#) image choosing pixels from the left if a conditional image is
- * @(#) non-zero and from the right otherwise.
- * @(#)
- * @(#) The conditional image can have n bands or 1 band. If n bands, then we
- * @(#) choose from the two source images an element at a time. If 1 band,
- * @(#) then choose from the source images a pixel at a time.
- * @(#)
- * @(#)		int
- * @(#)		im_ifthenelse( c, a, b, out )
- * @(#)		IMAGE *c, *a, *b;
- * @(#)		IMAGE *out;
- * @(#)
- * @(#) Returns either 0 (success) or -1 (fail).
  *
  * Modified:
  * 9/2/95 JC
@@ -22,6 +9,8 @@
  *	- now just evals left/right if all zero/all one
  * 7/10/06
  * 	- set THINSTRIP
+ * 23/9/09
+ * 	- gtkdoc comment
  */
 
 /*
@@ -154,9 +143,27 @@ ifthenelse_gen( REGION *or, void *seq, void *client1, void *client2 )
 	return( 0 );
 }
 
-/* if-then-else. Use IM_BANDFMT_UCHAR image to choose between two other images.
+/**
- * Either: all same number of bands, or choice image is one band, others are
+ * im_ifthenelse:
- * n band.
+ * @c: condition #IMAGE
+ * @a: then #IMAGE
+ * @b: else #IMAGE
+ * @out: output #IMAGE
+ *
+ * This operation scans the condition image @c (which must be unsigned char) 
+ * and uses it to select pixels from either the then image @a or the else
+ * image @b. Non-zero means @a, 0 means @b.
+ *
+ * The conditional image @c can have either 1 band, in which case entire pels
+ * come either from @a or @b, or n bands, where n is the number of bands in 
+ * both @a and @b, in which case individual band elements are chosen from 
+ * @a and @b.
+ *
+ * Images @a and @b must match exactly in size, bands and format.
+ *
+ * See also: im_blend(), im_equal().
+ *
+ * Returns: 0 on success, -1 on error
  */
 int
 im_ifthenelse( IMAGE *c, IMAGE *a, IMAGE *b, IMAGE *out )

libvips/relational/relational_dispatch.c

@@ -42,6 +42,37 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/** 
+ * SECTION: relational
+ * @short_description: relational comparisons between pairs of images and 
+ * images and constants
+ * @see_also: <link linkend="libvips-arithmetic">arithmetic</link>
+ * @stability: Stable
+ * @include: vips/vips.h
+ *
+ * These operations perform comparison operations, such as equals, on
+ * every pixel in an image or pair of images. 
+ * All will work with 
+ * images of any type or any mixture of types of any size and of any number 
+ * of bands.
+ *
+ * For binary operations, if the number of bands differs, one of the images 
+ * must have one band. In this case, an n-band image is formed from the 
+ * one-band image by joining n copies of the one-band image together and then
+ * the two n-band images are operated upon.
+ *
+ * In the same way, for operations that take an array constant, such as 
+ * im_equal_vec(), you can mix single-element arrays or single-band images
+ * freely.
+ *
+ * The output type is always unsigned char, 
+ * with 255 for every band element for which the condition 
+ * is true, and 0 for every other element.
+ * For complex images, the operations calculate and compare the modulus.
+ *
+ * For binary operations on pairs of images, the images must match in size.
+ */
+
 /* Two images in, one out.
  */
 static im_arg_desc two_in_one_out[] = {