ruby-vips8 0.1.0

data/lib/vips8/access.rb

@@ -0,0 +1,14 @@
+module Vips
+    # The type of access an operation has to supply. 
+    # 
+    # *   `:random` means requests can come in any order. 
+    # 
+    # *   `:sequential` means requests will be top-to-bottom, but with some
+    #     amount of buffering behind the read point for small non-local
+    #     accesses. 
+    #
+    # *   `:sequential_unbuffered` means requests will be strictly
+    #     top-to-bottom with no read-behind. This can save some memory.
+    class Access
+    end
+end

data/lib/vips8/align.rb

@@ -0,0 +1,11 @@
+module Vips
+
+    # Various types of alignment. See {Vips::Image.join}, for example.
+    #
+    # * `:low` Align on the low coordinate edge
+    # * `:centre` Align on the centre
+    # * `:high` Align on the high coordinate edge
+
+    class Align
+    end
+end

data/lib/vips8/angle.rb

@@ -0,0 +1,12 @@
+module Vips
+
+    # Various fixed 90 degree rotation angles. See {Vips::Image.rot}.
+    #
+    # * `:d0` no rotate
+    # * `:d90` 90 degrees clockwise
+    # * `:d180` 180 degrees 
+    # * `:d270` 90 degrees anti-clockwise
+
+    class Angle
+    end
+end

data/lib/vips8/angle45.rb

@@ -0,0 +1,16 @@
+module Vips
+
+    # Various fixed 45 degree rotation angles. See {Vips::Image.rot45}.
+    #
+    # * `:d0` no rotate
+    # * `:d45` 45 degrees clockwise 
+    # * `:d90` 90 degrees clockwise
+    # * `:d135` 135 degrees clockwise
+    # * `:d180` 180 degrees 
+    # * `:d225` 135 degrees anti-clockwise
+    # * `:d270` 90 degrees anti-clockwise
+    # * `:d315` 45 degrees anti-clockwise
+
+    class Angle45
+    end
+end

data/lib/vips8/argument.rb

@@ -0,0 +1,163 @@
+
+module Vips
+
+    # This class is used internally to convert Ruby values to arguments to 
+    # libvips operations. 
+    # @private
+    class Argument 
+        attr_reader :op, :name, :flags, :priority, :isset, :prop
+        attr_reader :blurb, :gtype, :type
+
+        # map gobject-introspection's ruby class names to ours
+        @@map_goi_to_vips = {
+            "TrueClass" => "Boolean",
+            "Vips::ArrayDouble" => "Array<Double>",
+            "Vips::ArrayInt" => "Array<Integer>",
+            "Vips::ArrayImage" => "Array<Image>",
+            "Vips::ArrayString" => "Array<String>",
+        }
+
+        def initialize(op, name)
+            @op = op
+            @name = name.tr '-', '_'
+            @prop = op.gtype.to_class.property name
+            @blurb = @prop.blurb
+            @gtype = prop.value_type
+            @flags = op.get_argument_flags name
+            @priority = op.get_argument_priority @name
+            @isset = op.argument_isset @name
+
+            type = GLib::Type[gtype.name].to_class.name
+            type = @@map_goi_to_vips[type] if @@map_goi_to_vips.include? type
+            @type = type
+        end
+
+        private
+
+        def self.imageize match_image, value
+            return value if match_image == nil
+            return value if value.is_a? Vips::Image
+
+            # 2D array values become tiny 2D images
+            if value.is_a? Array and value[0].is_a? Array
+                return Vips::Image.new_from_array value
+            end
+
+            # if there's nothing to match to, we also make a 2D image
+            if match_image == nil
+                return Vips::Image.new_from_array value
+            end
+
+            # we have a 1D array ... use that as a pixel constant and expand 
+            # to match match_image
+            pixel = (Vips::Image.black(1, 1) + value).cast(match_image.format)
+            pixel = pixel.copy :interpretation => match_image.interpretation,
+                :xres => match_image.xres, :yres =>  match_image.yres
+            pixel.embed(0, 0, match_image.width, match_image.height, 
+                        :extend => :copy)
+        end
+
+        # @private
+        class ArrayImageConst < Vips::ArrayImage 
+            def self.new(value)
+                if not value.is_a? Array
+                    value = [value]
+                end
+
+                match_image = value.find {|x| x.is_a? Vips::Image}
+                if match_image == nil
+                    raise Vips::Error, 
+                        "Argument must contain at least one image."
+                end
+
+                value = value.map {|x| Argument::imageize match_image, x}
+
+                # we'd like to just 
+                #   super(value)
+                # to construct, but the gobject-introspection gem does not
+                # support new from object array ... instead, we build in stages
+                array = Vips::ArrayImage.empty
+                value.each {|x| array = array.append(x)}
+
+                return array
+            end
+        end
+
+        # if this gtype needs an array, try to transform the value into one
+        def self.arrayize(gtype, value)
+            arrayize_map = {
+                GLib::Type["VipsArrayDouble"] => Vips::ArrayDouble,
+                GLib::Type["VipsArrayInt"] => Vips::ArrayInt,
+                GLib::Type["VipsArrayImage"] => ArrayImageConst
+            }
+
+            if arrayize_map.has_key? gtype
+                if not value.is_a? Array
+                    value = [value]
+                end
+
+                value = arrayize_map[gtype].new(value)
+            end
+
+            value
+        end
+
+        def self.unwrap value
+            [Vips::Blob, Vips::ArrayDouble, Vips::ArrayImage, 
+                Vips::ArrayInt, Vips::RefString].each do |cls|
+                if value.is_a? cls
+                    value, length = value.get
+
+                    # blobs come from gobject-introspection as arrays ... 
+                    # repack as strings for convenience
+                    if value and cls == Vips::Blob
+                        value = value.pack("C*")
+                    end
+
+                end
+
+            end
+
+            value
+        end
+
+        public
+
+        def set_value(match_image, value)
+            # array-ize
+            value = Argument::arrayize gtype, value
+
+            # blob-ize
+            if gtype.type_is_a? GLib::Type["VipsBlob"]
+                if not value.is_a? Vips::Blob
+                    value = Vips::Blob.copy value
+                end
+            end
+
+            # image-ize
+            if gtype.type_is_a? GLib::Type["VipsImage"]
+                if not value.is_a? Vips::Image
+                    value = Argument::imageize match_image, value
+                end
+            end
+
+            # MODIFY input images need to be copied before assigning them
+            if (flags & :modify) != 0
+                # don't use .copy(): we want to make a new pipeline with no
+                # reference back to the old stuff ... this way we can free the
+                # previous image earlier 
+                new_image = Vips::Image.memory
+                value.write new_image
+                value = new_image
+            end
+
+            op.set_property @name, value
+        end
+
+        def get_value
+            Argument::unwrap @op.get_property(@name)
+        end
+
+    end
+
+end

data/lib/vips8/bandformat.rb

@@ -0,0 +1,20 @@
+module Vips
+
+    # The format used for each band element. Each corresponds to a native C type
+    # for the current machine.
+    #
+    # * `:notset` invalid setting
+    # * `:uchar` unsigned char format
+    # * `:char` char format
+    # * `:ushort` unsigned short format
+    # * `:short` short format
+    # * `:uint` unsigned int format
+    # * `:int` int format
+    # * `:float` float format
+    # * `:complex` complex (two floats) format
+    # * `:double` double float format
+    # * `:dpcomplex` double complex (two double) format
+    class BandFormat
+    end
+
+end

data/lib/vips8/call.rb

@@ -0,0 +1,302 @@
+module Vips
+
+    # call a vips operation ... this will crash if there's a GC during the call,
+    # I've really no idea why :-(
+    #
+    # Workaround: don't call this directly, use call_base (see below) instead.
+    # This will disable the GC, call this operation, then reenable it. 
+
+    private
+    def self.call_base_nogc(name, instance, option_string, supplied_values)
+        log "in Vips::call_base"
+        log "name = #{name}"
+        log "instance = #{instance}"
+        log "option_string = #{option_string}"
+        log "supplied_values are:"
+        supplied_values.each {|x| log "   #{x}"}
+
+        if supplied_values.last.is_a? Hash
+            optional_values = supplied_values.last
+            supplied_values.delete_at -1
+        else
+            optional_values = {}
+        end
+
+        begin
+            op = Vips::Operation.new name
+        rescue
+            raise Vips::Error, "no operator '#{name}'"
+        end
+
+        # set string options first 
+        log "setting string options ..."
+        if option_string
+            if op.set_from_string(option_string) != 0
+                raise Error
+            end
+        end
+
+        all_args = op.get_args
+
+        # the instance, if supplied, must be a vips image ... we use it for
+        # match_image, below
+        if instance and not instance.is_a? Vips::Image
+            raise Vips::Error, "@instance is not a Vips::Image."
+        end
+
+        # if the op needs images but the user supplies constants, we expand
+        # them to match the first input image argument ... find the first
+        # image
+        log "searching for first image argument ..."
+        match_image = instance
+        if match_image == nil
+            match_image = supplied_values.find {|x| x.is_a? Vips::Image}
+        end
+        if match_image == nil
+            match = optional_values.find do |name, value|
+                value.is_a? Vips::Image
+            end
+            # if we found a match, it'll be [name, value]
+            if match
+                match_image = match[1]
+            end
+        end
+
+        # find unassigned required input args
+        log "finding unassigned required input arguments ..."
+        required_input = all_args.select do |arg|
+            not arg.isset and
+            (arg.flags & :input) != 0 and
+            (arg.flags & :required) != 0 
+        end
+
+        # do we have a non-nil instance? set the first image arg with this
+        if instance != nil
+            log "setting first image arg with instance ..."
+            x = required_input.find do |arg|
+                gtype = GLib::Type["VipsImage"]
+                vtype = arg.prop.value_type
+
+                vtype.type_is_a? gtype
+            end
+            if x == nil
+                raise Vips::Error, 
+                    "No #{instance.class} argument to #{name}."
+            end
+            x.set_value match_image, instance
+            required_input.delete x
+        end
+
+        if required_input.length != supplied_values.length
+            raise Vips::Error, 
+                "Wrong number of arguments. '#{name}' requires " +
+                "#{required_input.length} arguments, you supplied " +
+                "#{supplied_values.length}."
+        end
+
+        log "setting required input arguments ..."
+        required_input.zip(supplied_values).each do |arg, value|
+            arg.set_value match_image, value
+        end
+
+        # find optional unassigned input args
+        log "finding optional unassigned input arguments ..."
+        optional_input = all_args.select do |arg|
+            not arg.isset and
+            (arg.flags & :input) != 0 and
+            (arg.flags & :required) == 0 
+        end
+
+        # make a hash from name to arg
+        optional_input = Hash[
+            optional_input.map(&:name).zip(optional_input)]
+
+        # find optional unassigned output args
+        log "finding optional unassigned output arguments ..."
+        optional_output = all_args.select do |arg|
+            not arg.isset and
+            (arg.flags & :output) != 0 and
+            (arg.flags & :required) == 0 
+        end
+        optional_output = Hash[
+            optional_output.map(&:name).zip(optional_output)]
+
+        # set all optional args
+        log "setting optional values ..."
+        optional_values.each do |name, value|
+            # we are passed symbols as keys
+            name = name.to_s
+            if optional_input.has_key? name
+                log "setting #{name} to #{value}"
+                optional_input[name].set_value match_image, value
+            elsif optional_output.has_key? name and value != true
+                raise Vips::Error, 
+                    "Optional output argument #{name} must be true."
+            elsif not optional_output.has_key? name 
+                raise Vips::Error, "No such option '#{name}',"
+            end
+        end
+
+        log "building ..."
+
+        op2 = Vips::cache_operation_lookup op
+        if op2
+            log "cache hit"
+            op = op2
+
+            all_args = op.get_args
+
+            # find optional output args
+            optional_output = all_args.select do |arg|
+                (arg.flags & :output) != 0 and
+                (arg.flags & :required) == 0 
+            end
+            optional_output = Hash[
+                optional_output.map(&:name).zip(optional_output)]
+        else
+            log "cache miss ... building"
+            if not op.build
+                raise Vips::Error
+            end
+            showall
+
+            log "adding to cache ... "
+            Vips::cache_operation_add op
+        end
+
+        log "fetching outputs ..."
+
+        # gather output args 
+        out = []
+
+        all_args.each do |arg|
+            # required output
+            if (arg.flags & :output) != 0 and
+                (arg.flags & :required) != 0 
+                log "fetching required output #{arg.name}"
+                out << arg.get_value
+            end
+
+            # modified input arg ... this will get the result of the 
+            # copy() we did in Argument.set_value above
+            if (arg.flags & :input) != 0 and
+                (arg.flags & :modify) != 0 
+                log "fetching modified input arg ..."
+                out << arg.get_value
+            end
+        end
+
+        opts = {}
+        optional_values.each do |name, value|
+            # we are passed symbols as keys
+            name = name.to_s
+            if optional_output.has_key? name
+                log "fetching optional output arg ..."
+                opts[name] = optional_output[name].get_value
+            end
+        end
+        out << opts if opts != {}
+
+        if out.length == 1
+            out = out[0]
+        elsif out.length == 0
+            out = nil
+        end
+
+        log "unreffing outputs ..."
+        op.unref_outputs
+        op = nil
+        # showall
+
+        log "success! #{name}.out = #{out}"
+
+        return out
+    end
+
+    # run call_base_nogc, with the GC disabled
+    private
+    def self.call_base(name, instance, option_string, supplied_values)
+        gc_was_enabled = GC.disable
+        begin
+            result = call_base_nogc name, instance, 
+                option_string, supplied_values
+        ensure
+            GC.enable if gc_was_enabled
+        end
+
+        return result
+    end
+
+    public
+
+    # This is the public entry point for the vips8 binding. {call} will run
+    # any vips operation, for example:
+    #
+    # ```ruby
+    # out = Vips::call "black", 100, 100, :bands => 12
+    # ```
+    #
+    # will call the C function 
+    #
+    # ```C
+    # vips_black( &out, 100, 100, "bands", 12, NULL );
+    # ```
+    # 
+    # There are {Image#method_missing} hooks which will run {call} for you 
+    # on {Image} for undefined instance or class methods. So you can also 
+    # write:
+    #
+    # ```ruby
+    # out = Vips::Image.black 100, 100, :bands => 12
+    # ```
+    #
+    # Or perhaps:
+    #
+    # ```ruby
+    # x = Vips::Image.black 100, 100
+    # y = x.invert
+    # ```
+    #
+    # to run the `vips_invert()` operator.
+    #
+    # There are also a set of operator overloads and some convenience functions,
+    # see {Image}. 
+    #
+    # If the operator needs a vector constant, {call} will turn a scalar into a
+    # vector for you. So for `x.linear(a, b)`, which calculates 
+    # `x * a + b` where `a` and `b` are vector constants, you can write:
+    #
+    # ```ruby
+    # x = Vips::Image.black 100, 100, :bands => 3
+    # y = x.linear(1, 2)
+    # y = x.linear([1], 4)
+    # y = x.linear([1, 2, 3], 4)
+    # ```
+    #
+    # or any other combination. The operator overloads use this facility to
+    # support all the variations on:
+    #
+    # ```ruby
+    # x = Vips::Image.black 100, 100, :bands => 3
+    # y = x * 2
+    # y = x + [1,2,3]
+    # y = x % [1]
+    # ```
+    #
+    # Similarly, whereever an image is required, you can use a constant. The
+    # constant will be expanded to an image matching the first input image
+    # argument. For example, you can write:
+    #
+    # ```
+    # x = Vips::Image.black 100, 100, :bands => 3
+    # y = x.bandjoin(255)
+    # ```
+    #
+    # to add an extra band to the image where each pixel in the new band has 
+    # the constant value 255. 
+
+    def self.call(name, *args)
+        Vips::call_base name, nil, "", args
+    end
+
+end