The SEARCH3D function finds “objects” or regions of similar data values within a 3-D array of data. Given a starting location and a range of values to search for, SEARCH3D finds all the cells within the volume that are within the specified range of values and have some path of connectivity through these cells to the starting location. In addition to searching for cells within a global range of data values, SEARCH3D can also search for adjacent cells whose values deviate from their neighbors within specified tolerances.

This routine is written in the IDL language. Its source code can be found in the file search3d.pro in the lib subdirectory of the IDL distribution.

## Examples

Find all the indices corresponding to an object contained in a 3-D array:

`; Create some data. vol = RANDOMU(s, 40, 40, 40)vol[3:13, 1:15, 17:33] = 1.3 vol[15:25, 5:25, 15:25] = 0.2vol[5:30,17:38,7:28] = 1.3vol[9:23, 16:27, 7:33] = 1.5; Search for an object starting at (6, 22, 16) whose data values; are between (1.2) and (1.4):region = SEARCH3D(vol, 6, 22, 16, 1.2, 1.4, /DIAGONAL); Scale the background cells into the range 0 to 127:vol = BYTSCL(vol, TOP=127B); Highlight the object region by setting it to 255:vol[Region] = 255BWINDOW, 0, XSIZE=640, YSIZE=512, RETAIN=2; Set up a 3-D view:CREATE_VIEW, XMAX=39, YMAX=39, ZMAX=39, AX=(-30), AZ=30, ZOOM=0.8; Display the volume with the highlighted object in it:TVSCL, PROJECT_VOL(vol, 64, 64, 40, DEPTH_Q=0.4)`

## Syntax

Result = SEARCH3D( Array, Xpos, Ypos, Zpos, Min_Val, Max_Val [, /DECREASE , /INCREASE [, LPF_BAND=integer{≥3}]] [, /DIAGONAL] )

## Return Value

SEARCH3D returns a longword array that contains a list of the array subscripts that define the selected object or region. The original X and Y indices of the array subscripts returned by SEARCH3D can be found with the following IDL code:

`S = SIZE(Array)`
`index_z = Result / (S[1] * S[2]) `
`index_y = (Result - (index_z * S[1] * S[2])) / S[1]`
`index_x = (Result - (index_z * S[1] * S[2])) - (index_y * S[1]) `

where Result is the array returned by SEARCH3D and Array is the original input volume. The object within Array can be subscripted as Array[Region] or Array[index_x, index_y, index_z].

## Arguments

### Array

The three-dimensional array, of any data type except string, to be searched.

### Xpos

The X coordinate (dimension 0 or Array) of the starting location.

### Ypos

The Y coordinate (dimension 1 of Array) of the starting location.

### Zpos

The Z coordinate (dimension 2 of Array) of the starting location.

### Min_Val

The minimum data value for which to search. All array subscripts of all the cells that are connected to the starting cell, and have a value between Min_Val and Max_Val (inclusive) are returned.

### Max_Val

The maximum data value for which to search.

## Keywords

### DECREASE

This keyword and the INCREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if INCREASE is specified.

### INCREASE

This keyword and the DECREASE keyword allow you to compensate for changing intensities of data values within an object. An edge-enhanced copy of Array is made and compared to the orginal array if this keyword is set. When DECREASE or INCREASE is set, any adjacent cells are found if their corresponding data values in the edge enhanced array are greater than DECREASE and less than INCREASE. In any case, the adjacent cells will never be selected if their data values are not between Min_Val and Max_Val. The default for this keyword is 0.0 if DECREASE is specified.

### LPF_BAND

Set this keyword to an integer value of 3 or greater to perform low-pass filtering on the edge-enhanced array. The value of LPF_BAND is used as the width of the smoothing window. This keyword is only effective when the DECREASE or INCREASE keywords are also specified. The default is no smoothing.

### DIAGONAL

Set this keyword to cause SEARCH3D to find cells meeting the search criteria whose surrounding cubes share a common corner or edge. Normally, cells are considered adjacent only when cubes surrounding the cells share a common edge. Setting this option requires more memory and execution time.

## Version History

 Pre-4.0 Introduced