In my last post, Histogram Functions in Accelerate vImage, I looked using vImage's contrast stretching function to improve the contrast of an image. In this post, I'll look at another vImage histogram function: specification.This function allows us to apply an arbitrary histogram (typically from a suppled image) to an image. In the example above, the histogram from the leftmost photograph is applied to the sunset image in the centre to create the final blue tinted image on the right.
Technically, the histogram that was calculated from the leftmost image has been specified as the new histogram for the centre image.
The first step to recreate the example above is to calculate the histogram. We'll use the same technique described in my previous post to convert a supplied CGImage to a vImage buffer. However this time, we're not populating a target image, we're populating four arrays of unsigned integers that will contain the histogram values for each of the four colour channels (red, green, blue and alpha).
vImage's API shows its C roots and to calculate the histogram of inBuffer, we initialise four arrays, create pointers to those arrays and create pointers to an array of those pointers:
let alpha = [UInt](count: 256, repeatedValue: 0) let red = [UInt](count: 256, repeatedValue: 0) let green = [UInt](count: 256, repeatedValue: 0) let blue = [UInt](count: 256, repeatedValue: 0) let alphaPtr = UnsafeMutablePointer<vImagePixelCount>(alpha) let redPtr = UnsafeMutablePointer<vImagePixelCount>(red) let greenPtr = UnsafeMutablePointer<vImagePixelCount>(green) let bluePtr = UnsafeMutablePointer<vImagePixelCount>(blue) let rgba = [alphaPtr, redPtr, greenPtr, bluePtr] let histogram = UnsafeMutablePointer<UnsafeMutablePointer<vImagePixelCount>>(rgba)
The histogram object, along with the source image, are passed to vImageHistogramCalculation_ARGB8888(_:_:_:):
vImageHistogramCalculation_ARGB8888(&inBuffer, histogram, UInt32(kvImageNoFlags))
The original arrays, alpha, red, green and blue, are now populated with the histogram data.
Given the histogram data, we now need to specify it against another image (the sunset in our case). In my example, I've separated these two steps into two functions and my specification function requires a histogram tuple of the form:
histogram: (alpha: [UInt], red: [UInt], green: [UInt], blue: [UInt])
The vImage specification function, vImageHistogramSpecification_ARGB888(_:_:_:_:) requires an unsafe mutable pointer to an unsafe pointer of the pixel counts for each bucket for each channel. The following code prepareshistogram to pass into vImage (vImagePixelCount is a type alias for UInt):
let alphaPtr = UnsafePointer<vImagePixelCount>(histogram.alpha) let redPtr = UnsafePointer<vImagePixelCount>(histogram.red) let greenPtr = UnsafePointer<vImagePixelCount>(histogram.green) let bluePtr = UnsafePointer<vImagePixelCount>(histogram.blue) let rgba = UnsafeMutablePointer<UnsafePointer<vImagePixelCount>>([alphaPtr, redPtr, greenPtr, bluePtr])
Using the inBuffer and outBuffer technique from the previous post, we can now specify the histogram for a source image and populate a vImage buffer:
vImageHistogramSpecification_ARGB8888(&inBuffer, &outBuffer, rgba, UInt32(kvImageNoFlags))
Wrapping in a Core Image Filter
If all that logic seems a bit daunting to implement every time you want to calculate and specify a histogram, it can all be wrapped up in a Core Image filter. Take a look at my VImageFilters.swift file under Filterpedia to see it in action. The final filter can be used in the same way as any other Core Image filter with one caveat: vImage sometimes crashes when run in background threads, so Filterpedia always runs the filter in the main thread.
Histogram specification is a great tool for colorising monochrome images and matching colours of images for composition. vImage offers tools lacking in Core Image and, with a little work, its sightly arcane API can be hidden away inside a CIFilter wrapper.
The demo code to accompany this post is available here.