The SHIFT_DIFF function applies a shift-difference filter to an image array to generate an array containing differences representing edges in the image.

## Examples

This example produces an image with black gradients on the left and white gradients on the right.

TVSCL, SHIFT_DIFF(DIST(200), DIRECTION=4)

## Syntax

*Result* = SHIFT_DIFF (*Array* [, /ADD_BACK] [, BIAS=*value*] [, /CENTER] [, DIRECTION={0 | 1 | 2 | 3 | 4 | 5 | 6 | 7}] [, /EDGE_TRUNCATE] [, /EDGE_WRAP] [, /EDGE_ZERO] [, INVALID=*value*] [, MISSING=*value*] [, /NAN] [, /NORMALIZE] )

## Return Value

Returns the filtered array of the same dimensions as the input array. The input type is converted to an output type as follows:

Input |
Output |

BYTE |
INT |

INT |
LONG |

UINT |
LONG |

ULONG |
LONG64 |

ULONG64 |
LONG64 |

Non-numeric types: not allowed | |

All other types |
Same as input type |

## Arguments

### Array

A two-dimensional array of any numeric type containing the image.

## Keywords

### ADD_BACK

Set this keyword to cause the original input array to be added back to the difference array generated by the shift-difference operator. This is often useful for sharpening the image.

If the ADD_BACK keyword is set, the function returns an array of the same type and dimensions as the input array.

### BIAS

Set this keyword to the bias offset to be added to each result value. If you have negative kernel values and a byte or unsigned integer input array, you can use this keyword to ensure that the result values are within the range of your data type.

*Note: *The same BIAS is added to each result value, regardless of any missing data as specified by the INVALID or NAN keywords. It is usually not appropriate to add the full BIAS if portions of the kernel were not applied due to missing data. In this case, you might want to use the NORMALIZE keyword instead.

### CENTER

Set or omit this keyword to center the kernel over each array point. If CENTER is explicitly set to zero, the SHIFT_DIFF function works in the conventional mathematical sense.

*Note: *For the kernel to be centered, it must be symmetric about the point K[FLOOR(*m*/2)], where *m* is the number of elements in the kernel. In many signal and image processing applications, it is useful to center a symmetric kernel over the data, thereby aligning the result with the original array.

### DIRECTION

An integer between 0 and 7 to specify the direction of the shift:

0 |
1 |
2 |

3 |
x |
4 |

5 |
6 |
7 |

### EDGE_TRUNCATE

Set this keyword to make SHIFT_DIFF compute the values of elements at the edge of *Array* (where *A *is an *n*-element vector, *K* is an *k*-element vector (*k *≤*n*), and *S* is the scale factor) by repeating the subscripts of *Array* at the edge. For example, if CENTER is set to zero:

where *n* is the number of elements in *Array*.

If none of the EDGE_* keywords are set, SHIFT_DIFF sets the values of *Result* to zero (or the value of BIAS) where the kernel extends beyond the edge.

### EDGE_WRAP

Set this keyword to make SHIFT_DIFF compute the values of elements at the edge of *Array* (where *A *is an *n*-element vector, *K* is an *k*-element vector (*k *≤ *n*), and *S* is the scale factor) by “wrapping” the subscripts of *Array* at the edge. For example, if CENTER is set to zero:

where n is the number of elements in *Array*.

If none of the EDGE_* keywords are set, SHIFT_DIFF sets the values of *Result* to zero (or the value of BIAS) where the kernel extends beyond the edge.

### EDGE_ZERO

Set this keyword to make SHIFT_DIFF compute the values of elements at the edge of *Array* (where *A *is an *n*-element vector, *K* is an *k*-element vector (*k*≤ *n*), and *S* is the scale factor) as if the array were padded with zeroes. For example, if CENTER is set to zero:

If none of the EDGE_* keywords are set, SHIFT_DIFF sets the values of *Result* to zero (or the value of BIAS) where the kernel extends beyond the edge.

### INVALID

Set this keyword to a scalar value of the same type as *Array* that should be used to indicate missing or invalid data within *Array*. Missing data are ignored when computing the convolution for neighboring elements. In *Result*, missing elements are replaced by the convolution of all other valid points within the kernel. If all points within the kernel are missing, the result at that point is given by the value of the MISSING keyword.

*Tip: *The INVALID keyword has the same effect as the NAN keyword, but is useful for byte or integer data which have missing values.

*Note: *The INVALID keyword uses a simple comparison to ignore values and should not be set to *NaN*. For floating-point data, you can use the INVALID and NAN keywords simultaneously to filter out both user-defined values and *NaN* or *Infinity* values.

### MISSING

Set this keyword to the numeric value to return for elements that contain no valid points within the kernel. The default is zero for byte or integer input, and NaN for floating-point input. This keyword is only used if the INVALID or NAN keyword is set.

### NAN

Set this keyword to cause the routine to check for occurrences of the IEEE floating-point values *NaN* or *Infinity* in the input data. Elements with the value *NaN* or *Infinity* are treated as missing data. Missing data are ignored when computing the convolution for neighboring elements. In the Result, missing elements are replaced by the convolution of all other valid points within the kernel. If all points within the kernel are missing, then the result at that point is given by the MISSING keyword.

*Note: *SHIFT_DIFF should never be called without the NAN keyword if the input array may possibly contain *NaN* or *Infinity* values.

### NORMALIZE

Set this keyword to automatically compute a bias and apply it to the result values. If this keyword is set, the BIAS keyword is ignored.

For BYTE or UINT, the bias is defined as the sum of the absolute values of the negative *Kernel* values, multiplied by either (255/Scale) for BYTE or (65535/*Scale*) for UINT, where *Scale* is the computed scale factor. For all other types, the bias is zero.

*Tip: *If NORMALIZE is set and your input array has missing data (the INVALID or NAN keywords are set), for each result value the scale factor and bias are computed using only those kernel values that contributed to that result value. This ensures that all result values are comparable in magnitude, regardless of any missing data.

### Thread Pool Keywords

This routine is written to make use of IDL’s *thread pool*, which can increase execution speed on systems with multiple CPUs. The values stored in the !CPU system variable control whether IDL uses the thread pool for a given computation. In addition, you can use the thread pool keywords TPOOL_MAX_ELTS, TPOOL_MIN_ELTS, and TPOOL_NOTHREAD to override the defaults established by !CPU for a single invocation of this routine. See Thread Pool Keywords for details.

## Version History

6.4 |
Introduced |

## See Also

CONVOL, EDGE_DOG, EMBOSS, LAPLACIAN, PREWITT, ROBERTS, SOBEL