---
title: "ImageCases"
language: "en"
type: "Symbol"
summary: "ImageCases[image] gives an association of lists of subimages for each identified category of objects in image. ImageCases[image, category] gives a list of subimages identified as an instance of the specified category. ImageCases[image, category -> prop] gives the specified property prop for each identified subimage. ImageCases[image, {category1, category2, ...}] gives an association with lists of subimages identified as being instances of each of the categoryi. ImageCases[video, ...] gives a time series of detected objects in frames of video."
keywords: 
- object detection
- find subimage
- subimage position
- template matching
- find template
- find image template
- locate image template
canonical_url: "https://reference.wolfram.com/language/ref/ImageCases.html"
source: "Wolfram Language Documentation"
related_guides: 
  - 
    title: "Computer Vision"
    link: "https://reference.wolfram.com/language/guide/ComputerVision.en.md"
  - 
    title: "Segmentation Analysis"
    link: "https://reference.wolfram.com/language/guide/SegmentationAnalysis.en.md"
  - 
    title: "Image Computation: Update History"
    link: "https://reference.wolfram.com/language/guide/ImageComputation-UpdateHistory.en.md"
  - 
    title: "Machine Learning"
    link: "https://reference.wolfram.com/language/guide/MachineLearning.en.md"
  - 
    title: "Video Computation: Update History"
    link: "https://reference.wolfram.com/language/guide/VideoComputation-UpdateHistory.en.md"
  - 
    title: "Video Analysis"
    link: "https://reference.wolfram.com/language/guide/VideoAnalysis.en.md"
related_functions: 
  - 
    title: "FindFaces"
    link: "https://reference.wolfram.com/language/ref/FindFaces.en.md"
  - 
    title: "FindImageText"
    link: "https://reference.wolfram.com/language/ref/FindImageText.en.md"
  - 
    title: "ImageContents"
    link: "https://reference.wolfram.com/language/ref/ImageContents.en.md"
  - 
    title: "ImageBoundingBoxes"
    link: "https://reference.wolfram.com/language/ref/ImageBoundingBoxes.en.md"
  - 
    title: "ImagePosition"
    link: "https://reference.wolfram.com/language/ref/ImagePosition.en.md"
  - 
    title: "ImageIdentify"
    link: "https://reference.wolfram.com/language/ref/ImageIdentify.en.md"
  - 
    title: "HighlightImage"
    link: "https://reference.wolfram.com/language/ref/HighlightImage.en.md"
  - 
    title: "ImageContainsQ"
    link: "https://reference.wolfram.com/language/ref/ImageContainsQ.en.md"
  - 
    title: "TextCases"
    link: "https://reference.wolfram.com/language/ref/TextCases.en.md"
  - 
    title: "Cases"
    link: "https://reference.wolfram.com/language/ref/Cases.en.md"
---
[EXPERIMENTAL]

# ImageCases

ImageCases[image] gives an association of lists of subimages for each identified category of objects in image.

ImageCases[image, category] gives a list of subimages identified as an instance of the specified category.

ImageCases[image, category -> prop] gives the specified property prop for each identified subimage.

ImageCases[image, {category1, category2, …}] gives an association with lists of subimages identified as being instances of each of the categoryi.

ImageCases[video, …] gives a time series of detected objects in frames of video.

## Details and Options

* ``ImageCases`` is also known as object detection and attempts to find instances of an object category present in an image and returns a list of subimages per category.

* Possible forms for ``category`` include:

|                             |                                               |
| --------------------------- | --------------------------------------------- |
| "concept"                   | named concept, as used in "Concept" entities  |
| "word"                      | English word, as used in WordData             |
| wordspec                    | word sense specification, as used in WordData |
| Entity[…]                   | any appropriate entity                        |
| category1 \| category2 \| … | any of the categoryi                          |

* The property ``prop`` can be any of the following:

|                   |                                       |
| ----------------- | ------------------------------------- |
| "BoundingBox"     | the bounding box given as a Rectangle |
| "Confidence"      | confidence of the identification      |
| "Dimensions"      | width and height of the subimage      |
| "Image"           | the identified subimage (default)     |
| "Position"        | center of the identified bounding box |
| {prop1, prop2, …} | a list of properties                  |

* Masked subimage properties:

|                   |                                        |
| ----------------- | -------------------------------------- |
| "Mask"            | binary mask indicating the object      |
| "MaskBoundingBox" | the bounding box of the masked image   |
| "MaskCentroid"    | centroid of the mask                   |
| "MaskedImage"     | subimage masked by the component shape |
| "MaskMedoid"      | medoid of the mask                     |
| "MaskPosition"    | center of the mask bounding box        |

* The following options can be given:

|                      |            |                                           |
| -------------------- | ---------- | ----------------------------------------- |
| AcceptanceThreshold  | Automatic  | identification acceptance threshold       |
| MaxFeatures          | Automatic  | maximum number of subimages to return     |
| MaxOverlapFraction   | Automatic  | maximum bounding box overlap              |
| PerformanceGoal      | "Balanced" | aspects of performance to try to optimize |
| TargetDevice         | "CPU"      | the target device on which to compute     |

* ``ImageCases`` uses machine learning. Its methods, training sets and biases included therein may change and yield varied results in different versions of the Wolfram Language.

* ``ImageCases`` may download resources that will be stored in your local object store at ``\$LocalBase``, and can be listed using ``LocalObjects[]`` and removed using ``ResourceRemove``.

---

## Examples (19)

### Basic Examples (3)

Find identified subimages of an image:

```wl
In[1]:= ImageCases[[image]]

Out[1]= [image]
```

---

Find subimages identified as a dog:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Infraspecies:CanisLupusFamiliaris"]]

Out[1]= {[image]}
```

---

Get the detected and segmented objects of an image:

```wl
In[1]:= ImageCases[[image], All -> "MaskedImage"]

Out[1]= [image]
```

### Scope (11)

#### Data (2)

Detect objects in an image:

```wl
In[1]:= ImageCases[[image]]

Out[1]= <|Entity["Concept", "Auto::p735c"] -> {[image], [image], [image], [image], [image], [image], [image], [image]}|>
```

---

Detect objects in frames of video:

```wl
In[1]:= ts = ImageCases[\!\(\*VideoBox["![Embedded Video Player](video://content-k8ee4)"]\)]

Out[1]= TemporalData[TimeSeries, «1»]
```

Objects at a given time:

```wl
In[2]:= ts[.3]

Out[2]= <|Entity["Concept", "Auto::p735c"] -> {[image], [image], [image], [image], [image], [image], [image], [image]}|>
```

#### Categories (2)

Find all the detectable objects in an image:

```wl
In[1]:= ImageCases[[image]]

Out[1]= <|Entity["Concept", "Person::93r37"] -> {[image]}, Entity["Concept", "Bird::56ny3"] -> {[image]}|>
```

---

Find all birds in the image:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Class:Aves"]]

Out[1]= {[image]}
```

#### Properties (7)

Find the birds' bounding boxes:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Class:Aves"] -> "BoundingBox"]

Out[1]= {Rectangle[{223, 55}, {350, 182}]}
```

---

Return multiple properties:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Class:Aves"] -> {"BoundingBox", "Probability"}]

Out[1]= {{Rectangle[{223, 55}, {350, 182}], 0.911157}}
```

---

Query properties of the concept:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Class:Aves"] -> {"Name", "Definition"}]

Out[1]= {{"bird", "warm-blooded egg-laying vertebrates characterized by feathers and forelimbs modified as wings"}}
```

---

Group together the detection for multiple categories:

```wl
In[1]:= ImageCases[[image], Entity["Species", "Class:Aves"] | Entity["Concept", "Person::93r37"] -> {"Name", "Image"}]

Out[1]= {{"person", [image]}, {"bird", [image]}}
```

---

Return the specified properties for all the detectable categories:

```wl
In[1]:= ImageCases[[image], All -> {"Image", "Position", "Definition"}]//Dataset

Out[1]=
Dataset[Association[Entity["Concept", "Person::93r37"] -> 
   {{Image[CompressedData["«35945»"], "Byte", ColorSpace -> "RGB", ImageResolution -> {72, 72}, 
      Interleaving -> True], {53.5, 75.}, "a human body (usually including the clothing)"}}, ... -> 
   {{Image[CompressedData["«33687»"], "Byte", 
      ColorSpace -> "RGB", ImageResolution -> {72, 72}, Interleaving -> True], {286.5, 118.5}, "war\
m-blooded egg-laying vertebrates characterized by feathers and forelimbs modified as wings"}}]]
```

---

Get the detected and segmented objects of an image:

```wl
In[1]:= ImageCases[[image], All -> "MaskedImage"]

Out[1]= <|Entity["Concept", "Person::93r37"] -> {[image]}, Entity["Concept", "Bird::56ny3"] -> {[image]}|>
```

---

Mask of each detected subimage:

```wl
In[1]:= ImageCases[[image], All -> "Mask"]

Out[1]= <|Entity["Concept", "Person::93r37"] -> {[image]}, Entity["Concept", "Bird::56ny3"] -> {[image]}|>
```

### Options (4)

#### AcceptanceThreshold (1)

Objects with low probability are not returned:

```wl
In[1]:= i = [image];

In[2]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"]]

Out[2]= {[image], [image], [image], [image], [image]}
```

Allowing a lower probability may result in more objects being recognized:

```wl
In[3]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"], AcceptanceThreshold -> 0.1]

Out[3]= {[image], [image], [image], [image], [image], [image]}
```

#### MaxFeatures (1)

By default, all the detected objects are returned:

```wl
In[1]:= i = [image];

In[2]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"]]

Out[2]= {[image], [image], [image], [image], [image]}
```

Specify a maximum number of results:

```wl
In[3]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"], MaxFeatures -> 2]

Out[3]= {[image], [image]}
```

#### MaxOverlapFraction (1)

The detected bounding boxes may overlap each other:

```wl
In[1]:= i = [image];

In[2]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"] -> "BoundingBox"]

Out[2]= {Rectangle[{21, 20}, {93, 162}], Rectangle[{143, 4}, {205, 215}], Rectangle[{101, 43}, {147, 223}], Rectangle[{302, 108}, {344, 229}], Rectangle[{382, 128}, {407, 233}]}

In[3]:= HighlightImage[i, %]

Out[3]= [image]
```

Find only non-intersecting objects:

```wl
In[4]:=
ImageCases[i, Entity["Concept", "Wineglass::w5dj5"] -> "BoundingBox", MaxOverlapFraction -> 0];
HighlightImage[i, %]

Out[4]= [image]
```

#### TargetDevice (1)

By default, the function is evaluated on CPU:

```wl
In[1]:= i = [image];

In[2]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"]]//AbsoluteTiming

Out[2]= {0.379749, {[image], [image], [image], [image], [image]}}
```

Use the ``TargetDevice`` option to specify a different device:

```wl
In[3]:= ImageCases[i, Entity["Concept", "Wineglass::w5dj5"], TargetDevice -> "GPU"]//AbsoluteTiming

Out[3]= {0.190705, {[image], [image], [image], [image], [image]}}
```

### Applications (1)

Build an image captioning function using the counts of detected objects:

```wl
In[1]:= detections = Length /@ ImageCases[[image]]

Out[1]= <|Entity["Concept", "Elephant::72b52"] -> 3, Entity["Concept", "Zebra::nx5qr"] -> 3|>
```

Transform the object counts in a string:

```wl
In[2]:=
StringRiffle[KeyValueMap[
	{IntegerName[#2], Pluralize[#1["Name"], #2]}&, 
	detections
	], ", ", " "]

Out[2]= "three elephants, three zebras"
```

Package all the code in a function to automatically generate captions:

```wl
In[3]:=
imageCaption[i_Image] := 
	With[
	{detections = Length /@ ImageCases[i]}, 
	If[Length[detections] == 0, 
	"An image with no identified objects.", 
	StringJoin[
	"An image with ", 
	Riffle[Riffle[KeyValueMap[
	StringRiffle[{IntegerName[#2], Pluralize[#1["Name"], #2]}]&, 
	detections
	], ", ", {2, -3, 2}], " and ", {-2, -2, 1}], 
	"."
	]
	]
	]

In[4]:= imageCaption[[image]]

Out[4]= "An image with three elephants and three zebras."
```

Try the function on a different image:

```wl
In[5]:= imageCaption[[image]]

Out[5]= "An image with two forks, four bowls, one cup, one dining table, one knife and one spoon."
```

Caption an image with no identified objects:

```wl
In[6]:= imageCaption[[image]]

Out[6]= "An image with no identified objects."
```

## See Also

* [`FindFaces`](https://reference.wolfram.com/language/ref/FindFaces.en.md)
* [`FindImageText`](https://reference.wolfram.com/language/ref/FindImageText.en.md)
* [`ImageContents`](https://reference.wolfram.com/language/ref/ImageContents.en.md)
* [`ImageBoundingBoxes`](https://reference.wolfram.com/language/ref/ImageBoundingBoxes.en.md)
* [`ImagePosition`](https://reference.wolfram.com/language/ref/ImagePosition.en.md)
* [`ImageIdentify`](https://reference.wolfram.com/language/ref/ImageIdentify.en.md)
* [`HighlightImage`](https://reference.wolfram.com/language/ref/HighlightImage.en.md)
* [`ImageContainsQ`](https://reference.wolfram.com/language/ref/ImageContainsQ.en.md)
* [`TextCases`](https://reference.wolfram.com/language/ref/TextCases.en.md)
* [`Cases`](https://reference.wolfram.com/language/ref/Cases.en.md)

## Related Guides

* [Computer Vision](https://reference.wolfram.com/language/guide/ComputerVision.en.md)
* [Segmentation Analysis](https://reference.wolfram.com/language/guide/SegmentationAnalysis.en.md)
* [Image Computation: Update History](https://reference.wolfram.com/language/guide/ImageComputation-UpdateHistory.en.md)
* [Machine Learning](https://reference.wolfram.com/language/guide/MachineLearning.en.md)
* [Video Computation: Update History](https://reference.wolfram.com/language/guide/VideoComputation-UpdateHistory.en.md)
* [Video Analysis](https://reference.wolfram.com/language/guide/VideoAnalysis.en.md)

## Related Links

* [Wolfram Neural Net Repository: Object Detection Models](https://resources.wolframcloud.com/NeuralNetRepository/tasktype/Object-Detection/)

## History

* [Introduced in 2019 (12.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn120.en.md) \| [Updated in 2024 (14.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn140.en.md) ▪ [2025 (14.2)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn142.en.md)