multiarray 0.5.2 → 0.6.0

data/lib/multiarray/rgb.rb

@@ -17,20 +17,40 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Representation for colour pixel
   class RGB
 
     class << self
 
+      # Check compatibility of other type
+      #
+      # This method checks whether binary operations with the other Ruby object can
+      # be performed without requiring coercion.
+      #
+      # @param [Object] value The other Ruby object.
+      #
+      # @return [Boolean] Returns +false+ if Ruby object requires
+      #         coercion.
       def generic?( value )
         value.is_a?( Numeric ) or value.is_a?( GCCValue )
       end
 
+      # Defines a unary operation
+      #
+      # This method uses meta-programming to define channel-wise unary operations.
+      #
+      # @param [Symbol,String] op Operation to define channel-wise operation.
       def define_unary_op( op )
         define_method( op ) do
           RGB.new r.send( op ), g.send( op ), b.send( op )
         end
       end
 
+      # Defines a binary operation
+      #
+      # This method uses meta-programming to define channel-wise binary operations.
+      #
+      # @param [Symbol,String] op Operation to define channel-wise operation.
       def define_binary_op( op )
         define_method( op ) do |other|
           if other.is_a? RGB
@@ -48,20 +68,53 @@ module Hornetseye
 
     end
 
-    attr_accessor :r, :g, :b
-
+    # Access red channel
+    #
+    # @return [Object] Value of red channel.
+    attr_accessor :r
+
+    # Access green channel
+    #
+    # @return [Object] Value of green channel.
+    attr_accessor :g
+
+    # Access blue channel
+    #
+    # @return [Object] Value of blue channel.
+    attr_accessor :b
+
+    # Constructor
+    #
+    # Create new RGB object.
+    #
+    # @param [Object] r Red colour component.
+    # @param [Object] g Green colour component.
+    # @param [Object] b Blue colour component.
     def initialize( r, g, b )
       @r, @g, @b = r, g, b
     end
 
+    # 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] Returns a string (e.g. "RGB(1,2,3)").
     def to_s
       "RGB(#{@r.to_s},#{@g.to_s},#{@b.to_s})"
     end
 
+    # Store new value in this RGB object
+    #
+    # @param [Object] value New value for this object.
+    #
+    # @return [Object] Returns +value+.
+    #
+    # @private
     def store( value )
       @r, @g, @b = value.r, value.g, value.b
     end
@@ -111,6 +164,11 @@ module Hornetseye
       end
     end
 
+    # Decompose RGB number
+    #
+    # This method decomposes the RGB value into an array.
+    #
+    # @return [Node] An array with the three channel values as elements.
     def decompose
       Hornetseye::Sequence[ @r, @g, @b ]
     end
@@ -121,18 +179,38 @@ module Hornetseye
 
     class << self
 
+      # Set base class attribute
+      #
+      # Sets number of elements to three.
       def inherited( subclass )
         subclass.num_elements = 3
       end
 
+      # Construct new object from arguments
+      #
+      # @param [Object] r Value for red channel.
+      # @param [Object] g Value for green channel.
+      # @param [Object] b Value for blue channel.
+      #
+      # @return [RGB] New object of this type.
+      #
+      # @private
       def construct( r, g, b )
         new RGB.new( r, g, b )
       end
 
+      # Get default value for elements of this type
+      #
+      # @return [Object] Returns +RGB( 0, 0, 0 )+.
+      #
+      # @private
       def default
         RGB.new 0, 0, 0
       end
 
+      # Diplay information about this class
+      #
+      # @return [String] Text with information about this class (e.g. "DFLOATRGB").
       def inspect
         unless element_type.nil?
           { BYTE    => 'BYTERGB',
@@ -151,14 +229,31 @@ module Hornetseye
         end
       end
 
+      # Get corresponding maximum integer type
+      #
+      # @return [Class] Returns RGB type based on integers.
+      #
+      # @private
       def maxint
         Hornetseye::RGB element_type.maxint
       end
 
+      # Convert to type based on floating point numbers
+      #
+      # @return [Class] Corresponding type based on floating point numbers.
+      #
+      # @private
       def float
         Hornetseye::RGB element_type.float
       end
 
+      # Compute balanced type for binary operation
+      #
+      # @param [Class] other Other native datatype to coerce with.
+      #
+      # @return [Class] Result of coercion.
+      #
+      # @private
       def coercion( other )
         if other < RGB_
           Hornetseye::RGB element_type.coercion( other.element_type )
@@ -169,6 +264,13 @@ module Hornetseye
         end
       end
 
+      # Type coercion for native elements
+      #
+      # @param [Class] other Other type to coerce with.
+      #
+      # @return [Array<Class>] Result of coercion.
+      #
+      # @private
       def coerce( other )
         if other < RGB_
           return other, self
@@ -179,15 +281,32 @@ module Hornetseye
         end
       end
 
+      # Test equality of classes
+      #
+      # @param [Object] other Object to compare with.
+      #
+      # @return [Boolean] Boolean indicating whether classes are equal.
       def ==( other )
         other.is_a? Class and other < RGB_ and
           element_type == other.element_type
       end
 
+      # Compute hash value for this class.
+      #
+      # @return [Fixnum] Hash value
+      #
+      # @private
       def hash
         [ :RGB_, element_type ].hash
       end
 
+      # Equality for hash operations
+      #
+      # @param [Object] other Object to compare with.
+      #
+      # @return [Boolean] Returns +true+ if objects are equal.
+      #
+      # @private
       def eql?( other )
         self == other
       end
@@ -206,6 +325,9 @@ module Hornetseye
       end
     end
 
+    # Duplicate object
+    #
+    # @return [RGB_] Duplicate of +self+.
     def dup
       if Thread.current[ :function ]
         r = Thread.current[ :function ].variable self.class.element_type, 'v'
@@ -220,6 +342,13 @@ module Hornetseye
       end
     end
 
+    # Store new value in this object
+    #
+    # @param [Object] value New value for this object.
+    #
+    # @return [Object] Returns +value+.
+    #
+    # @private
     def store( value )
       value = value.simplify
       if @value.r.respond_to? :store
@@ -240,12 +369,27 @@ module Hornetseye
       value
     end
 
+    # Get values of composite number
+    #
+    # @return [Array<Object>] Returns array with red, green, and blue component.
+    #
+    # @private
     def values
       [ @value.r, @value.g, @value.b ]
     end
 
     module Match
 
+      # Method for matching elements of type RGB_
+      #
+      # @param [Array<Object>] *values Values to find matching native element
+      #        type for.
+      #
+      # @return [Class] Native type fitting all values.
+      #
+      # @see RGB_
+      #
+      # @private
       def fit( *values )
         if values.all? { |value| value.is_a? RGB or value.is_a? Float or
                                  value.is_a? Integer }
@@ -271,6 +415,14 @@ module Hornetseye
         end
       end
 
+      # Perform type alignment
+      #
+      # Align this type to another. This is used to prefer single-precision
+      # floating point in certain cases.
+      #
+      # @param [Class] context Other type to align with.
+      #
+      # @private
       def align( context )
         if self < RGB_
           Hornetseye::RGB element_type.align( context )
@@ -285,6 +437,86 @@ module Hornetseye
 
   end
 
+  module Operations
+
+    define_unary_op :r, :scalar
+    define_unary_op :g, :scalar
+    define_unary_op :b, :scalar
+
+    def r_with_decompose
+      if typecode < RGB_
+        decompose.roll.element 0
+      elsif typecode == OBJECT
+        r_without_decompose
+      else
+        self
+      end
+    end
+
+    alias_method_chain :r, :decompose
+
+    def r=( value )
+      if typecode < RGB_
+        decompose.roll[ 0 ] = value
+      elsif typecode == OBJECT
+        self[] = Hornetseye::lazy do
+          value * RGB.new( 1, 0, 0 ) + g * RGB.new( 0, 1, 0 ) + b * RGB.new( 0, 0, 1 )
+        end
+      else
+        raise "Cannot assign red channel to object of type #{array_type.inspect}"
+      end
+    end
+
+    def g_with_decompose
+      if typecode < RGB_
+        decompose.roll.element 1
+      elsif typecode == OBJECT
+        g_without_decompose
+      else
+        self
+      end
+    end
+
+    alias_method_chain :g, :decompose
+
+    def g=( value )
+      if typecode < RGB_
+        decompose.roll[ 1 ] = value
+      elsif typecode == OBJECT
+        self[] = Hornetseye::lazy do
+          r * RGB.new( 1, 0, 0 ) + value * RGB.new( 0, 1, 0 ) + b * RGB.new( 0, 0, 1 )
+        end
+      else
+        raise "Cannot assign green channel to object of type #{array_type.inspect}"
+      end
+    end
+
+    def b_with_decompose
+      if typecode < RGB_
+        decompose.roll.element 2
+      elsif typecode == OBJECT
+        b_without_decompose
+      else
+        self
+      end
+    end
+
+    alias_method_chain :b, :decompose
+
+    def b=( value )
+      if typecode < RGB_
+        decompose.roll[ 2 ] = value
+      elsif typecode == OBJECT
+        self[] = Hornetseye::lazy do
+          r * RGB.new( 1, 0, 0 ) + g * RGB.new( 0, 1, 0 ) + value * RGB.new( 0, 0, 1 )
+        end
+      else
+        raise "Cannot assign blue channel to object of type #{array_type.inspect}"
+      end
+    end
+
+  end
+
   def RGB( arg, g = nil, b = nil )
     if g.nil? and b.nil?
       retval = Class.new RGB_
@@ -317,42 +549,132 @@ module Hornetseye
 
   DFLOATRGB = RGB DFLOAT
 
+  # Shortcut for constructor
+  #
+  # The method calls +BYTERGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [BYTERGB] The wrapped RGB value.
+  #
+  # @private
   def BYTERGB( value )
     BYTERGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +UBYTERGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [UBYTERGB] The wrapped RGB value.
+  #
+  # @private
   def UBYTERGB( value )
     UBYTERGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +SINTRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [SINTRGB] The wrapped RGB value.
+  #
+  # @private
   def SINTRGB( value )
     SINTRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +USINTRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [USINTRGB] The wrapped RGB value.
+  #
+  # @private
   def USINTRGB( value )
     USINTRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +INTRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [INTRGB] The wrapped RGB value.
+  #
+  # @private
   def INTRGB( value )
     INTRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +UINTRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [UINTRGB] The wrapped RGB value.
+  #
+  # @private
   def UINTRGB( value )
     UINTRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +LONGRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [LONGRGB] The wrapped RGB value.
+  #
+  # @private
   def LONGRGB( value )
     LONGRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +ULONGRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [ULONGRGB] The wrapped RGB value.
+  #
+  # @private
   def ULONGRGB( value )
     ULONGRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +SFLOATRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [SFLOATRGB] The wrapped RGB value.
+  #
+  # @private
   def SFLOATRGB( value )
     SFLOATRGB.new value
   end
 
+  # Shortcut for constructor
+  #
+  # The method calls +DFLOATRGB.new+.
+  #
+  # @param [RGB] value RGB value.
+  #
+  # @return [DFLOATRGB] The wrapped RGB value.
+  #
+  # @private
   def DFLOATRGB( value )
     DFLOATRGB.new value
   end

data/lib/multiarray/sequence.rb

@@ -69,6 +69,11 @@ module Hornetseye
       # @return [Integer] num_elements Number of elements.
       attr_accessor :num_elements
 
+      # Get default value for elements of this type
+      #
+      # @return [Object] Returns an array of default values.
+      #
+      # @private
       def default
         Hornetseye::lazy( num_elements ) do |i|
           if element_type.dimension > 0
@@ -105,10 +110,22 @@ module Hornetseye
         element_type.shape + [ num_elements ]
       end
 
+      def width
+        shape[0]
+      end
+
+      def height
+        shape[1]
+      end
+
       def size
         num_elements * element_type.size
       end
 
+      def storage_size
+        num_elements * element_type.storage_size
+      end
+
       def empty?
         size == 0
       end
@@ -117,10 +134,20 @@ module Hornetseye
         element_type.typecode
       end
 
+      # Base type of this data type
+      #
+      # @return [Class] Returns +element_type+.
+      #
+      # @private
       def basetype
         element_type.basetype
       end
 
+      # Get type of result of delayed operation
+      #
+      # @return [Class] Type of result.
+      #
+      # @private
       def array_type
         self
       end
@@ -145,6 +172,9 @@ module Hornetseye
         coercion( other ).bool
       end
 
+      # Get corresponding scalar type
+      #
+      # @return [Class] Returns type for array of scalars.
       def scalar
         Hornetseye::Sequence element_type.scalar, num_elements
       end
@@ -153,6 +183,9 @@ module Hornetseye
         Hornetseye::Sequence element_type.float_scalar, num_elements
       end
 
+      # Get corresponding maximum integer type
+      #
+      # @return [Class] Returns type based on maximum integers.
       def maxint
         Hornetseye::Sequence element_type.maxint, num_elements
       end
@@ -169,6 +202,11 @@ module Hornetseye
         coercion( other ).byte
       end
 
+      # Convert to type based on floating point numbers
+      #
+      # @return [Class] Corresponding type based on floating point numbers.
+      #
+      # @private
       def float
         Hornetseye::Sequence element_type.float, num_elements
       end
@@ -213,12 +251,24 @@ module Hornetseye
         end
       end
 
+      # Test equality of classes
+      #
+      # @param [Object] other Object to compare with.
+      #
+      # @return [Boolean] Boolean indicating whether classes are equal.
       def ==( other )
         other.is_a? Class and other < Sequence_ and
           other.element_type == element_type and
           other.num_elements == num_elements
       end
 
+      # Type coercion for native elements
+      #
+      # @param [Class] other Other native datatype to coerce with.
+      #
+      # @return [Class] Result of coercion.
+      #
+      # @private
       def coercion( other )
         if other < Sequence_
           Hornetseye::Sequence element_type.coercion( other.element_type ),
@@ -229,6 +279,13 @@ module Hornetseye
         end
       end
 
+      # Compute balanced type for binary operation
+      #
+      # @param [Class] other Other type to coerce with.
+      #
+      # @return [Array<Class>] Result of coercion.
+      #
+      # @private
       def coerce( other )
         if other < Sequence_
           return other, self
@@ -237,8 +294,8 @@ module Hornetseye
         end
       end
 
-      def new
-        MultiArray.new typecode, *shape
+      def new( memory = nil )
+        MultiArray.new typecode, *shape, :memory => memory
       end
 
       def compilable?
@@ -256,8 +313,8 @@ module Hornetseye
 
       # Method for matching elements of type Sequence_
       #
-      # 'param [Array<Object>] *values Values to find matching native element
-      # type for.
+      # @param [Array<Object>] *values Values to find matching native element
+      #        type for.
       #
       # @return [Class] Native type fitting all values.
       #
@@ -278,6 +335,14 @@ module Hornetseye
         end
       end
 
+      # Perform type alignment
+      #
+      # Align this type to another. This is used to prefer single-precision
+      # floating point in certain cases.
+      #
+      # @param [Class] context Other type to align with.
+      #
+      # @private
       def align( context )
         if self < Sequence_
           Hornetseye::Sequence element_type.align( context ), num_elements