SCImage:
Filter:
Classes | GUI > Views

SCImage

image component
Location: NOT INSTALLED!

Description

SCImage is an image component for the macOS SuperCollider client. SCImage is currently a wrapper around different models : you can use it for bitmap operations, image embedding for custom UI and for more advanced image processing as applying filters and kernels, both provided with the CoreImage framework.

SCImage currently supports most formats including tiff, bmp, gif, jpeg, png, tga...ect.. for reading. But for for writing it supports only those in SCImage.formats.

NOTE: GUI Issue : since it is macOS only, be sure to call GUI.cocoa before any SCImage.call

Class Methods

.new

Creates a new SCImage instance. multiple stands here for multiple arguments.

Arguments:

multiple

May be a...

  • Number to create an empty image of size multiple as width and height

  • Point to create an empty image of size multiple.x as width and multiple.y as height

  • String to create an image from a local file or from an URL (http://, ftp://, file:///)

.color

Creates a new SCImage instance filled with the specified color.

Arguments:

args

multiple arguments. the last argument should be a valid Color

.open

Creates a new SCImage instance from the local file at path.

.openURL

Creates a new SCImage instance from a valid image at the specified URL path.

.fromImage

Creates a new SCImage instance from another SCImage.

.fromWindow

Creates a new SCImage from a portion of a SCWindow. this can be used to capture either a window or a specific SCView.

Arguments:

window

the SCWindow object.

rect

optional. the constrained rect to capture inside the SCWindow. By default, it is the window size.

Class variables and attributes

.formats

returns all the valid image formats as an Array

.compositingOperations

returns all the valid compositing operations you can use when drawing an SCImage as an Array

.interpolations

returns an Array of the different levels of interpolation you can specify when drawing an SCImage.

.closeAllPlotWindows

close all the SCImage plot windows currently opened.

Inherited class methods

Instance Methods

commons / general attributes

.width

returns or set the width of the receiver

.height

returns or set the height of the receiver

.setSize

set the size of the receiver

.bounds

returns the bounds of the receiver.

.free

deallocate the receiver. this method is useful if you want to manage and reclaim yourself resources. otherwise you do not need to call this method since each object is automatically garbage collected.

.scalesWhenResized

flag to tell or set if the receiver should update its bitmap representation to scale when a resize operation if performed

.url

returns or set the url of the receiver. Returning only if any where supplied at creation, otherwise returns nil. Setting may be used for different purpose but try to supply a valid one since it is used for archiving the image as an object.

.accelerated

if true, the receiver currently use the CoreImage model, possibly caching its data on GPU, if not the bitmap model. Set it to switch representation.

WARNING: this method should never be used directly unless you know perfectly what you are doing. Since the SCImage will switch internally and manage itself the syncronization between representations.

.interpolation

get or set the level of interpolation used when rendering the image - it has not effect when the SCImage is accelerated. see *interpolations for a valid range of values.

saving and archiving

.write

write the SCImage to a file.

Arguments:

path

the location where to save it

format

(optional) format to use. see SCImage.formats for supported formats. If nil, it will get the format depending on the path extension.

rendering

.plot

plots the image in a SCWindow.

Arguments:

name

the title of the SCWindow. may be nil.

bounds

the bounds of the SCWindow. may be nil.

freeOnClose

flag to tell if the SCWindow should free the SCImage when closed.

background

additional background to apply to the SCWindow. may be useful for artifacts due to alpha / compositing...

showInfo

shows pixel coordinates while the mouse is over the image's plot window.

.lockFocus

sets the receiver as the current graphic context. So you can use SCPen to draw inside of it.

.unlockFocus

restore the graphic context state. the receiver is not anymore the current graphic context.

.draw

shortcut for drawing inside an image. equivalent to :

.drawStringAtPoint

renders *correctly* a String inside an SCImage :) // to fix to have a compliant interface

.drawAtPoint

render the image or a portion of it in the current graphic context.

Arguments:

point

the Point where to draw it

fromRect

the portion of the SCImage to use

operation

the compositing operation to use. 'sourceOver' is the default.

fraction

the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)

.drawInRect

render the image or a portion of it in a specified rectangle of the current graphic context. This may stretch the image depending on the destination rect.

Arguments:

rect

the Rect where to draw it

fromRect

the portion of the SCImage to use

operation

the compositing operation to use. 'sourceOver' is the default.

fraction

the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)

.tileInRect

tile the image or a portion of it in a specified rectangle of the current graphic context. This may stretch the image depending on the destination rect.

Arguments:

rect

the Rect where to draw it

fromRect

the portion of the SCImage to use

operation

the compositing operation to use. 'sourceOver' is the default.

NOTE: Compositing operations are currently disabled for tileInRect
fraction

the opacity to use, ranging from 0.0 (fully transparent) to 1.0 (fully opaque)

Instance Methods / accessing and setting pixels

.setPixel

fill a pixel located at x @ y.

Arguments:

rgbaInteger

an 32 bit Integer containing color information packed as 8bit RGBA

.getPixel

retrieve the pixel value at x @ y as a RGBA integer

.setColor

fill the pixel located at x @ y with the specified color.

.getColor

retrieve the pixel value at x @ y as a Color.

.pixels

retrieve or set all the pixels of the receiver.

NOTE: Carefull: the returned Array is a Int32Array of size receiver.width * receiver.height containing all pixel values as 32bit Integer

Arguments:

array

an Int32Array of size receiver.width * receiver.height containing all pixel values as 32bit Integer

.loadPixels

load all the pixels of the receiver in an array. it is better and faster to call this function instead of -pixels if you plan to retrieve frequently the pixel data (since it won't allocate a new array everytime !)

Arguments:

array

the array that will be filled. Should be an Int32Array of size receiver.width * receiver.height.

region

the targeted rectangular region. (nil by default, meaning full size)

start

the start index of the array.

.setPixels

set the pixels in a specific portion of the receiver.

Arguments:

array

an Int32Array of size rect.width * rect.height containing all pixel values as 32bit Integer

rect

a rectangle defining the portion to update in the receiver. By default rect is nil, meaning full image size.

start

the array start index.

Instance Methods / Attributes for SCImageFilter support

see SCImageFilter for more info

.applyFilters

apply an array of SCImageFilter to the image. this should be considered as an in place operation, meaning the SCImage is altered after it.

Arguments:

filters

a SCImageFilter or an array of SCImageFilter to be applied

crop

the crop region to finally use. This may be required for extending bounds since some SCImageFilter / CoreImageFilters require to set a wider region (to be applied correctly) or may create a huge image. Setting crop to nil sets no crop region. In case the current maximum size of a filtered SCImage is 4096 / 4096. Any larger size will be clipped. by default crop is constrained to the receiver bounds.

region

option to constrain the filter to a specific region IN the SCImage.

.filteredWith

returns a new SCImage, copy of the receiver filtered with an array of SCImageFilter. arguments are the same as -applyFilters (except for region).

NOTE: Beware: you are responsible for freeing the newly created SCImage !!!

.filters

filters is the instance variable that holds the array of SCImageFilter attached to the receiver. This is a convenient for applying filters out place and changing the SCImageFilter's attributes. see -addFilter, -removeFilter

see SCImageFilter for an example on how to use the filters array.

.addFilter

you can also attach filters to the receiver for real-time changing operations. In this case the receiver will create a cache before each rendering to maintain his previous state, and allowing you to use filters without applying them in place. The cache is managed directly by the receiver. you can add several filters to the receiver, the first filter in the array is the first applied in the rendering chain.

see SCImageFilter for an example on how to use addFilter.

Arguments:

filter

a SCImageFilter to apply before rendering of the image

.removeFilter

see SCImageFilter for an example on how to use removeFilter.

Arguments:

filter

the SCImageFilter to remove from the rendering chain.

.flatten

if -filters is not zero sized, this method will apply all those filters in place. if the image is accelerated this method force a bitmap representation of the receiver.

.invert

invert the receiver

.crop

crop the receiver

Arguments:

aRect

the cropping region

Instance Methods / Attributes for SCImageKernel support

see SCImageKernel for examples and more info.

.applyKernel

apply a Kernel in place. the receiver is modified after this call.

Arguments:

kernel

a SCImageKernel

Inherited instance methods

Examples

Views addition

you can now use a SCImage as a valid view background. 16 drawing modes are defined to behave differently.

tileMode values:
1fixed to left, fixed to top
2horizontally tile, fixed to top
3fixed to right, fixed to top
4fixed to left, vertically tile
5horizontally tile, vertically tile
6fixed to right, vertically tile
7fixed to left, fixed to bottom
8horizontally tile, fixed to bottom
9fixed to right, fixed to bottom
10fit
11center, center (scale)
12center , fixed to top
13center , fixed to bottom
14fixed to left, center
15fixed to right, center
16center, center (no scale)
SCView:backgroundImage_
image - the SCImage to use

tileMode - the mode to use. by default fixed to left, fixed to top

alpha - opacity 0 < x < 1

fromRect - the portion of the image to use. by default use the full image.