multiarray 0.11.3 → 0.11.4

data/lib/multiarray/methods.rb

@@ -17,11 +17,15 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Module providing the methods to manipulate array expressions
   module Methods
 
-    # Extend some methods in the specified module.
+    # Extend some methods in the specified module
     #
     # @param [Module] mod The mathematics module.
+    # @return The return value should be ignored.
+    #
+    # @private
     def Methods.included( mod )
       define_unary_method  mod, :sqrt , :float
       define_unary_method  mod, :log  , :float
@@ -43,11 +47,14 @@ module Hornetseye
       define_binary_method mod, :hypot, :floating
     end
 
-    # Extend unary method with capability to handle arrays.
+    # Extend unary method with capability to handle arrays
     #
     # @param [Module] mod The mathematics module.
     # @param [Symbol,String] op The unary method to extend.
     # @param [Symbol,String] conversion A method for doing the type conversion.
+    # @return [Proc] The new method.
+    #
+    # @private
     def define_unary_method( mod, op, conversion = :contiguous )
       mod.module_eval do
         define_method( "#{op}_with_hornetseye" ) do |a|
@@ -73,11 +80,14 @@ module Hornetseye
 
     module_function :define_unary_method
 
-    # Extend binary method with capability to handle arrays.
+    # Extend binary method with capability to handle arrays
     #
     # @param [Module] mod The mathematics module.
     # @param [Symbol,String] op The binary method to extend.
     # @param [Symbol,String] conversion A method for doing the type balancing.
+    # @return [Proc] The new method.
+    #
+    # @private
     def define_binary_method( mod, op, coercion = :coercion )
       mod.module_eval do
         define_method( "#{op}_with_hornetseye" ) do |a,b|

data/lib/multiarray/multiarray.rb

@@ -26,6 +26,8 @@ module Hornetseye
       #
       # @param [Class] typecode The type of elements
       # @param [Array<Integer>] *shape The shape of the multi-dimensional array.
+      #
+      # @return [Node] Returns uninitialised native array.
       def new( typecode, *shape )
         options = shape.last.is_a?( Hash ) ? shape.pop : {}
         count = options[ :count ] || 1
@@ -44,6 +46,15 @@ module Hornetseye
         end
       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 [Array<Integer>] shape Array with dimensions of array.
+      #
+      # @return [Node] Multi-dimensional array with imported data.
       def import( typecode, string, *shape )
         t = Hornetseye::MultiArray typecode, *shape
         if string.is_a? Malloc

data/lib/multiarray/node.rb

@@ -43,7 +43,7 @@ module Hornetseye
       #
       # @private
       def descriptor( hash )
-        'Node'
+        name
       end
 
       # Find matching native datatype to a Ruby value
@@ -117,10 +117,16 @@ module Hornetseye
         []
       end
 
+      # Get width of two-dimensional array
+      #
+      # @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
@@ -155,6 +161,9 @@ module Hornetseye
         self
       end
 
+      # Check whether this object is an RGB value
+      #
+      # @return [Boolean] Returns +false+.
       def rgb?
         false
       end
@@ -237,6 +246,12 @@ module Hornetseye
         coercion( other ).byte
       end
 
+      # Get byte-based datatype for ternary operation
+      #
+      # @param [Class] a The second type.
+      # @param [Class] a The third type.
+      #
+      # @return [Class] Returns type based on bytes.
       def cond( a, b )
         t = a.coercion b
         Hornetseye::MultiArray( t.typecode, *shape ).coercion t
@@ -336,6 +351,9 @@ module Hornetseye
       array_type.typecode
     end
 
+    # Base-type of this term
+    #
+    # @return [Class] Base-type of this datatype.
     def basetype
       array_type.basetype
     end
@@ -347,10 +365,16 @@ module Hornetseye
       array_type.shape
     end
 
+    # Get width of two-dimensional array
+    #
+    # @return [Integer] Width of array.
     def width
       array_type.width
     end
 
+    # Get height of two-dimensional array
+    #
+    # @return [Integer] Height of array.
     def height
       array_type.height
     end
@@ -362,15 +386,21 @@ module Hornetseye
       array_type.size
     end
 
+    # Get memory size of object
+    #
+    # @return [Integer] Returns required storage size of this array.
     def storage_size
       array_type.storage_size
     end
 
+    # Get memory object
+    #
+    # @return [Malloc,List,NilClass] This method will return +nil+.
     def memory
       nil
     end
 
-    # Check whether this object is an empty array.
+    # Check whether this object is an empty array
     #
     # @return [Boolean] Returns whether this object is an empty array.
     def empty?
@@ -384,6 +414,9 @@ module Hornetseye
       array_type.dimension
     end
 
+    # Check whether this object is an RGB value
+    #
+    # @return [Boolean] Returns +false+.
     def rgb?
       array_type.rgb?
     end
@@ -553,14 +586,24 @@ module Hornetseye
       end
     end
 
+    # Check arguments for compatible shape
+    #
+    # The method will throw an exception if one of the arguments has an incompatible
+    # shape.
+    #
+    # @param [Array<Node>] args Arguments to check for compatibility.
+    #
+    # @return [Object] The return value should be ignored.
     def check_shape( *args )
+      _shape = shape
       args.each do |arg|
-        if dimension < arg.dimension
+        _arg_shape = arg.shape
+        if _shape.size < _arg_shape.size
           raise "#{arg.array_type.inspect} has #{arg.dimension} dimension(s) " +
                 "but should not have more than #{dimension}"
         end
-        if ( shape + arg.shape ).all? { |s| s.is_a? Integer }
-          if shape.last( arg.dimension ) != arg.shape
+        if ( _shape + _arg_shape ).all? { |s| s.is_a? Integer }
+          if _shape.last( _arg_shape.size ) != _arg_shape
             raise "#{arg.array_type.inspect} has shape #{arg.shape.inspect} " +
                   "(does not match last value(s) of #{shape.inspect})"
           end
@@ -578,7 +621,7 @@ module Hornetseye
     # @return [Object,Node] Returns the value.
     def []=( *indices )
       value = indices.pop
-      value = Node.match( value ).new value unless value.is_a? Node
+      value = typecode.new value unless value.is_a? Node
       if indices.empty?
         check_shape value
         unless compilable? and value.compilable? and dimension > 0
@@ -638,10 +681,10 @@ module Hornetseye
     #
     # @private
     def force
-      if ( dimension > 0 and Thread.current[ :lazy ] ) or not variables.empty?
-        self
-      elsif finalised?
+      if finalised?
         get
+      elsif ( dimension > 0 and Thread.current[ :lazy ] ) or not variables.empty?
+        self
       elsif compilable?
         retval = pointer_type.new
         GCCFunction.run Store.new( retval, self )

data/lib/multiarray/operations.rb

@@ -17,8 +17,17 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Module providing the operations to manipulate array expressions
   module Operations
 
+    # Meta-programming method to define a unary operation
+    #
+    # @param [Symbol,String] op Name of unary operation.
+    # @param [Symbol,String] conversion Name of method for type conversion.
+    #
+    # @return [Proc] The new method.
+    #
+    # @private
     def define_unary_op( op, conversion = :contiguous )
       define_method( op ) do
         if dimension == 0 and variables.empty?
@@ -34,6 +43,14 @@ module Hornetseye
 
     module_function :define_unary_op
 
+    # Meta-programming method to define a binary operation
+    #
+    # @param [Symbol,String] op Name of binary operation.
+    # @param [Symbol,String] conversion Name of method for type conversion.
+    #
+    # @return [Proc] The new method.
+    #
+    # @private
     def define_binary_op( op, coercion = :coercion )
       define_method( op ) do |other|
         unless other.is_a? Node
@@ -87,10 +104,20 @@ module Hornetseye
     define_binary_op :minor
     define_binary_op :major
 
+    # This operation has no effect
+    #
+    # @return [Node] Returns +self+.
+    #
+    # @private
     def +@
       self
     end
 
+    # Convert array elements to different element type
+    #
+    # @param [Class] dest Element type to convert to.
+    #
+    # @return [Node] Array based on the different element type.
     def to_type( dest )
       if dimension == 0 and variables.empty?
         target = typecode.to_type dest
@@ -102,6 +129,13 @@ module Hornetseye
       end
     end
 
+    # Convert RGB array to scalar array
+    #
+    # This operation is a special case handling colour to greyscale conversion.
+    #
+    # @param [Class] dest Element type to convert to.
+    #
+    # @return [Node] Array based on the different element type.
     def to_type_with_rgb( dest )
       if typecode < RGB_
         if dest < FLOAT_
@@ -118,6 +152,12 @@ module Hornetseye
 
     alias_method_chain :to_type, :rgb
 
+    # Element-wise conditional selection of values
+    #
+    # @param [Node] a First array of values.
+    # @param [Node] b Second array of values.
+    #
+    # @return [Node] Array with selected values.
     def conditional( a, b )
       unless a.is_a? Node
         a = Node.match( a, b.is_a?( Node ) ? b : nil ).new a
@@ -137,6 +177,11 @@ module Hornetseye
       end
     end
 
+    # Element-wise comparison of values
+    #
+    # @param [Node] other Array with values to compare with.
+    #
+    # @return [Node] Array with results.
     def <=>( other )
       Hornetseye::lazy do
         ( self < other ).conditional -1, ( self > other ).conditional( 1, 0 )
@@ -162,6 +207,11 @@ module Hornetseye
         inject( term ) { |retval,var| Lambda.new var, retval }
     end
 
+    # Cycle indices of array
+    #
+    # @param [Integer] n Number of times to cycle indices of array.
+    #
+    # @return [Node] Resulting array expression with different order of indices.
     def roll( n = 1 )
       if n < 0
         unroll -n
@@ -172,6 +222,11 @@ module Hornetseye
       end
     end
 
+    # Reverse-cycle indices of array
+    #
+    # @param [Integer] n Number of times to cycle back indices of array.
+    #
+    # @return [Node] Resulting array expression with different order of indices.
     def unroll( n = 1 )
       if n < 0
         roll -n
@@ -182,6 +237,11 @@ module Hornetseye
       end
     end
 
+    # Perform element-wise operation on array
+    #
+    # @param [Proc] action Operation(s) to perform on elements.
+    #
+    # @return [Node] The resulting array.
     def collect( &action )
       var = Variable.new typecode
       block = action.call var
@@ -189,8 +249,22 @@ module Hornetseye
       Hornetseye::ElementWise( action, block.to_s, conversion ).new( self ).force
     end
 
+    # Perform element-wise operation on array
+    #
+    # @param [Proc] action Operation(s) to perform on elements.
+    #
+    # @return [Node] The resulting array.
     alias_method :map, :collect
 
+    # Perform cummulative operation on array
+    #
+    # @param [Object] initial Initial value for cummulative operation.
+    # @option options [Variable] :var1 First variable defining operation.
+    # @option options [Variable] :var1 Second variable defining operation.
+    # @option options [Variable] :block (yield( var1, var2 )) The operation to
+    #         apply.
+    #
+    # @return [Object] Result of injection.
     def inject( initial = nil, options = {} )
       unless initial.nil?
         initial = Node.match( initial ).new initial unless initial.is_a? Node
@@ -209,8 +283,9 @@ module Hornetseye
         end
       else
         index = Variable.new Hornetseye::INDEX( nil )
-        value = element( index ).
-          inject nil, :block => block, :var1 => var1, :var2 => var2
+        value = element( index ).inject nil, :block => block,
+                                        :var1 => var1, :var2 => var2
+        value = typecode.new value unless value.is_a? Node
         Inject.new( value, index, initial, block, var1, var2 ).force
       end
     end
@@ -236,22 +311,39 @@ module Hornetseye
 
     alias_method_chain :==, :multiarray, :eq
 
+    # Find minimum value of array
+    #
+    # @return [Object] Minimum value of array.
     def min
       inject { |a,b| a.minor b }
     end
 
+    # Find maximum value of array
+    #
+    # @return [Object] Maximum value of array.
     def max
       inject { |a,b| a.major b }
     end
 
+    # Compute sum of array
+    #
+    # @return [Object] Sum of array.
     def sum
       inject { |a,b| a + b }
     end
 
+    # Find range of values of array
+    #
+    # @return [Object] Range of values of array.
     def range
       min .. max
     end
 
+    # Normalise values of array
+    #
+    # @param [Range] range Target range of normalisation.
+    #
+    # @return [Node] Array with normalised values.
     def normalise( range = 0 .. 0xFF )
       if range.exclude_end?
         raise "Normalisation does not support ranges with end value " +
@@ -273,6 +365,11 @@ module Hornetseye
       end
     end
 
+    # Fill array with a value
+    #
+    # @param [Object] value Value to fill array with.
+    #
+    # @return [Node] Return +self+.
     def fill!( value = typecode.default )
       self[] = value
       self
@@ -355,12 +452,20 @@ module Hornetseye
       product( filter ).diagonal { |s,x| s + x }
     end
 
+    # Compute histogram of this array
+    #
+    # @overload histogram( *ret_shape, options = {} )
+    #   @param [Array<Integer>] ret_shape Dimensions of resulting histogram.
+    #   @option options [Boolean] :safe (true) Do a boundary check before creating the
+    #           histogram.
+    #
+    # @return [Node] The histogram.
     def histogram( *ret_shape )
       options = ret_shape.last.is_a?( Hash ) ? ret_shape.pop : {}
       options = { :target => UINT, :safe => true }.merge options
       if options[ :safe ]
         if shape.first != 1 and ret_shape.size == 1
-          right = Hornetseye::lazy( 1 ) { |i| self }.unroll
+          right = Hornetseye::lazy( 1 ) { self }.unroll
         else
           if shape.first != ret_shape.size
             raise "First dimension of array (#{shape.first}) differs from number of " +
@@ -395,12 +500,13 @@ module Hornetseye
       left
     end
 
-    #def histogram_with_composite( *ret_shape )
-    #  decompose.histogram_without_composite *ret_shape
-    #end
-
-    #alias_method_chain :histogram, :composite
-
+    # Perform element-wise lookup
+    #
+    # @param [Node] table The lookup table (LUT).
+    # @option options [Boolean] :safe (true) Do a boundary check before creating the
+    #         element-wise lookup.
+    #
+    # @return [Node] The result of the lookup operation.
     def lut( table, options = {} )
       options = { :safe => true }.merge options
       if options[ :safe ]
@@ -441,12 +547,9 @@ module Hornetseye
       end
     end
 
-    #def lut_with_composite( table, options = {} )
-    #  decompose.lut_without_composite table, options
-    #end
-
-    #alias_method_chain :lut, :composite
-
+    # Compute integral image
+    #
+    # @return [Node] The integral image of this array.
     def integral
       left = pointer_type.new
       block = Integral.new left, self