```{index} single: Filters; Crop Geometry (Image)
```
# Crop Geometry (Image)

## Description

This **Filter** allows the user to crop a region of interest (ROI) from an **Image Geometry**.  The input parameters are in units of voxels or physical coordinates.  

It is possible to also crop specific dimensions of the **Image Geometry** by toggling **Crop X Dimension**, **Crop Y Dimension**, and **Crop Z Dimension** ON and OFF.

## WARNING: NeighborList Removal

If the option to "Renumber Features" is turn ON and the Cell Feature AttributeMatrix contains any *NeighborList* data arrays, those arrays will be **REMOVED** because those lists are now invalid. Re-run the *Find Neighbors* filter to re-create the lists.


## Examples

In the following examples, the following image is being used.

- Origin:     [0.0, 0.0, 0.0]
- Spacing:    {0.5, 0.5, 1.0}
- Dimensions: {100, 100, 1}

So the bounds of the image is (0-50 micron, 0-50 micron, 0-1 micron)

![Base image for examples](Images/CropImageGeometry_1.png)

### Example 1

If the user wanted to crop the last 50 voxels in the X and Y axis then the user would use the following values:

    Xmin = 50,
    Xmax = 99,
    Ymin = 50,
    Ymax = 99,
    Zmin = 0,
    Zmax = 0 

![Cropped image using voxels as the bounds](Images/CropImageGeometry_2.png)

**Note:** the units in the above image is in microns.

**Note:** The input parameters are *inclusive* and begin at *0*, so in the above example *50-99* will include the last 50 voxels.

### Example 2

If the user would like to crop out the `middle` 50 voxels from the image, these are the inputs:

    Xmin = 25,
    Xmax = 74,
    Ymin = 25,
    Ymax = 74,
    Zmin = 0,
    Zmax = 0

![Cropped image using voxels as the bounds](Images/CropImageGeometry_3.png)

### Example 3

In this example the user is going to define the crop using physical coordinates and also selecting an upper bound that exceeds the actual bounds of the image. In this case, the filter will instead use the maximum bounds from that axis.

    Xmin = 30 microns,
    Xmax = 65 microns,
    Ymin = 30 microns,
    Ymax = 65 microns,
    Zmin = 0 microns,
    Zmax = 65 microns

**Note:** This will work because at least some portion of the cropped image is within the original image. If **ALL** cropped values fall out side of the image bounds then the filter will error out in preflight.

![Cropped image using voxels as the bounds](Images/CropImageGeometry_4.png)

User may note that the way the bounds are determined are affected by the origin and spacing, so be sure to take these into account when supplying coordinate bounds for the crop.

## Renumber Features

It is possible with this **Filter** to fully remove **Features** from the volume, possibly resulting in consistency errors if more **Filters** process the data in the pipeline. If the user selects to *Renumber Features* then the *Feature Ids* array will be adjusted so that all **Features** are continuously numbered starting from 1. The user should decide if they would like their **Features** renumbered or left alone (in the case where the cropped output is being compared to some larger volume).

The user has the option to save the cropped volume as a new **Data Container** or overwrite the current volume.


### Input Parameter(s)

| Parameter Name | Parameter Type | Parameter Notes | Description |
|----------------|----------------|-----------------|-------------|
| Use Physical Units For Bounds | Bool |  | If true define physical coordinates for bounds, If false define voxel indices for bounds |
| Crop X Dimension | Bool |  | Enable cropping in the X dimension. |
| Crop Y Dimension | Bool |  | Enable cropping in the Y dimension. |
| Crop Z Dimension | Bool |  | Enable cropping in the Z dimension. |
| Min Voxel | Vector of UInt64 Values | Order=X (Column),Y (Row),Z (Plane) | Lower bound of voxels of the volume to crop out |
| Max Voxel [Inclusive] | Vector of UInt64 Values | Order=X (Column),Y (Row),Z (Plane) | Upper bound in voxels of the volume to crop out |
| Min Coordinate (Physical Units) | Vector of Float64 Values | Order=X,Y,Z | Lower bound in real units of the volume to crop. |
| Max Coordinate (Physical Units) [Inclusive] | Vector of Float64 Values | Order=X,Y,Z | Upper bound in real units of the volume to crop. |
| Perform In Place | Bool |  | Removes the original Image Geometry after filter is completed |

### Input Image Geometry

| Parameter Name | Parameter Type | Parameter Notes | Description |
|----------------|----------------|-----------------|-------------|
| Selected Image Geometry | Geometry Selection | Image | DataPath to the source Image Geometry |

### Optional Renumber Features

| Parameter Name | Parameter Type | Parameter Notes | Description |
|----------------|----------------|-----------------|-------------|
| Renumber Features | Bool |  | Specifies if the feature IDs should be renumbered |
| Cell Feature Ids | Array Selection | Allowed Types: int32 Comp. Shape: 1 | Specifies to which feature each cell belongs. |
| Feature Attribute Matrix | AttributeMatrixSelection |  | DataPath to the feature Attribute Matrix |

### Output Image Geometry

| Parameter Name | Parameter Type | Parameter Notes | Description |
|----------------|----------------|-----------------|-------------|
| Created Image Geometry | DataGroupCreation |  | The DataPath to store the created Image Geometry |

## Example Pipelines

## License & Copyright

Please see the description file distributed with this **Plugin**

## DREAM3D-NX Help

If you need help, need to file a bug report or want to request a new feature, please head over to the [DREAM3DNX-Issues](https://github.com/BlueQuartzSoftware/DREAM3DNX-Issues/discussions) GitHub site where the community of DREAM3D-NX users can help answer your questions.
