Swift and Objective-C generated classes for built-in CIFilter types. Type safe, auto-complete friendly and (mostly) documented.
Supports macOS, tvOS, iOS and mac Catalyst
I like CIFilters a lot. I've always found the CIFilter interfaces to be
- Hard to use due to the opaque interface (no code completion!), and
- Easy to make basic mistakes such as type mismatches etc. which would be very difficult to identify in a review (for example). Given that the parameters to filters are Any? values, there is no type checking around the api.
- Xcode's documentation for each filter is lacking for the most part.
- Information about the OS version in which the CIFilter appeared is buried within the opaque interface.
This package contains automatically generated type-safe and documented class wrappers for all of the built-in CIFilter types.
It also includes the scripts used to generate the classes, so that as new built-in CIFilters are added the classes can be easily (re)generated to include the new filters.
| Type safety | All filter attributes are exposed via class properties using type-safe Swift/Objective-C classes and types where possible. |
| Range clamping | Filters which define valid ranges for attributes have undefined behaviour when the assigned value is outside range. These classes automatically clamp assigned values to the valid range to avoid potential crashes for invalid values. |
| Auto-completion | As the filter attributes are exposed as properties, Xcode can provide autocomplete information while you code. |
| Version information | The generated classes are wrapped in @available() to make sure that only the filters your deployment target defines are available. |
| Documention | All classes and attributes are documented such that Xcode can provide • meaningful inline documentation. • meaningful documentation in the Xcode quick-help inspector. • With Xcode 13, you can compile a docarchive and have the full documentation for all filters available within the Xcode documentation viewer |
let filter = CIFilter(name: "CICheckerboardGenerator")!
filter.setValue(CIVector(x: 150.0, y: 150.0), forKey: "inputCenter")
filter.setValue(CIColor(red: 1.0, green: 1.0, blue: 1.0, alpha: 1.0), forKey: "inputColor0")
filter.setValue(CIColor(red: 0.0, green: 0.0, blue: 0.0, alpha: 1.0), forKey: "inputColor1")
filter.setValue(80.0, forKey: "inputWidth")
filter.setValue(1.0, forKey: "inputSharpness")
let output = filter.outputImagelet output = filter.outputImagelet filter = CIFF.CheckerboardGenerator()!
filter.center = CGPoint(x: 150.0, y: 150.0)
filter.color0 = CIColor(red: 1.0, green: 1.0, blue: 1.0, alpha: 1.0)
filter.color1 = CIColor(red: 0.0, green: 0.0, blue: 0.0, alpha: 1.0)
filter.width = 80.0
filter.sharpness = 1.0
let output = filter.outputImageCIFilter use string constants to define the argument parameters. Incredibly powerful and extensible but not overly discoverable without having to resort to online documentation like CIFilter.app. And forget Xcode code completion. As the parameter values are defined as String: Any?, you can spend a long time debugging an issue because you put in the wrong key string or an incorrect value type.
This library pulls out the 'soft' string-based parameters eg :-
// compiles, but filter is nil as there's a typo in CIBloom
let filter = CIFilter("CIBLoom")!
// no code completion, no type safety
filter.setValue(11.8, forKey: "inputRadius")
// These compile fine, but result in undefined behaviour during runtime.
filter.setValue(vector, forKey: "inputRadius")
filter.setValue(12.0, forKey: "inputNoodles")and creates type-safe parameters like :-
// No chance of a poorly named filter
guard let filter = CIFF.Bloom() else { fatalError() }
// code completion support, type safe, range safe. Read documentation directly in Xcode
filter.inputRadius = 11.8
// compile time error, invalid type
filter.inputRadius = vector
filter.inputTitle = 12.0CIFilterFactory defines all available documentation inline within the code itself, allowing Xcode to provide useful Quick Help for all available filters and parameters.
For example :-
/// Accordion Fold Transition
///
/// Transitions from one image to another of a differing dimensions by unfolding.
///
/// **CIFilter Name**
/// - CIAccordionFoldTransition
///
/// **Availability**
/// - macOS 10.10, iOS 8, tvOS 8
///
/// **Categories**
/// - BuiltIn (*CICategoryBuiltIn*)
/// - HighDynamicRange (*CICategoryHighDynamicRange*)
/// - StillImage (*CICategoryStillImage*)
/// - Transition (*CICategoryTransition*)
/// - Video (*CICategoryVideo*)
///
/// **Documentation Links**
/// - [CIAccordionFoldTransition Online Documentation](http://developer.apple.com/library/mac/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIAccordionFoldTransition)
/// - [CoreImage.CIFilterBuiltins Xcode documentation](https://developer.apple.com/documentation/coreimage/ciaccordionfoldtransition) /// - [CIFilter.app documentation](https://cifilter.app/CIAccordionFoldTransition/)
@available(macOS 10.10, iOS 8, tvOS 8, *)
@objc(CIFFAccordionFoldTransition) class AccordionFoldTransition: Core {/// The width of each bar.
///
/// CIFilter attribute information
/// - Attribute key: `inputWidth`
/// - Internal class: `NSNumber`
/// - Type: `CIAttributeTypeDistance`
/// - Minimum Value: `2.0`
/// - Default Value: `30.0`
@objc public var width: Double {
...
}
/// `width` range definition
public static let widthRange = PartialRangeFrom<Double>(2.0)A lot of the APIs define minimum and/or maximum values for input values. Unfortunately, these values are only publicly visible from Apple's documentation or via the programmatic interface. The generated code embeds the min/max definitions into the code comments, as well as defining clamping ranges for input values to ensure correct behaviour. Range definitions for each range-appropriate parameter are also automatically generated and made available for your code to validate against if needed.
Some of the supported types (like an affine transform) use different class types depending on the
platform (NSAffineTransform on macOS, CGAffineTransform wrapped in NSValue on everything else). This library
defines a common AffineTransform class which wraps the os-dependent type meaning that you don't have to your code.
Each filter that supports an inputImage generates an extension on CIImage for the filter to allow for
simple chaining of filters onto a CIImage. Each call returns either the original image, or a new CIImage
with the filter applied.
Each functional call also has an isActive parameter to allow you to easily enable/disable the filter within the chain.
For example, the CIBokehBlur filter generates :-
public extension CIImage {
/// Apply the 'Bokeh Blur' filter to this image and return a new filtered image
///
/// - Parameters:
/// - radius: The radius determines how many pixels are used to create the blur. The larger the radius, the blurrier the result. (0.0...500.0)
/// - ringAmount: The amount of extra emphasis at the ring of the bokeh. (0.0...1.0)
/// - ringSize: The size of extra emphasis at the ring of the bokeh. (0.0...0.2)
/// - softness: No Description (0.0...10.0)
/// - isActive: If true applies the filter and returns a new image, else returns this image
/// - Returns: The filtered image, or this image if the filter is not active
///
/// Smooths an image using a disc-shaped convolution kernel.
///
/// **Categories**: Blur, BuiltIn, HighDynamicRange, StillImage, Video
///
/// **Documentation Links**
/// - [CIBokehBlur Online Documentation](http://developer.apple.com/library/mac/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIBokehBlur)
/// - [CoreImage.CIFilterBuiltins Xcode documentation](https://developer.apple.com/documentation/coreimage/ciqrcodegenerator?language=objc)
/// - [CIFilter.app documentation](https://cifilter.app/CIBokehBlur/)
@inlinable func applyingBokehBlur(
radius: Double = CIFF.BokehBlur.radiusDefault,
ringAmount: Double = CIFF.BokehBlur.ringAmountDefault,
ringSize: Double = CIFF.BokehBlur.ringSizeDefault,
softness: Double = CIFF.BokehBlur.softnessDefault,
isActive: Bool = true
) -> CIImage {
...
}
}And then, you can simply chain these filters
let myImage = CIImage(...)
let filtered = myImage
.applyingBokehBlur(radius: 100)
.applyingSepiaTone()For generation filters like CIQRCodeGenerator (these filters don't have an explicit inputImage), a static creator function is generated
extension CIImage {
/// Create a new CIImage using the 'QR Code Generator' filter
///
/// - Parameters:
/// - message: The message to encode in the QR Code
/// - correctionLevel: QR Code correction level L, M, Q, or H.
/// - Returns: A new image by running the filter, or nil if the image could not be created
///
/// Generate a QR Code image for message data.
///
/// **Categories**: BuiltIn, Generator, StillImage
///
/// **Documentation Links**
/// - [CIQRCodeGenerator Online Documentation](http://developer.apple.com/library/mac/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIQRCodeGenerator)
/// - [CoreImage.CIFilterBuiltins Xcode documentation](https://developer.apple.com/documentation/coreimage/ciqrcodegenerator?language=objc)
/// - [CIFilter.app documentation](https://cifilter.app/CIQRCodeGenerator/)
@inlinable static func createUsingQRCodeGenerator(
message: Data,
correctionLevel: String
) -> CIImage? {
return CIFF.QRCodeGenerator(
message: message,
correctionLevel: correctionLevel
)?.outputImage
}
}CIFilter provides quite an amazing programmatic discovery interface, where you can ask it what filters are registered, the parameters that are accepted for a specific filter and all sorts of useful information like localized argument descriptions etc. Very cool, but also kinda useless when you're just wanting to create a sepia filter.
CIFilterFactory is automatically generated using a swift script file, which enumerates the available filters on the system and builds up a type-safe class structure for each of the filters. It also uses the discovery apis to document the generated code, meaning that Xcode has the ability to fully document each of the created classes. Not only that, but CIFilter also defines which operating systems it supports (macOS, tvOS, iOS) and when the filter became available, and the generated code takes advantage of this by wrapping generated classes in #available calls.
Using CIFilterFactory, Xcode can now :-
- Check available filters for platform/os version at compile time
- code-complete
- type check methods and generate error(s) at compile-time
- clamp input values to defined ranges.
Cool!
guard let bloomFilter = CIFilter(name: "CIBloom") else { fatalError() }
bloomFilter.setValue(inputImage, forKey: kCIInputImageKey)
bloomFilter.setValue(0.3, forKey: kCIInputIntensityKey)
bloomFilter.setValue(5, forKey: kCIInputRadiusKey)
let outputImage = bloomFilter.outputImageguard let bloomFilter = CIFF.Bloom() else { fatalError() }
bloomFilter.inputImage = image
bloomFilter.intensity = 0.3
bloomFilter.radius = 5
let outputImage = bloomFilter.outputImageUsing the generated interface provides :-
- Avoid mistakes from incorrect parameter string identifiers
- Code completion
- Type checking
- Automatic range validation
- Automatically generate expressive Xcode documentation within the
id appimage = [NSImage imageNamed:NSImageNameApplicationIcon];
id bir = [[NSBitmapImageRep alloc] initWithData:[appimage TIFFRepresentation]];
id image = [[CIImage alloc] initWithBitmapImageRep:bir];
CIFFBloom* filter = [[CIFFBloom alloc] init];
[filter setInputImage: image];
[filter setRadius: 10];
[filter setIntensity: 4];
CIImage* output = [filter outputImage];
assert(output != nil);In more recent versions of Xcode, the SDK now comes with a pre-generated set of CIFilter classes (like CIFilter.pixellate()). This library was written before CIFilterBuiltins was available, and was also required to support Objective-C (admittedly, becoming less and less of a problem as time goes on).
- only available for newer versions of Xcode.
- No objective-c support.
- Some filters are not available (eg.
CICrop) - Basically undocumented.
CIFilterFactoryembeds ALL the documentation within the generated code so it's directly available when you need it.
Use Swift Package Manager.
You can find some really simple examples for both Swift and Objective-C in the Demo subfolder.
NOTE: This is only available for Xcode 13 and later
There is a project in the tools/generator folder, called ciff_generator. Open this in XCode 13 and build/run
the project.
Additionally, there is a script in the tools directory which will rebuild the filters and update the Xcode documentation.
- Open a terminal and navigate to the
CIFilterFactory/toolsfolder - run
sh regenerate.sh
NOTE: This is only available for Xcode 13 and later
- Open a terminal and navigate to the CIFilterFactory/tools folder
- run
sh make-docs.sh
MIT License
Copyright (c) 2024 Darren Ford
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.