vImageMultiDimensionalInterpolatedLookupTable_PlanarF(_:_:_:_:_:_:)

Uses a multidimensional lookup table to transform a 32-bit planar image.

Declaration

func vImageMultiDimensionalInterpolatedLookupTable_PlanarF(_ srcs: UnsafePointer<vImage_Buffer>, _ dests: UnsafePointer<vImage_Buffer>, _ tempBuffer: UnsafeMutableRawPointer!, _ table: vImage_MultidimensionalTable, _ method: vImage_InterpolationMethod, _ flags: vImage_Flags) -> vImage_Error

Parameters

srcs:
An array of vImage buffers that reference the source image planes. The number of source buffers is the numSrcChannels parameter you pass to Vimagemultidimensionaltable_create(_:_:_:_:_:_:_:).
dests:
An array of vImage buffers that reference the destination image planes. The number of destination buffers is the numDestChannels parameter you pass to Vimagemultidimensionaltable_create(_:_:_:_:_:_:_:).
tempBuffer:
A pointer to workspace memory the function uses as it operates on an image. Pass nil to instruct the function to allocate, use, and then free its own temporary buffer.
table:
The multidimensional lookup table.
method:
The interpolation method, either Kvimagefullinterpolation or Kvimagehalfinterpolation.
flags:
The options to use when performing the operation. If your code implements its own tiling or its own multithreading, pass Kvimagedonottile; otherwise, pass Kvimagenoflags.
To instruct the function to return the minimum size of the workspace memory, set the Kvimagegettempbuffersize flag.
Pass Kvimagegettempbuffersize to specify that the function returns the minimum temporary buffer size for the operation with the specified parameters.

Mentioned in

Applying color transforms to images with a multidimensional lookup table

Return Value

kvImageNoError; otherwise, a negative value indicates one of the error codes that Data Types and Constants describes, and a positive value indicates the required size for the temporary buffer.

Discussion

The following code shows how to convert an RGB image that’s represented as three planar buffers to grayscale. The call to vImageMultiDimensionalInterpolatedLookupTable_PlanarF(_:_:_:_:_:_:) uses the lookup table from the example code in the Discussion section for vImageMultidimensionalTable_Create(_:_:_:_:_:_:_:). The source image contains three pixels, one is pure red, one is pure green, and one is pure blue. On return, the destination image contains three pixels with the values [0.2125887, 0.71519035, 0.072190434].

let size = vImage.Size(width: 1, height: 3)

let red = vImage.PixelBuffer<vImage.PlanarF>(
    pixelValues: [1, 0, 0],
    size: size)
let green = vImage.PixelBuffer<vImage.PlanarF>(
    pixelValues: [0, 1, 0],
    size: size)
let blue = vImage.PixelBuffer<vImage.PlanarF>(
    pixelValues: [0, 0, 1],
    size: size)

let source = vImage.PixelBuffer<vImage.PlanarFx3>(
    planarBuffers: [red, green, blue])

let destination = vImage.PixelBuffer<vImage.PlanarF>(
    size: size)

source.withUnsafeVImageBuffers { src in
    destination.withUnsafeVImageBuffer { dest in
        
        _ = vImageMultiDimensionalInterpolatedLookupTable_PlanarF(
            src,
            [dest],
            nil,
            lookupTable,
            kvImageFullInterpolation,
            vImage_Flags(kvImageNoFlags))
    }
}

// Prints "[0.2125887, 0.71519035, 0.072190434]".
print(destination.array)

Optimize performance with temporary buffers

This function uses a multiple-pass algorithm that saves intermediate pixel values between passes. In some cases, the destination buffer may not be large enough to store that intermediate data, so the operation requires additional storage.

Pass nil to the tempBuffer parameter to have vImage create and manage this temporary storage for you.

In cases where your code calls the function frequently (for example, when processing video), create and manage this temporary buffer yourself and reuse it across function calls. Reusing a buffer avoids vImage allocating the temporary storage with each call.

To use your own temporary buffer, first call the function with the same values for all other parameters that you intend to use for subsequent calls. In addition, pass the kvImageGetTempBufferSize flag. The kvImageGetTempBufferSize instructs the function not to perform any processing, and to return a positive value that represents the minimum size, in bytes, of the temporary buffer. A negative return value represents an error.

After you allocate the memory for the temporary buffer, pass that to the tempBuffer parameter for subsequent calls to the function, and don’t pass the kvImageGetTempBufferSize flag.

You can use the same workspace memory for a group of images that are different sizes. To do this, create a vImage buffer structure with a size that shares the maximum width and maximum height of the images that you’re working with. For example, to create a workspace memory that’s suitable for 4x4, 5x4, and 4x5 images, pass a buffer with the size 5x5.