| Class | RS::Graphics::RSImage |
| In: |
rsil/extension/rsimageextension.rb
rsil/graphics/rsimage.rb |
| Parent: | Object |
| Class: | RSImage |
| File: | rsimage.rb |
| Purpose: | RSImage represents an image through wrapping of RubyCocoas OSX::CIImage. You can set and get properties for each image directly without calling the properties object. So you do not have to call ‘image.properties.gamma = 1.0’ (it works nethertheless), you can call ‘image.gaama = 1.0’. When extended with rsimagextension.rb, you can call well known image manipulation methods for the image - consult RSImage#extend_with_filter_functions for detailed information on which methods will be added to RSImage after calling. If you need this functionality right from the beginning, have a look at class RSImageX. |
| Created by: | Mario Pehle, 2006/04/29 |
| Required modules: | - |
| Offers functions: | - |
| filename | [R] | saves the initial path and file name as a String. |
| filters | [R] | saves added filters as an Array. Will be cleared, if filters are applied to the image. |
| properties | [R] | makes the properties of the image accessable as a RSImageProperties object. |
| Description: | Initialize the RSImage either with a String, OSX::NSURL, OSX::CIImage or without an argument. |
| Precondition: | - |
| Postcondition: | @ciimage, @properties, @filename and @filters are set. |
| Exceptions: | ArgumentError |
| Uses: | OSX::CIImage.init, OSX::CIImage, RSImage.read_from_string, RSImageList, RSProperties |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | image | i | nil | String, OSX::NSURL, OSX::CIImage |
# File rsil/graphics/rsimage.rb, line 92
92: def initialize image=nil
93: if image.nil? or (image.kind_of?(Array) and image.empty?)
94: @ciimage = OSX::CIImage.alloc.init
95: @filename = nil
96: elsif image.kind_of?(OSX::CIImage) or image.kind_of?(OSX::OCObject)
97: @ciimage = image
98: @filename = nil
99: else
100: is_string = read_from_string image
101: raise ArgumentError, "Unable to load image '#{image}'" unless is_string
102: end
103: assert "@ciimage not initialized" if @ciimage.nil?
104: @filters = []
105: @properties = RS::Utils::RSImageProperties.new
106: assert "@properties not initialized" if @properties.nil?
107: @delegate = @properties
108: self
109: end
| Description: | Comparison of the image and another image. Compares the amount of Pixels. Mixin Comparable uses this method. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | ArgumentError |
| Uses: | RSImage#pixels |
| Returns: | Fixnum, if set and nil if not set |
| Parameters: | Name | i/o/io | default | Meaning |
| : | other | i | - | The RSImage to compare |
# File rsil/graphics/rsimage.rb, line 547
547: def <=> other
548: if other.kind_of? RSImage
549: return self.pixels <=> other.pixels
550: else
551: raise ArgumentError, "Arguemnt 'other' has to be of type RSImage."
552: end
553: end
| Description: | Adds filters to the image. Also have a look at RSImage#apply_filters. |
| Precondition: | - |
| Postcondition: | @filters is changed. |
| Exceptions: | - |
| Uses: | @filters |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filters | i | - | RSFilter / Array, the filter(s) to add |
# File rsil/graphics/rsimage.rb, line 650
650: def add_filter filters
651: if filters.kind_of? Array
652: filters.each do |f|
653: @filters << f.clone if f.kind_of? RS::Graphics::RSFilter
654: end
655: else
656: @filters << filters.clone if filters.kind_of? RS::Graphics::RSFilter
657: end
658: self
659: end
| Description: | Processes the image with the given filters. If you do not provide an argument, the filters added to this image will process the image. This method will not change the actual image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | ArgumentError |
| Uses: | RSImage#clone, RSImage#apply_filters! |
| Returns: | RSImage if valid argument, else nil |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filters | i | nil | RSFilter / Array of RSFilter, the filters to process the image with |
# File rsil/graphics/rsimage.rb, line 625
625: def apply_filters filters=nil
626: if filters.nil? or filters.kind_of?(Array) or
627: filters.kind_of?(RS::Graphics::RSFilter)
628: ri = self.clone
629: ri.apply_filters! filters
630: return ri
631: else
632: raise ArgumentError, "Can not make use of the argument."
633: end
634: nil
635: end
| Description: | Processes the image with the given filters. If you do not provide an argument, the filters added to this image will process the image. This method will change the actual image. |
| Precondition: | - |
| Postcondition: | @ciimage is changed internally, @filters is cleared when added filters were used. |
| Exceptions: | ArgumentError |
| Uses: | RSFilter, @ciimage |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filters | i | nil | RSFilter / Array of RSFilter, the filters to process the image with |
# File rsil/graphics/rsimage.rb, line 584
584: def apply_filters! filters=nil
585: if filters.nil?
586: @filters.each do |f|
587: if f.respond_to?('inputImage='.to_sym) and f.input_image.nil?
588: f.inputImage = self
589: end
590: @ciimage = f.outputImage if f.respond_to? :outputImage
591: end
592: @filters = []
593: elsif filters.kind_of? Array
594: filters.each do |f|
595: if f.respond_to?('inputImage='.to_sym) and f.input_image.nil?
596: f.inputImage = self
597: end
598: @ciimage = f.outputImage if f.respond_to? :outputImage
599: end
600: elsif filters.kind_of? RS::Graphics::RSFilter
601: if filters.respond_to?('inputImage='.to_sym) and filters.input_image.nil?
602: filters.inputImage = self
603: end
604: @ciimage = filters.outputImage if filters.respond_to?(:outputImage)
605: else
606: raise ArgumentError, "Can not make use of the argument."
607: end
608: assert "@ciimage not reinitialized" if @ciimage.nil?
609: self
610: end
| Description: | Returns the Bytes (of the nsdata) of the image. |
| Precondition: | @ciimage is not nil. |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | - |
| Uses: | RSImage.nsdata |
| Returns: | String |
| Parameters: | Name | i/o/io | default | Meaning |
| : | datatype | o | nil | Fixnum, the type of the data |
# File rsil/graphics/rsimage.rb, line 337
337: def bytes datatype=nil
338: self.bytes_from self.extent, datatype
339: end
| Description: | Create the image from Bytes. |
| Precondition: | - |
| Postcondition: | @ciimage is changed. |
| Exceptions: | ArgumentError |
| Uses: | OSX::NSData, OSX::CIImage.initWithData |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | bytestring | i | (none) | The data representing the bytes of the nsdata of the image. Has to be a String. |
# File rsil/graphics/rsimage.rb, line 354
354: def bytes= bytestring
355: if bytestring.respond_to? :to_str
356: data = OSX::NSData.dataWithRubyString bytestring.to_str
357: assert "data not created" if data.nil?
358: @ciimage = OSX::CIImage.alloc.initWithData data
359: assert "@ciimage not reinitialized" if @ciimage.nil?
360: else
361: raise ArgumentError, "Parameter 'bytestring' has to offer method 'to_str'."
362: end
363: self
364: end
| Description: | Returns the Bytes (of the nsdata) of the image from given rectangle. |
| Precondition: | @ciimage is not nil. |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | - |
| Uses: | RSImage.nsdata |
| Returns: | String |
| Parameters: | Name | i/o/io | default | Meaning |
| : | rect | i | nil | RSRectangle, the area to draw |
| : | datatype | o | nil | Fixnum, the type of the data |
# File rsil/graphics/rsimage.rb, line 318
318: def bytes_from rect, datatype=nil
319: nsdat = self.nsdata_from rect, datatype
320: nsdat_ptr = nsdat.bytes
321: nsdat_ptr.bytestr nsdat.length
322: end
| Description: | Determines the color at the given point of the image. |
| Precondition: | @ciimage is not nil |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | RSImage#get_drawn_rep |
| Returns: | RSColor if valid point, else nil |
| Parameters: | Name | i/o/io | default | Meaning |
| : | point | i | - | RSPoint, the point to get the color from |
# File rsil/graphics/rsimage.rb, line 270
270: def color_at point
271: nscolor = get_drawn_rep(self.extent).colorAtX(point.x, :y, point.y)
272: assert "nscolor not created" if nscolor.nil?
273: return RS::Graphics::RSColor.new(
274: nscolor.redComponent,
275: nscolor.greenComponent,
276: nscolor.blueComponent,
277: nscolor.alphaComponent
278: ) rescue return nil
279: end
| Description: | Determines the width and height of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | @ciimage.getWidth, @ciimage.getHeight |
| Returns: | RSDimension |
| Parameters: | Name | i/o/io | default | Meaning |
| : | (none) |
# File rsil/graphics/rsimage.rb, line 379
379: def dimension
380: RS::Geometry::RSDimension.new @ciimage.getWidth, @ciimage.getHeight
381: end
| Description: | Draws the image with all applied filters at a given position on an image representation with its size in ‘rect’. You can use this method when you want to draw an image with more space around. For instance: Your image is 100x100 px and you want to center it on an image representation with 200x200 px, you call (pseudo code): draw_on 200x200, 50 50. Keep in mind, that the additional space is blank space. The color behind is black. If you save your enlarged image, it will have a black border. So use this method, when you want to place one image onto another with compositing filters. |
| Precondition: | @ciimage is not nil |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | - |
| Uses: | RSImage#draw_rep |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | rect | i | - | RSRectangle, the area to draw |
| : | point | i | - | RSPoint, the point to draw |
# File rsil/graphics/rsimage.rb, line 203
203: def draw_on rect, at_point
204: nsdat = get_drawn_rep(rect, at_point).representationUsingType(
205: RS::Utils::RSImageProperties::FILE_TYPES['png'],
206: :properties, self.properties.objc_object
207: )
208: assert "nsdat not created" if nsdat.nil?
209: nsdat_ptr = nsdat.bytes
210: self.bytes = nsdat_ptr.bytestr(nsdat.length)
211: self
212: end
| Description: | Extents RSImage objects with well known image functions when required to program and called. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | - |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
crop(rectangle)
| Description: | Crops the image to the given rectangle. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | ArgumentError |
| Uses: | - |
| Returns: | RSFilter |
| Parameters: | Name | i/o/io | default | Meaning |
| : | rectangle | i | - | RSRectangle/RSVector, the rectangle for cropping |
gaussian_blur(radius=10.0)
| Description: | Blurs the image with Gaussian algorithm. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | ArgumentError |
| Uses: | - |
| Returns: | RSFilter |
| Parameters: | Name | i/o/io | default | Meaning |
| : | | radius | i | 10.0 | Float, the radius for blurring |
lanczos_scale(scale_factor=0.5)
| Description: | Scales an image with Lanczos filter. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | ArgumentError |
| Uses: | - |
| Returns: | RSFilter |
| Parameters: | Name | i/o/io | default | Meaning |
| : | | scale_factor | i | 0.5 | Float, the scale factor |
negate()
| Description: | Inverts/negates the colors of the image |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | - |
| Returns: | RSFilter |
| Parameters: | Name | i/o/io | default | Meaning |
sepiatone()
| Description: | Converts the image to a sepia tone image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | - |
| Returns: | RSFilter |
| Parameters: | Name | i/o/io | default | Meaning |
# File rsil/extension/rsimageextension.rb, line 97
97: def extend_with_filter_functions
98: available_filters = RS::Graphics::RSFilter.installed_filters
99: eval_codes = []
100:
101:
102: eval_codes << "def crop rectangle\nunless rectangle.kind_of?(RS::Geometry::RSRectangle) or\nrectangle.kind_of?(RS::Geometry::RSVector)\nraise ArgumentError, \"No valid rectangle given.\"\nend\nfilter = RS::Graphics::RSFilter.new('CICrop', true)\nif rectangle.kind_of? RS::Geometry::RSVector\nfilter.inputRectangle = rectangle\nelse\nfilter.inputRectangle = RS::Geometry::RSVector.new(\nrectangle.x,\nrectangle.y,\nrectangle.width,\nrectangle.height\n)\nend\nself.add_filter filter\nfilter\nend\n" if available_filters.include?('CICrop')
103:
104:
105: eval_codes << "def gaussian_blur radius=10.0\nr = Float radius rescue raise ArgumentError, 'Argument has to be a float.'\nraise ArgumentError, 'Argument has to be a positive float.' if r < 0.0\nfilter = RS::Graphics::RSFilter.new('CIGaussianBlur', true)\nfilter.inputRadius = r\nself.add_filter filter\nfilter\nend\n" if available_filters.include?('CIGaussianBlur')
106:
107:
108: eval_codes << "def lanczos_scale scale_factor=0.5\nf = Float scale_facot rescue raise ArgumentError, 'Argument has to be a float.'\nraise ArgumentError, 'Argument has to be a positive float.' if f < 0.0\nfilter = RS::Graphics::RSFilter.new('CILanczosScaleTransform', true)\nfilter.inputScale = f\nself.add_filter filter\nfilter\nend\n" if available_filters.include?('CILanczosScaleTransform')
109:
110:
111: eval_codes << "def negate\nfilter = RS::Graphics::RSFilter.new('CIColorInvert', true)\nself.add_filter filter\nfilter\nend\n" if available_filters.include?('CIColorInvert')
112:
113:
114: eval_codes << "def sepiatone\nfilter = RS::Graphics::RSFilter.new('CISepiaTone', true)\nself.add_filter filter\nfilter\nend\n" if available_filters.include?('CISepiaTone')
115:
116:
117: eval_codes.each { |code| instance_eval code }
118: self
119: end
| Description: | Determines the extent (x, y, width, height) of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | @ciimage.getX, @ciimage.getY, @ciimage.getWidth, @ciimage.getHeight, RSRectangle.new |
| Returns: | RSRectangle |
| Parameters: | Name | i/o/io | default | Meaning |
| : | (none) |
# File rsil/graphics/rsimage.rb, line 413
413: def extent
414: RS::Geometry::RSRectangle.new(
415: @ciimage.getX, @ciimage.getY, nil,
416: @ciimage.getWidth, @ciimage.getHeight, nil
417: )
418: end
| Description: | Determines the height of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | OSX::CIImage.getHeight |
| Returns: | Float |
| Parameters: | Name | i/o/io | default | Meaning |
| : | (none) |
# File rsil/graphics/rsimage.rb, line 484
484: def height
485: @ciimage.getHeight
486: end
| Description: | Loads data from filesystem with a String, OSX::NSURL, OSX::CIImage or without a parameter. |
| Precondition: | - |
| Postcondition: | @ciimage is changed. |
| Exceptions: | ArgumentError |
| Uses: | RSImage.read_from_string |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filename | i | - | String, OSX::NSURL |
# File rsil/graphics/rsimage.rb, line 124
124: def load filename
125: is_string = read_from_string(filename)
126: raise ArgumentError, "Unable to load #{filename}." unless is_string
127: self
128: end
| Description: | Returns the OSX::NSData of the image. Method acts as a virtual attribute. You specify the format (gif, jpge etc.) via the types parameter. If you do not specify, nsdata with bmp format will be returned. |
| Precondition: | @ciimage is not nil. |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | ArgumentError |
| Uses: | RSImage#get_drawn_rep, RSImageProperties#FILTE_TYPES |
| Returns: | OSX::NSData |
| Parameters: | Name | i/o/io | default | Meaning |
| : | datatype | i | nil | Fixnum, the type of the data |
# File rsil/graphics/rsimage.rb, line 253
253: def nsdata datatype=nil
254: self.nsdata_from self.extent, datatype
255: end
| Description: | Create the image from OSX::NSData. Method acts as a virtual attribute. Be aware that not every NSData represents an image, it can be anything else. |
| Precondition: | - |
| Postcondition: | @ciimage is changed. |
| Exceptions: | - |
| Uses: | OSX::CIImage.initWithData |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | ns_data | i | (none) | The data representing the nsdata of the image. |
# File rsil/graphics/rsimage.rb, line 294
294: def nsdata= ns_data
295: if ns_data.kind_of? OSX::OCObject
296: @ciimage = OSX::CIImage.alloc.initWithData ns_data
297: assert "@ciimage not reinitialized" if @ciimage.nil?
298: else
299: raise "Parameter 'ns_data' has to be of type 'OSX::NSData'."
300: end
301: self
302: end
| Description: | Returns the OSX::NSData of the image from given rectangle. You specify the format (gif, jpge etc.) via the types parameter. If you do not specify, nsdata with bmp format will be returned. |
| Precondition: | @ciimage is not nil. |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | ArgumentError |
| Uses: | RSImage#get_drawn_rep, RSImageProperties#FILTE_TYPES |
| Returns: | OSX::NSData |
| Parameters: | Name | i/o/io | default | Meaning |
| : | point | i | nil | RSPoint, the point from where to draw |
| : | rect | i | nil | RSRectangle, the area to draw |
| : | datatype | i | nil | Fixnum, the type of the data |
# File rsil/graphics/rsimage.rb, line 229
229: def nsdata_from rect, datatype=nil
230: dattype = datatype.nil? ? RS::Utils::RSImageProperties::FILE_TYPES[:BMP] : datatype
231: unless rect.kind_of?(RS::Geometry::RSRectangle)
232: raise ArgumentError, "Argument 'rect' has to be a RSRectangle."
233: end
234: return get_drawn_rep(rect).representationUsingType(
235: dattype,
236: :properties, self.properties.objc_object
237: )
238: end
| Description: | Gives access to the basic Core Image object of this object, a OSX::CIImage. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | - |
| Returns: | OSX::CIImage / OSX::OCObject |
| Parameters: | Name | i/o/io | default | Meaning |
# File rsil/graphics/rsimage.rb, line 567
567: def objc_object
568: @ciimage
569: end
| Description: | Determines the amount of pixels of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | OSX::CIImage.getWidth, OSX::CIImage.getHeight |
| Returns: | Float |
| Parameters: | Name | i/o/io | default | Meaning |
# File rsil/graphics/rsimage.rb, line 500
500: def pixels
501: @ciimage.getHeight * @ciimage.getHeight
502: end
| Description: | Determines the point of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | @ciimage.getX, @ciimage.getY |
| Returns: | RSPoint |
| Parameters: | Name | i/o/io | default | Meaning |
| : | (none) |
# File rsil/graphics/rsimage.rb, line 396
396: def point
397: RS::Geometry::RSPoint.new @ciimage.getX, @ciimage.getY
398: end
| Description: | Removes filter(s) from image. Filter only can be removed if not yet applied via RSImage#apply_filters. Removes each filter same as filters. That means, doubletts are fully removed. |
| Precondition: | - |
| Postcondition: | @filters is changed. |
| Exceptions: | - |
| Uses: | @filters |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filters | i | - | Array / RSFilter, the filters to remove |
# File rsil/graphics/rsimage.rb, line 674
674: def remove_filters! filters=nil
675: if filters.nil?
676: @filters = []
677: elsif filters.kind_of? Array
678: filters.each { |f| @filters.delete f }
679: elsif filters.kind_of? RS::Graphics::RSFilter
680: @filters.delete filters
681: end
682: self
683: end
| Description: | Writes the (bytes of the OSX::NSData of the) image into a file. The data type will be determined from the filename. If you specify a type, this type will be used. If no type is specified (not in filename or type), writes a BMP bitmap. |
| Precondition: | @ciimage is not nil |
| Postcondition: | @ciimage is changed internally. |
| Exceptions: | ArgumentError |
| Uses: | RSImage#bytes, RSImageProperties |
| Returns: | self |
| Parameters: | Name | i/o/io | default | Meaning |
| : | filename | o | - | String, the filename |
| : | type | o | - | Fixnum, the type of the image data |
# File rsil/graphics/rsimage.rb, line 518
518: def save filename, type=nil
519: raise ArgumentError, "No value for attribute 'filename' given." if filename.to_s.empty?
520: t = nil
521: if type.nil?
522: parts = filename.to_s.split('.')
523: suffix = parts.last if parts.length > 1
524: t = RS::Utils::RSImageProperties::FILE_TYPES[suffix] unless suffix.nil?
525: else
526: t = type
527: end
528: b = self.bytes t
529: assert "bytes not determined" if b.nil?
530: File.open(filename, "w") { |file| file.write(b) }
531: self
532: end
| Description: | Determines the width of the image. |
| Precondition: | - |
| Postcondition: | - |
| Exceptions: | - |
| Uses: | OSX::CIImage.getWidth |
| Returns: | Float |
| Parameters: | Name | i/o/io | default | Meaning |
| : | (none) |
# File rsil/graphics/rsimage.rb, line 467
467: def width
468: @ciimage.getWidth
469: end