DIPlib Documentation - ©1995-2015 Quantitative Imaging Group, Delft University of Technology.

# SeparableFrameWork

FrameWork for separable filters

## SYNOPSIS

dip_Error dip_SeparableFrameWork (in, out, boundary, border, process )

## FUNCTION

The `dip_SeparableFrameWork` function is a framework for separable filters. This function takes care of all the "administrative work" involved when processing a n-D DIPlib image n times with a 1-D filter. In short, using this function, one has only to create an one dimension filter function and `dip_SeparableFrameWork` takes care of the other stuff. The `in` image is filtered `nrOfProcesses` times using the information in each element of the `process` array. If `nrOfProcesses` is zero, only the first element of `process` is used to filter `in` in all its dimensions.

## ARGUMENTS

Data type | Name | Description
`dip_Image` | `in` | Input image
`dip_Image` | `out` | Output image
`dip_BoundaryArray` | `boundary` | Boundary conditions
`dip_IntegerArray` | `border` | Border array
`dip_FrameWorkProcessArray` | `process` | Array of `dip_FrameWorkProcess` structures

## NOTE

The `dip_FrameWorkProcess` structure contains the following members:

Data type | Name | Description
`dip_Boolean` | `process` | flags specifying to do processing or not
`dipf_FrameWorkMethod` | `frameWorkMethod` | flags specifying the method of how `dip_SeparableFrameWork` should transport data from in to out
`dipf_FrameWorkOperation` | `frameWorkOperation` | flags specifying requirements of the 1-D filter function
`dip_int` | `processDimension` | dimension of `in` to be processed
`dip_int` | `roiOrigin` | ignored in current implementation
`dip_int` | `roiSize` | ignored in current implementation
`dipf_FrameWorkFilter` | `FrameWorkFilterType` | specifying the type of 1-D filter function
`dip_FrameWorkFilter` | `FrameWorkFilter` | pointer to the 1-D filter function
`void *` | `functionParameters` | parameters of the 1-D filter function, for all dimensions
`dip_DataType` | `inputBufferType` | data type of input buffer
`dip_DataType` | `outputBufferType` | data type of output buffer
`dip_DataType` | `suggestedOutputType` | data type of output image

The `dipf_FrameWorkMethod` enum contains the following elements:

Name | Description
`DIP_FRAMEWORK_DEFAULT_METHOD` | use `dip_SeparableFrameWorks` most optimal method
`DIP_FRAMEWORK_CLASSICAL` | use a classical method
`DIP_FRAMEWORK_DOUBLE_STRIPE` | use two buffers to store temporary results

It is strongly advised to use the `DIP_FRAMEWORK_DEFAULT_METHOD` method.

The `dipf_FrameWorkOperation` enum contains the following elements:

Name | Description
`DIP_FRAMEWORK_DEFAULT_OPERATION` | default operation
`DIP_FRAMEWORK_IN_PLACE` | filtering operation can be performed in-place. It is up to `dip_SeparableFrameWork` whether the actual filtering is done in-place
`DIP_FRAMEWORK_NO_IN_BORDER` | the 1-D filter does not need border extension of the input data
`DIP_FRAMEWORK_OUT_BORDER` | the 1-D filter needs border extension of the output data
`DIP_FRAMEWORK_WRITE_INPUT` | the 1-D filter needs to write in the input data
`DIP_FRAMEWORK_USE_BUFFER_TYPES` | made the input and output buffers of the `inputBufferType` and outputBufferType data type
`DIP_FRAMEWORK_NO_BUFFER_STRIDE` | Create input and output buffers with a stride of one
`DIP_FRAMEWORK_DO_NOT_ADJUST` | Do not adjust the output image, just check it
`DIP_FRAMEWORK_USE_OUTPUT_TYPE` | Adjust output image to the `suggestedOutputType` data type

The `dipf_FrameWorkFilter` enum contains the following elements:

Name | Description
`DIP_FRAMEWORK_SEPARABLE_FILTER` | default filter type, process one line at the time
`DIP_FRAMEWORK_TWO_LINES_SEPARABLE_FILTER` | process two lines in one go
`DIP_FRAMEWORK_SINGLE_OUTPUT_FILTER` | this filter only needs an output buffer

The union `dip_FrameWorkFunction` consists of the types

Name | Description
`dip_SeparableFilter` | one line filter function
`dip_TwoLinesSeparableFilter` | two lines filter function
`dip_SingleOutputFilter` | single output image filter

The functions have the following arguments: `dip_SeparableFilter`

Data type | Name | Description
`void *` | `inData` | pointer to the input data
`void *` | `outData` | pointer to the output data
`dip_int` | `elements` | number of pixels in the `inData` array
`dip_SeparableFilterParameters` | `params` | parameter structure for the filter function

and `dip_SeparableTwoLinesFilter`

Data type | Name | Description
`void *` | `inFirstLineData` | pointer to the data of the first input line
`void *` | `inSecondLineData` | pointer to the data of the second input line
`void *` | `outFirstLineData` | pointer to the data of the first output line
`void *` | `outSecondLineData` | pointer to the data of the second output line
`dip_int` | `elements` | number of pixels in the `inFirstLineData` array
`dip_TwoLinesSeparableFilterParameters` | `params` | parameter structure for the two lines filter function

The `inData`, `inFirstLineData` and `inSecondLineData` will always point to the first pixel of the line of `in` that is processed. Therefore, the 1-D filter can access pixels with indices ranging from `-border[dimension]` up to `elements + border[dimension]`. If the flag `DIP_FRAMEWORK_OUT_BOUNDARY` is specified, the same holds for the output data pointers.

The structure `dip_SeparableFilterParameters` contains the following elements:

Data type | Name | Description
`void *` | `functionParameters` | parameters of the 1-D filter function per dimension
`dip_int` | `dimension` | the dimension in which direction the input buffer is taken from the input image
`dip_int` | `processNumber` | number of times `dip_SeparableFrameWork` has already filtered `in` with an 1-D filter including current filtering
`dip_DataType` | `inType` | `dip_DataType` of the input buffer
`dip_int` | `inStride` | stride of the elements in the input array
`dip_int` | `inPlane` | plane number in case `in` is a binary image
`dip_DataType` | `outType` | `dip_DataType` of the output buffer
`dip_int` | `outStride` | stride of the elements in the output array
`dip_int` | `outPlane` | plane number in case `out` is a binary image
`dip_int` | `outDimension` | the dimension in which direction the output buffer is taken from the output image
`dip_IntegerArray` | `position` | coordinate of the first pixel of the input buffer in the input image

The structure `dip_TwoLinesSeparableFilterParameters` contains the following elements:

Data type | Name | Description
`void *` | `functionParameters` | parameters of the 1-D filter function per dimension
`dip_int` | `dimension` | the dimension in which direction the input buffer is taken from the input image
`dip_int` | `processNumber` | number of times `dip_SeparableFrameWork` has already filtered `in` with an 1-D filter including current filtering
`dip_DataType` | `inType` | `dip_DataType` of the input buffer
`dip_int` | `inStride` | stride of the elements in the input array
`dip_int` | `inPlane` | plane number in case `in` is a binary image
`dip_DataType` | `outType` | `dip_DataType` of the output buffer
`dip_int` | `outStride` | stride of the elements in the output array
`dip_int` | `outPlane` | plane number in case `out` is a binary image
`dip_int` | `outDimension` | the dimension in which direction the output buffer is taken from the output image
`dip_IntegerArray` | `position` | coordinate of the first pixel of the input buffer in the input image

The structure `dip_SingleOutputFilterParameters` contains the following elements:

Data type | Name | Description
`void *` | `functionParameters` | parameters of the 1-D filter function per dimension
`dip_int` | `dimension` | the dimension in which direction the input buffer is taken from the input image
`dip_int` | `processNumber` | number of times `dip_SeparableFrameWork` has already filtered `in` with an 1-D filter including current filtering
`dip_DataType` | `type` | `dip_DataType` of the input buffer
`dip_int` | `stride` | stride of the elements in the input array
`dip_int` | `plane` | plane number in case `in` is a binary image
`dip_IntegerArray` | `position` | coordinate of the first pixel of the input buffer in the input image

## SEE ALSO

DIPlib's data types `SeparableConvolution`, `MonadicFrameWork`, `SingleOutputFrameWork`, `PixelTableFrameWork`, `ScanFrameWork`