multiarray 0.11.3 → 0.11.4

data/lib/multiarray/pointer.rb

@@ -14,8 +14,10 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+# Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Class for representing native pointer types
   class Pointer_ < Node
 
     class << self
@@ -71,7 +73,7 @@ module Hornetseye
           target == other.target
       end
 
-      # Compute hash value for this class.
+      # Compute hash value for this class
       #
       # @return [Fixnum] Hash value
       #
@@ -134,10 +136,16 @@ module Hornetseye
 
     end
 
+    # Constructor for pointer object
+    #
+    # @param [Malloc,List] value Initial value for pointer object.
     def initialize( value = self.class.default )
       @value = value
     end
 
+    # Get access to storage object
+    #
+    # @return [Malloc,List] The object used to store the data.
     def memory
       @value
     end
@@ -156,6 +164,13 @@ module Hornetseye
       return [ variable ], [ self ], variable
     end
 
+    # Get unique descriptor of this object
+    #
+    # @param [Hash] hash Labels for any variables.
+    #
+    # @return [String] Descriptor of this object,
+    #
+    # @private
     def descriptor( hash )
       "#{self.class.to_s}(#{@value.to_s})"
     end
@@ -199,6 +214,14 @@ module Hornetseye
       end
     end
 
+    # Skip elements of an array
+    #
+    # @param [Variable] index Variable identifying index of array.
+    # @param [Node] start Wrapped integer with number of elements to skip.
+    #
+    # @return [Node] Lookup object with elements skipped.
+    #
+    # @private
     def skip( index, start )
       self
     end
@@ -228,6 +251,17 @@ module Hornetseye
 
   end
 
+  # Create a class deriving from +Pointer_+
+  #
+  # Create a class deriving from +Pointer_+. The parameter +target+ is assigned to
+  # the corresponding attribute of the resulting class.
+  #
+  # @param [Class] target The native type of the complex components.
+  #
+  # @return [Class] A class deriving from +Pointer_+.
+  #
+  # @see Pointer_
+  # @see Pointer_.target
   def Pointer( target )
     p = Class.new Pointer_
     p.target = target

data/lib/multiarray/rgb.rb

@@ -31,6 +31,8 @@ module Hornetseye
       #
       # @return [Boolean] Returns +false+ if Ruby object requires
       #         coercion.
+      #
+      # @private
       def generic?( value )
         value.is_a?( Numeric ) or value.is_a?( GCCValue )
       end
@@ -40,6 +42,10 @@ module Hornetseye
       # This method uses meta-programming to define channel-wise unary operations.
       #
       # @param [Symbol,String] op Operation to define channel-wise operation.
+      #
+      # @return [Proc] The new method.
+      #
+      # @private
       def define_unary_op( op )
         define_method( op ) do
           RGB.new r.send( op ), g.send( op ), b.send( op )
@@ -51,6 +57,10 @@ module Hornetseye
       # This method uses meta-programming to define channel-wise binary operations.
       #
       # @param [Symbol,String] op Operation to define channel-wise operation.
+      #
+      # @return [Proc] The new method.
+      #
+      # @private
       def define_binary_op( op )
         define_method( op ) do |other|
           if other.is_a? RGB
@@ -94,14 +104,14 @@ module Hornetseye
       @r, @g, @b = r, g, b
     end
 
-    # Return string with information about this object.
+    # Return string with information about this object
     #
     # @return [String] Returns a string (e.g. "RGB(1,2,3)").
     def inspect
       "RGB(#{@r.inspect},#{@g.inspect},#{@b.inspect})"
     end
 
-    # Return string with information about this object.
+    # Return string with information about this object
     #
     # @return [String] Returns a string (e.g. "RGB(1,2,3)").
     def to_s
@@ -119,6 +129,13 @@ module Hornetseye
       @r, @g, @b = value.r, value.g, value.b
     end
 
+    # Coerce with other object
+    #
+    # @param [RGB] other Other object.
+    #
+    # @return [Array<RGB>] Result of coercion.
+    #
+    # @private
     def coerce( other )
       if other.is_a? RGB
         return other, self
@@ -127,6 +144,11 @@ module Hornetseye
       end
     end
 
+    # This operation has no effect
+    #
+    # @return [InternalComplex] Returns +self+.
+    #
+    # @private
     def +@
       self
     end
@@ -150,14 +172,32 @@ module Hornetseye
     define_binary_op :minor
     define_binary_op :major
 
+    # Check whether value is equal to zero
+    #
+    # @return [Boolean,GCCValue] The result.
+    #
+    # @private
     def zero?
       @r.zero?.and( @g.zero? ).and( @b.zero? )
     end
 
+    # Check whether value is not equal to zero
+    #
+    # @return [Boolean,GCCValue] The result.
+    #
+    # @private
     def nonzero?
       @r.nonzero?.or( @g.nonzero? ).or( @b.nonzero? )
     end
 
+    # Test on equality
+    #
+    # @param [Object] other Object to compare with.
+    #
+    # @return [Boolean] Returns boolean indicating whether objects are
+    #         equal or not.
+    #
+    # @private
     def ==( other )
       if other.is_a? RGB
         @r.eq( other.r ).and( @g.eq( other.g ) ).and( @b.eq( other.b ) )
@@ -183,6 +223,7 @@ end
 
 module Hornetseye
 
+  # Class for representing native RGB values
   class RGB_ < Composite
 
     class << self
@@ -190,6 +231,12 @@ module Hornetseye
       # Set base class attribute
       #
       # Sets number of elements to three.
+      #
+      # @param [Class] subclass The class inheriting from +RGB_+.
+      #
+      # @return The return value should be ignored.
+      #
+      # @private
       def inherited( subclass )
         subclass.num_elements = 3
       end
@@ -216,22 +263,30 @@ module Hornetseye
         RGB.new 0, 0, 0
       end
 
+      # Identifier array used internally
+      #
+      # @private
+      IDENTIFIER = { BYTE    => 'BYTERGB',
+                     UBYTE   => 'UBYTERGB',
+                     SINT    => 'SINTRGB',
+                     USINT   => 'USINTRGB',
+                     INT     => 'INTRGB',
+                     UINT    => 'UINTRGB',
+                     LONG    => 'LONGRGB',
+                     ULONG   => 'ULONGRGB',
+                     SFLOAT  => 'SFLOATRGB',
+                     DFLOAT  => 'DFLOATRGB' }
+
       # Diplay information about this class
       #
       # @return [String] Text with information about this class (e.g. "DFLOATRGB").
       def inspect
         unless element_type.nil?
-          { BYTE    => 'BYTERGB',
-            UBYTE   => 'UBYTERGB',
-            SINT    => 'SINTRGB',
-            USINT   => 'USINTRGB',
-            INT     => 'INTRGB',
-            UINT    => 'UINTRGB',
-            LONG    => 'LONGRGB',
-            ULONG   => 'ULONGRGB',
-            SFLOAT  => 'SFLOATRGB',
-            DFLOAT  => 'DFLOATRGB' }[ element_type ] ||
-            "RGB(#{element_type.inspect})"
+          retval = IDENTIFIER[ element_type ] || "RGB(#{element_type.inspect})"
+          ( class << self; self; end ).instance_eval do
+            define_method( :inspect ) { retval }
+          end
+          retval
         else
           super
         end
@@ -299,7 +354,7 @@ module Hornetseye
           element_type == other.element_type
       end
 
-      # Compute hash value for this class.
+      # Compute hash value for this class
       #
       # @return [Fixnum] Hash value
       #
@@ -319,12 +374,18 @@ module Hornetseye
         self == other
       end
 
+      # Check whether this object is an RGB value
+      #
+      # @return [Boolean] Returns +true+.
       def rgb?
         true
       end
 
     end
 
+    # Constructor for native RGB value
+    #
+    # @param [RGB] value Initial RGB value.
     def initialize( value = self.class.default )
       if Thread.current[ :function ].nil? or
          [ value.r, value.g, value.b ].all? { |c| c.is_a? GCCValue }
@@ -390,6 +451,11 @@ module Hornetseye
       [ @value.r, @value.g, @value.b ]
     end
 
+    # Namespace containing method for matching elements of type RGB_
+    #
+    # @see RGB_
+    #
+    # @private
     module Match
 
       # Method for matching elements of type RGB_
@@ -455,6 +521,9 @@ module Hornetseye
     define_unary_op :g, :scalar
     define_unary_op :b, :scalar
 
+    # Fast extraction for red channel of RGB array
+    #
+    # @return [Node] Array with red channel.
     def r_with_decompose
       if typecode == OBJECT or is_a?( Variable )
         r_without_decompose
@@ -467,6 +536,11 @@ module Hornetseye
 
     alias_method_chain :r, :decompose
 
+    # Assignment for red channel values of RGB array
+    #
+    # @param [Object] Value or array of values to assign to red channel.
+    #
+    # @return [Object] Returns +value+.
     def r=( value )
       if typecode < RGB_
         decompose( 0 )[] = value
@@ -479,6 +553,9 @@ module Hornetseye
       end
     end
 
+    # Fast extraction for green channel of RGB array
+    #
+    # @return [Node] Array with green channel.
     def g_with_decompose
       if typecode == OBJECT or is_a?( Variable )
         g_without_decompose
@@ -491,6 +568,11 @@ module Hornetseye
 
     alias_method_chain :g, :decompose
 
+    # Assignment for green channel values of RGB array
+    #
+    # @param [Object] Value or array of values to assign to green channel.
+    #
+    # @return [Object] Returns +value+.
     def g=( value )
       if typecode < RGB_
         decompose( 1 )[] = value
@@ -503,6 +585,9 @@ module Hornetseye
       end
     end
 
+    # Fast extraction for blue channel of RGB array
+    #
+    # @return [Node] Array with blue channel.
     def b_with_decompose
       if typecode == OBJECT or is_a?( Variable )
         b_without_decompose
@@ -515,6 +600,11 @@ module Hornetseye
 
     alias_method_chain :b, :decompose
 
+    # Assignment for blue channel values of RGB array
+    #
+    # @param [Object] Value or array of values to assign to blue channel.
+    #
+    # @return [Object] Returns +value+.
     def b=( value )
       if typecode < RGB_
         decompose( 2 )[] = value
@@ -529,6 +619,25 @@ module Hornetseye
 
   end
 
+  # Create a class deriving from +RGB_+ or instantiate an +RGB+ object
+  #
+  # @overload RGB( element_type )
+  #   Create a class deriving from +RGB_+. The parameters +element_type+ is
+  #   assigned to the corresponding attribute of the resulting class.
+  #   @param [Class] element_type Element type of native RGB value.
+  #   @return [Class] A class deriving from +RGB_+.
+  #
+  # @overload RGB( r, g, b )
+  #   This is a shortcut for +RGB.new( r, g, b )+.
+  #   @param [Object] r Initial value for red channel.
+  #   @param [Object] g Initial value for green channel.
+  #   @param [Object] b Initial value for blue channel.
+  #   @return [RGB] The RGB value.
+  #
+  # @return [Class,RGB] A class deriving from +RGB_+ or an RGB value.
+  #
+  # @see RGB_
+  # @see RGB_.element_type
   def RGB( arg, g = nil, b = nil )
     if g.nil? and b.nil?
       retval = Class.new RGB_
@@ -541,24 +650,34 @@ module Hornetseye
 
   module_function :RGB
 
+  # 24-bit unsigned RGB-triplet
   BYTERGB   = RGB BYTE
 
+  # 24-bit signed RGB-triplet
   UBYTERGB  = RGB UBYTE
 
+  # 48-bit unsigned RGB-triplet
   SINTRGB   = RGB SINT
 
+  # 48-bit signed RGB-triplet
   USINTRGB  = RGB USINT
 
+  # 96-bit unsigned RGB-triplet
   INTRGB    = RGB INT
 
+  # 96-bit signed RGB-triplet
   UINTRGB   = RGB UINT
 
+  # 192-bit unsigned RGB-triplet
   LONGRGB   = RGB LONG
 
+  # 192-bit signed RGB-triplet
   ULONGRGB  = RGB ULONG
 
+  # single precision RGB-triplet
   SFLOATRGB = RGB SFLOAT
 
+  # double precision RGB-triplet
   DFLOATRGB = RGB DFLOAT
 
   # Shortcut for constructor
@@ -708,6 +827,12 @@ class Fixnum
 
   if method_defined? :rpower
 
+    # +**+ is modified to work with RGB values
+    #
+    # @param [Object] other Second operand for binary operation.
+    # @return [Object] Result of binary operation.
+    #
+    # @private
     def power_with_rgb( other )
       if other.is_a? Hornetseye::RGB
         x, y = other.coerce self

data/lib/multiarray/sequence.rb

@@ -32,6 +32,15 @@ module Hornetseye
         MultiArray.new typecode, size
       end
 
+      # Import array from string
+      #
+      # Create an array from raw data provided as a string.
+      #
+      # @param [Class] typecode Type of the elements in the string.
+      # @param [String] string String with raw data.
+      # @param [Integer] size Size of array.
+      #
+      # @return [Node] One-dimensional array with imported data.
       def import( typecode, string, size )
         t = Hornetseye::Sequence typecode, size
         if string.is_a? Malloc
@@ -95,6 +104,12 @@ module Hornetseye
         end
       end
 
+      # Create (lazy) index array
+      #
+      # @param [Integer] offset First value of array.
+      # @param [Integer] increment Increment for subsequent values.
+      #
+      # @return [Node] Lazy term generating the array.
       def indgen( offset = 0, increment = 1 )
         Hornetseye::lazy( num_elements ) do |i|
           ( element_type.size * increment * i +
@@ -102,6 +117,11 @@ module Hornetseye
         end
       end
 
+      # Construct native array from Ruby array
+      #
+      # @param [Array<Object>] args Array with Ruby values.
+      #
+      # @return [Node] Native array with specified values.
       def []( *args )
         retval = new
         recursion = lambda do |element,args|
@@ -117,30 +137,51 @@ module Hornetseye
         retval
       end
 
+      # Get dimensions of array type
+      #
+      # @return [Array<Integer>] 
       def shape
         element_type.shape + [ num_elements ]
       end
 
+      # Get width of two-dimensional array type
+      #
+      # @return [Integer] Width of array.
       def width
         shape[0]
       end
 
+      # Get height of two-dimensional array
+      #
+      # @return [Integer] Height of array.
       def height
         shape[1]
       end
 
+      # Get size of array type
+      #
+      # @return [Integer] Size of array.
       def size
         num_elements * element_type.size
       end
 
+      # Get storage size of array type
+      #
+      # @return [Integer] Storage size of array.
       def storage_size
         num_elements * element_type.storage_size
       end
 
+      # Check whether type denotes an empty array
+      #
+      # @return [Boolean] Return +true+ for empty array.
       def empty?
         size == 0
       end
 
+      # Get element type of array type
+      #
+      # @return [Class] Element type of array.
       def typecode
         element_type.typecode
       end
@@ -163,26 +204,53 @@ module Hornetseye
         self
       end
 
+      # Get pointer type of delayed operation
+      #
+      # @return [Class] Type of result.
+      #
+      # @private
       def pointer_type
         self
       end
 
+      # Get dimension of type of delayed operation
+      #
+      # @return [Integer] Number of dimensions.
       def dimension
         element_type.dimension + 1
       end
 
+      # Check whether delayed operation will have colour
+      #
+      # @return [Boolean] Boolean indicating whether the array has elements of type
+      #         RGB.
       def rgb?
         element_type.rgb?
       end
 
+      # Get corresponding contiguous type
+      #
+      # @return [Class] Returns +self+.
+      #
+      # @private
       def contiguous
         self
       end
 
+      # Get corresponding boolean type
+      #
+      # @return [Class] Returns type for array of boolean values.
+      #
+      # @private
       def bool
         Hornetseye::Sequence element_type.bool, num_elements
       end
 
+      # Coerce and convert to boolean type
+      #
+      # @return [Class] Returns type for array of boolean values.
+      #
+      # @private
       def coercion_bool( other )
         coercion( other ).bool
       end
@@ -190,10 +258,17 @@ module Hornetseye
       # Get corresponding scalar type
       #
       # @return [Class] Returns type for array of scalars.
+      #
+      # @private
       def scalar
         Hornetseye::Sequence element_type.scalar, num_elements
       end
 
+      # Get corresponding floating point type
+      #
+      # @return [Class] Returns type for array of floating point numbers.
+      #
+      # @private
       def float_scalar
         Hornetseye::Sequence element_type.float_scalar, num_elements
       end
@@ -201,18 +276,35 @@ module Hornetseye
       # Get corresponding maximum integer type
       #
       # @return [Class] Returns type based on maximum integers.
+      #
+      # @private
       def maxint
         Hornetseye::Sequence element_type.maxint, num_elements
       end
 
+      # Coerce and convert to maximum integer type
+      #
+      # @return [Class] Returns type based on maximum integers.
+      #
+      # @private
       def coercion_maxint( other )
         coercion( other ).maxint
       end
 
+      # Get corresponding byte type
+      #
+      # @return [Class] Returns type based on byte.
+      #
+      # @private
       def byte
         Hornetseye::Sequence element_type.byte, num_elements
       end
 
+      # Coerce and convert to byte type
+      #
+      # @return [Class] Returns type based on byte.
+      #
+      # @private
       def coercion_byte( other )
         coercion( other ).byte
       end
@@ -226,31 +318,56 @@ module Hornetseye
         Hornetseye::Sequence element_type.float, num_elements
       end
 
+      # Coerce and convert to type based on floating point numbers
+      #
+      # @return [Class] Corresponding type based on floating point numbers.
+      #
+      # @private
       def floating( other )
         coercion( other ).float
       end
 
+      # Coerce with two other types
+      #
+      # @return [Class] Result of coercion.
+      #
+      # @private
       def cond( a, b )
         t = a.coercion b
         Hornetseye::MultiArray( t.typecode, *shape ).coercion t
       end
 
+      # Replace element type
+      #
+      # @return [Class] Result of conversion.
+      #
+      # @private
       def to_type( dest )
         Hornetseye::Sequence element_type.to_type( dest ), num_elements
       end
 
+      # Display this type
+      #
+      # @return [String] String with description of this type.
       def inspect
         if element_type and num_elements
           if dimension == 1
-            "Sequence(#{typecode.inspect},#{num_elements.inspect})"
+            retval = "Sequence(#{typecode.inspect},#{num_elements.inspect})"
           else
-            "MultiArray(#{typecode.inspect},#{shape.join ','})"
+            retval = "MultiArray(#{typecode.inspect},#{shape.join ','})"
           end
+          ( class << self; self; end ).instance_eval do
+            define_method( :inspect ) { retval }
+          end
+          retval
         else
           'MultiArray(?,?)'
         end
       end
 
+      # Compute unique descriptor
+      #
+      # @return [String] Unique descriptor of this type.
       def to_s
         descriptor( {} )
       end
@@ -317,10 +434,18 @@ module Hornetseye
         end
       end
 
+      # Instantiate array of this type
+      #
+      # @param [Malloc,List] memory Object for storing array elements.
+      #
+      # @return [Node] The array expression.
       def new( memory = nil )
         MultiArray.new typecode, *( shape + [ :memory => memory ] )
       end
 
+      # Check whether this array expression allows compilation
+      #
+      # @return [Boolean] Returns +true+ if this expression supports compilation.
       def compilable?
         element_type.compilable?
       end
@@ -380,6 +505,19 @@ module Hornetseye
 
   end
 
+  # Create a class deriving from +Sequence_+
+  #
+  # Create a class deriving from +Sequence_+. The parameters +element_type+ and
+  # +num_elements+ are assigned to the corresponding attribute of the resulting class.
+  #
+  # @param [Class] element_type The element type of the native array.
+  # @param [Integer] num_elements The number of elements.
+  #
+  # @return [Class] A class deriving from +Sequence_+.
+  #
+  # @see Sequence_
+  # @see Sequence_.element_type
+  # @see Sequence_.num_elements
   def Sequence( element_type, num_elements )
     retval = Class.new Sequence_
     retval.element_type = element_type