The image filter chain object is an object that wraps a list of CoreImage filters to create a filter chain. The filter chain can be as simple as a single filter, to complex multi branch filter chains. For a view of what a [moderately complex filter chain looks like with a filter graph see the filter chain and diagram in the rendering image filter chain documentation](RenderingImageFilterChains#chaining-filters-together).
### Getting the available CoreImage filters
To get a list of all the available CoreImage filters:
[Apple documentation describing all the Core Image filters](https://developer.apple.com/library/mac/documentation/graphicsimaging/reference/CoreImageFilterReference/Reference/reference.html).
To get the list of filters that belong to particular category:
All the filters belong to more than one category. The list of categories, [from Apple's documentation are](https://developer.apple.com/library/mac/documentation/GraphicsImaging/Conceptual/CoreImaging/ci_concepts/ci_concepts.html):
CICategoryBlur
CICategoryColorAdjustment
CICategoryCompositeOperation
CICategoryDistortionEffect
CICategoryGenerator
CICategoryGeometryAdjustment
CICategoryGradient
CICategoryHalftoneEffect
CICategorySharpen
CICategoryStylyize
CICategoryTileEffect
CICategoryTransition
### Creating an image filter chain json object/plist dictionary
The chaining filters together is achieved by making the output image of a filter earlier in the filter chain an input image to a later filter. When the "imagefilterchain" object receives the render filter chain message the object renders the output image of the last filter in the filter list to the render destination.
Image filter chain objects are of type "imagefilterchain".
#### Creating and closing a image filter chain object
To create a image filter chain object you need to supply a image filter chain representation in the form of a json object or a plist dictionary. If the filter chain representation is in the form of a json object it can be supplied either as a string on the command or a path to a file containing the json content. If the representation is a plist dictionary then the content is accessed with a path to a file with the property list content.
To create a image filter chain object you need to supply a image filter chain representation in the form of a json object or a plist dictionary. If the filter chain representation is in the form of a json object it can be supplied either as a string on the command line or a path to a file containing the json content. If the representation is a plist dictionary then the content is accessed with a path to a file with the property list content.
The property keys used to define the json object or plist dictionary used to create a image filter chain object:
...
...
@@ -17,59 +44,169 @@ The top level json object takes two properties, both of which are required:
cifilterlist
cirenderdestination
#### The render destination
The render destination key takes a json object that describes how to obtain the render destination object. The render destination object requires either the object reference property or the object type property plus object name property.
{
"objectreference": 3
}
or
The object with an object reference of 3 will be the render destination. Alternatively the render destination could be defined by object type and name:
The filter list key takes an array of filter json objects, each filter json object takes three keys:
#### The filter list
The filter list key takes an array of filter json objects, each filter json object takes the following properties:
cifiltername
cifilterproperties
mifiltername
#### The filter object
The "cifiltername" property is required and its value is the name of the CoreImage filter that is to be created. The "cifilterproperties" property is required and its value is a list of json objects. This list can be of zero length for filters that take no inputs like the CIRandomGenerator filter. The "mifiltername" is optional and is the name identifier for the filter so that the filter can be referred to by filters later on in the filter chain.
Each json object in the property list "cifilterproperties" takes the following properties:
cifiltervalue
cifiltervalueclass
cifilterkey
To create a bitmap context with the name "grayscale.bitmapcontext" with width 768 and height 512 using a 16 bit grayscale integer preset you do:
The properties with keys "cifiltervalue" and "cifilterkey" are both required for all json objects in the property list, whereas the property "cifiltervalueclass" is required where the value for the "cifiltervalue" property is not a number. The values for "cifiltervalueclass" are "CIImage", "CIVector", "CIColor" and "NSString", these are the classes that Moving Images will attempt to convert the property value with key "cifiltervalue" to. In the case of "CIVector", and "CIColor" the actual type of the value for key "cifiltervalue" is string and the string value is converted into an object of the correct type before being assigned to the core image filter. In the case where "CIImage" is the value for the "cifiltervalueclass" property then the value is a json object/property list dictionary.
An example demonstrating the creation of a filter chain:
As you can see that is a bit unwieldy on the command line, so alternately the json object/property list can be a file on disk and in the create "imagefilterchain" subcommand then one of the command line options is a path to the file on disk. For a json file:
To close the image filter chain object once you've finished with it:
smig doaction -close -object $IMFCR
#### Modifiable properties of a image filter chain object
There are two properties of a image filter chain object that can be modified:
* "coreimagesoftwarerender" Should rendering happen through software or the GPU?
* "use_srgbcolorspace" Should rendering happen in the sRGB colorspace?
Both are boolean values. To specify that the image filter chain object should do a software render rather than using graphics processing unit (GPU) to do the image processing then do the following:
In most cases rendering using the GPU will be faster than software rendering.
When creating a bitmap graphics context you can override the default profile provided as part of the preset with another named profile with the same color space. For example all the RGB bitmap context presets use the sRGB profile as their default profile. There are three other named profiles for the RGB color space that can be used. These are: kCGColorSpaceGenericRGB, kCGColorSpaceGenericRGBLinear, and kCGColorSpaceAdobeRGB1998. So if you wanted to use the "kCGColorSpaceGenericRGBLinear" RGB profile instead then command would look like:
If you create a RGB colorspace bitmap context, then by default the context uses a sRGB color profile. When rendering the output of a image filter chain object to a bitmap context you might want to specify that the rendering should be done using the sRGB profile, by default rendering will be done using the RGB generic linear color profile which is faster. You can specify to use sRGB using this property:
echo Is filter chain software rendering: $USE_SOFTWARE
#### Drawing to a bitmap graphic context
#### Rendering the image filter chain object
To draw to the bitmap graphic context you use the "-drawelement" option for the doaction subcommand. The "-drawelement" option takes one of the options: "-jsonstring", "-jsonfile" or "-plistfile". If the option is "-jsonstring" then the string that immediately follows the option is a json object which describes the drawing, otherwise if the option is "-jsonfile" then the string that follows is a path to a file which is a text file containing a json object which describes the drawing, else if the option is "-plistfile" the the string that follows is a path to a file which is a plist file containing a dictionary object which describes the drawing.
