How to Use Mask R-CNN in Keras for Object Detection in Photographs

Last Updated on

Object detection is a task in computer vision that involves identifying the presence, location, and type of one or more objects in a given photograph.

It is a challenging problem that involves building upon methods for object recognition (e.g. where are they), object localization (e.g. what are their extent), and object classification (e.g. what are they).

In recent years, deep learning techniques have achieved state-of-the-art results for object detection, such as on standard benchmark datasets and in computer vision competitions. Most notably is the R-CNN, or Region-Based Convolutional Neural Networks, and the most recent technique called Mask R-CNN that is capable of achieving state-of-the-art results on a range of object detection tasks.

In this tutorial, you will discover how to use the Mask R-CNN model to detect objects in new photographs.

After completing this tutorial, you will know:

  • The region-based Convolutional Neural Network family of models for object detection and the most recent variation called Mask R-CNN.
  • The best-of-breed open source library implementation of the Mask R-CNN for the Keras deep learning library.
  • How to use a pre-trained Mask R-CNN to perform object localization and detection on new photographs.

Discover how to build models for photo classification, object detection, face recognition, and more in my new computer vision book, with 30 step-by-step tutorials and full source code.

Let’s get started.

  • Note: This tutorial requires TensorFlow version 1.14 or higher. It currently does not work with TensorFlow 2 because some third-party libraries have not been updated at the time of writing.
How to Perform Object Detection in Photographs With Mask R-CNN in Keras

How to Perform Object Detection in Photographs With Mask R-CNN in Keras
Photo by Ole Husby, some rights reserved.

Tutorial Overview

This tutorial is divided into three parts; they are:

  1. R-CNN and Mask R-CNN
  2. Matterport Mask R-CNN Project
  3. Object Detection with Mask R-CNN

Want Results with Deep Learning for Computer Vision?

Take my free 7-day email crash course now (with sample code).

Click to sign-up and also get a free PDF Ebook version of the course.

Download Your FREE Mini-Course

Mask R-CNN for Object Detection

Object detection is a computer vision task that involves both localizing one or more objects within an image and classifying each object in the image.

It is a challenging computer vision task that requires both successful object localization in order to locate and draw a bounding box around each object in an image, and object classification to predict the correct class of object that was localized.

An extension of object detection involves marking the specific pixels in the image that belong to each detected object instead of using coarse bounding boxes during object localization. This harder version of the problem is generally referred to as object segmentation or semantic segmentation.

The Region-Based Convolutional Neural Network, or R-CNN, is a family of convolutional neural network models designed for object detection, developed by Ross Girshick, et al.

There are perhaps four main variations of the approach, resulting in the current pinnacle called Mask R-CNN. The salient aspects of each variation can be summarized as follows:

  • R-CNN: Bounding boxes are proposed by the “selective search” algorithm, each of which is stretched and features are extracted via a deep convolutional neural network, such as AlexNet, before a final set of object classifications are made with linear SVMs.
  • Fast R-CNN: Simplified design with a single model, bounding boxes are still specified as input, but a region-of-interest pooling layer is used after the deep CNN to consolidate regions and the model predicts both class labels and regions of interest directly.
  • Faster R-CNN: Addition of a Region Proposal Network that interprets features extracted from the deep CNN and learns to propose regions-of-interest directly.
  • Mask R-CNN: Extension of Faster R-CNN that adds an output model for predicting a mask for each detected object.

The Mask R-CNN model introduced in the 2018 paper titled “Mask R-CNN” is the most recent variation of the family models and supports both object detection and object segmentation. The paper provides a nice summary of the model linage to that point:

The Region-based CNN (R-CNN) approach to bounding-box object detection is to attend to a manageable number of candidate object regions and evaluate convolutional networks independently on each RoI. R-CNN was extended to allow attending to RoIs on feature maps using RoIPool, leading to fast speed and better accuracy. Faster R-CNN advanced this stream by learning the attention mechanism with a Region Proposal Network (RPN). Faster R-CNN is flexible and robust to many follow-up improvements, and is the current leading framework in several benchmarks.

Mask R-CNN, 2018.

The family of methods may be among the most effective for object detection, achieving then state-of-the-art results on computer vision benchmark datasets. Although accurate, the models can be slow when making a prediction as compared to alternate models such as YOLO that may be less accurate but are designed for real-time prediction.

Matterport Mask R-CNN Project

Mask R-CNN is a sophisticated model to implement, especially as compared to a simple or even state-of-the-art deep convolutional neural network model.

Source code is available for each version of the R-CNN model, provided in separate GitHub repositories with prototype models based on the Caffe deep learning framework. For example:

Instead of developing an implementation of the R-CNN or Mask R-CNN model from scratch, we can use a reliable third-party implementation built on top of the Keras deep learning framework.

The best of breed third-party implementations of Mask R-CNN is the Mask R-CNN Project developed by Matterport. The project is open source released under a permissive license (i.e. MIT license) and the code has been widely used on a variety of projects and Kaggle competitions.

Nevertheless, it is an open source project, subject to the whims of the project developers. As such, I have a fork of the project available, just in case there are major changes to the API in the future.

The project is light on API documentation, although it does provide a number of examples in the form of Python Notebooks that you can use to understand how to use the library by example. Two notebooks that may be helpful to review are:

There are perhaps three main use cases for using the Mask R-CNN model with the Matterport library; they are:

  • Object Detection Application: Use a pre-trained model for object detection on new images.
  • New Model via Transfer Learning: Use a pre-trained model as a starting point in developing a model for a new object detection dataset.
  • New Model from Scratch: Develop a new model from scratch for an object detection dataset.

In order to get familiar with the model and the library, we will look at the first example in the next section.

Object Detection With Mask R-CNN

In this section, we will use the Matterport Mask R-CNN library to perform object detection on arbitrary photographs.

Much like using a pre-trained deep CNN for image classification, e.g. such as VGG-16 trained on an ImageNet dataset, we can use a pre-trained Mask R-CNN model to detect objects in new photographs. In this case, we will use a Mask R-CNN trained on the MS COCO object detection problem.

Mask R-CNN Installation

The first step is to install the library.

At the time of writing, there is no distributed version of the library, so we have to install it manually. The good news is that this is very easy.

Installation involves cloning the GitHub repository and running the installation script on your workstation. If you are having trouble, see the installation instructions buried in the library’s readme file.

Step 1. Clone the Mask R-CNN GitHub Repository

This is as simple as running the following command from your command line:

This will create a new local directory with the name Mask_RCNN that looks as follows:

Step 2. Install the Mask R-CNN Library

The library can be installed directly via pip.

Change directory into the Mask_RCNN directory and run the installation script.

From the command line, type the following:

On Linux or MacOS you may need to install the software with sudo permissions; for example, you may see an error such as:

In that case, install the software with sudo:

The library will then install directly and you will see a lot of successful installation messages ending with the following:

This confirms that you installed the library successfully and that you have the latest version, which at the time of writing is version 2.1.

Step 3: Confirm the Library Was Installed

It is always a good idea to confirm that the library was installed correctly.

You can confirm that the library was installed correctly by querying it via the pip command; for example:

You should see output informing you of the version and installation location; for example:

We are now ready to use the library.

Example of Object Localization

We are going to use a pre-trained Mask R-CNN model to detect objects on a new photograph.

Step 1. Download Model Weights

First, download the weights for the pre-trained model, specifically a Mask R-CNN trained on the MS Coco dataset.

The weights are available from the project GitHub project and the file is about 250 megabytes. Download the model weights to a file with the name ‘mask_rcnn_coco.h5‘ in your current working directory.

Step 2. Download Sample Photograph

We also need a photograph in which to detect objects.

We will use a photograph from Flickr released under a permissive license, specifically a photograph of an elephant taken by Mandy Goldberg.

Download the photograph to your current working directory with the filename ‘elephant.jpg‘.


Elephant (elephant.jpg)
Taken by Mandy Goldberg, some rights reserved.

Step 3. Load Model and Make Prediction

First, the model must be defined via an instance MaskRCNN class.

This class requires a configuration object as a parameter. The configuration object defines how the model might be used during training or inference.

In this case, the configuration will only specify the number of images per batch, which will be one, and the number of classes to predict.

You can see the full extent of the configuration object and the properties that you can override in the file.

We can now define the MaskRCNN instance.

We will define the model as type “inference” indicating that we are interested in making predictions and not training. We must also specify a directory where any log messages could be written, which in this case will be the current working directory.

The next step is to load the weights that we downloaded.

Now we can make a prediction for our image. First, we can load the image and convert it to a NumPy array.

We can then make a prediction with the model. Instead of calling predict() as we would on a normal Keras model, will call the detect() function and pass it the single image.

The result contains a dictionary for each image that we passed into the detect() function, in this case, a list of a single dictionary for the one image.

The dictionary has keys for the bounding boxes, masks, and so on, and each key points to a list for multiple possible objects detected in the image.

The keys of the dictionary of note are as follows:

  • rois‘: The bound boxes or regions-of-interest (ROI) for detected objects.
  • masks‘: The masks for the detected objects.
  • class_ids‘: The class integers for the detected objects.
  • scores‘: The probability or confidence for each predicted class.

We can draw each box detected in the image by first getting the dictionary for the first image (e.g. results[0]), and then retrieving the list of bounding boxes (e.g. [‘rois’]).

Each bounding box is defined in terms of the bottom left and top right coordinates of the bounding box in the image

We can use these coordinates to create a Rectangle() from the matplotlib API and draw each rectangle over the top of our image.

To keep things neat, we can create a function to do this that will take the filename of the photograph and the list of bounding boxes to draw and will show the photo with the boxes.

We can now tie all of this together and load the pre-trained model and use it to detect objects in our photograph of an elephant, then draw the photograph with all detected objects.

The complete example is listed below.

Running the example loads the model and performs object detection. More accurately, we have performed object localization, only drawing bounding boxes around detected objects.

In this case, we can see that the model has correctly located the single object in the photo, the elephant, and drawn a red box around it.

Photograph of an Elephant With All Objects Localized With a Bounding Box

Photograph of an Elephant With All Objects Localized With a Bounding Box

Example of Object Detection

Now that we know how to load the model and use it to make a prediction, let’s update the example to perform real object detection.

That is, in addition to localizing objects, we want to know what they are.

The Mask_RCNN API provides a function called display_instances() that will take the array of pixel values for the loaded image and the aspects of the prediction dictionary, such as the bounding boxes, scores, and class labels, and will plot the photo with all of these annotations.

One of the arguments is the list of predicted class identifiers available in the ‘class_ids‘ key of the dictionary. The function also needs a mapping of ids to class labels. The pre-trained model was fit with a dataset that had 80 (81 including background) class labels, helpfully provided as a list in the Mask R-CNN Demo, Notebook Tutorial, listed below.

We can then provide the details of the prediction for the elephant photo to the display_instances() function; for example:

The display_instances() function is flexible, allowing you to only draw the mask or only the bounding boxes. You can learn more about this function in the source file.

The complete example with this change using the display_instances() function is listed below.

Running the example shows the photograph of the elephant with the annotations predicted by the Mask R-CNN model, specifically:

  • Bounding Box. Dotted bounding box around each detected object.
  • Class Label. Class label assigned each detected object written in the top left corner of the bounding box.
  • Prediction Confidence. Confidence of class label prediction for each detected object written in the top left corner of the bounding box.
  • Object Mask Outline. Polygon outline for the mask of each detected object.
  • Object Mask. Polygon fill for the mask of each detected object.

The result is very impressive and sparks many ideas for how such a powerful pre-trained model could be used in practice.

Photograph of an Elephant With All Objects Detected With a Bounding Box and Mask

Photograph of an Elephant With All Objects Detected With a Bounding Box and Mask

Further Reading

This section provides more resources on the topic if you are looking to go deeper.




R-CNN Code Repositories


In this tutorial, you discovered how to use the Mask R-CNN model to detect objects in new photographs.

Specifically, you learned:

  • The region-based Convolutional Neural Network family of models for object detection and the most recent variation called Mask R-CNN.
  • The best-of-breed open source library implementation of the Mask R-CNN for the Keras deep learning library.
  • How to use a pre-trained Mask R-CNN to perform object localization and detection on new photographs.

Do you have any questions?
Ask your questions in the comments below and I will do my best to answer.

Develop Deep Learning Models for Vision Today!

Deep Learning for Computer Vision

Develop Your Own Vision Models in Minutes

...with just a few lines of python code

Discover how in my new Ebook:
Deep Learning for Computer Vision

It provides self-study tutorials on topics like:
classification, object detection (yolo and rcnn), face recognition (vggface and facenet), data preparation and much more...

Finally Bring Deep Learning to your Vision Projects

Skip the Academics. Just Results.

See What's Inside

40 Responses to How to Use Mask R-CNN in Keras for Object Detection in Photographs

  1. steve vaius May 24, 2019 at 7:09 pm #

    Good job! Wonderful article on subject. I would like to thank you first of all to your efforts. But wondering how text recognition can be implemented ( ie. for road side ads)?. How custom training dataset should be prepared?(images and labeling of them) Any source and help welcomed.

    • Jason Brownlee May 25, 2019 at 7:46 am #


      Good question, you can first perform object recognition to find the text, then use a model such as a CNN-LSTM to read off the text. Perhaps even segment each letter in the text and read them off one by one.

  2. Jason May 24, 2019 at 8:01 pm #

    Any prerequisites?

  3. SHAHEEN ALHIRMIZY May 27, 2019 at 12:11 am #

    Thank You Very Much May God Bless you for your great efforts in computer vision field one more thing if you can explain for us how to use concatenate and deconvolution in separate article

    • Jason Brownlee May 27, 2019 at 6:49 am #


      Yes, I have tutorials scheduled on these topics.

  4. Isabel June 21, 2019 at 9:30 pm #

    Dear Jason.

    I’m trying to apply mask in my project.
    I have this type of structure folder:

    ── train
    ├── class_1
    ├── class_2
    ├── class_3

    Where are the objects coordinates ?
    And what is the format? [ 1, 1, 1, 1] (1,1,1,1)

  5. Sourabh Prakash June 22, 2019 at 6:26 am #

    Dear Jason, it was very well explained. Thank you.
    I want to write the code for mask RCNN from the scratch using tensorflow-keras, can you suggest me how to proceed? Is there any resource or article that can help me in this.

    • Jason Brownlee June 22, 2019 at 6:51 am #

      Perhaps start with the paper and try to understand each step well.

  6. Drizzt June 25, 2019 at 11:52 am #

    Dear Jason:
    I’ve got an err while running the code below:

    rcnn = MaskRCNN(mode=’inference’, model_dir=’./’, config=TestConfig())

    The error is : ValueError: Tried to convert ‘shape’ to a tensor and failed. Error: None values not supported.

    I‘m running whith Tensorflow 1.13 and Keras 2.2.4 . And mask-rcnn 2.1 seems installed correctly.

    I’m confused because you said it worked with tf 1.13

    • Jason Brownlee June 25, 2019 at 2:22 pm #

      Sorry to hear that, I can confirm it works with TF 1.13.

      Are you using Python 3.6?
      Are you running from the command line?
      Did you copy all of the code from the example?

      I have some more suggestions here that may help:

      • Drizzt June 25, 2019 at 7:53 pm #

        I’m using Python 3.7 but i don’t think it matters. I’ve copy all of the code and run them in PyCharm .
        I’ll reset my environment and try this tutorial again , because i used TF2.0-gpu and then changed to TF1.13-gpu and then to TF 1.13 .

        Thank you for your help. Your tutorials really help me a lot. They works with TF 2.0-gpu beta well, most time I only need to change “import keras.XX” to “import tensorflow.keras.XX”. That’s great!

        • Jason Brownlee June 26, 2019 at 6:40 am #

          I recommend running from the command line not from a notebook or IDE, more here:

          • PK July 26, 2019 at 2:13 am #

            Thanks much for the article. I’ve an object detection code working on TF 1.xx, and I’m trying to port that to TF 2.beta. Followed the tf.upgrade_v2 commands…; but stuck finally with “keras.engine as KE” in the file. Any help on what all changes to be made for the code to run would really be appreciated.

          • Jason Brownlee July 26, 2019 at 8:28 am #

            Sorry, I don’t have tutorials on TF, let alone converting from one API to another.

            Perhaps try the TF user group or stackoverflow?

  7. Vijay July 1, 2019 at 12:19 pm #

    Hi ,thank you so much for this tutorial,I have. h5 file to classify blood cells, is it possible to load that weight to rcnn.load_weights(‘blood.h5) and detect mask?

    • Jason Brownlee July 2, 2019 at 7:27 am #

      If the saved model is a Mask RCNN model, then perhaps yes.

  8. Vijay July 1, 2019 at 2:48 pm #

    Hi Jason, how to apply this for own dataset.thanks

  9. Sai July 2, 2019 at 6:52 pm #

    Hi Mr. Jason, I’ve found that there are so many different algorithms were published in 2019 for Instance Segmentation like HTC and last year we have PANET..etc. So, how efficient is it we use MaskRCNN still to develop for different outputs. What is your opinion on MRCNN. Give me an advise. Thank you.

    • Jason Brownlee July 3, 2019 at 8:31 am #

      I think Mask R-CNN is great.

      If you want to try other methods, go for it – but it can be very time and resource consuming.

  10. mahmoud July 9, 2019 at 10:46 pm #

    thank you very match for sharing your knowledge ,my question is i want to change the training data and the classes name because i have different problem and i need to implement this method to detect the objects

    my problem that i need to detect objects which is really similar to the background it is like very small circular,and the model have failed to detect them so i think i need adaptation on this method.

  11. Latha August 6, 2019 at 5:50 am #

    Excellent tutorial.
    I’m getting this error

    rcnn.load_weights(‘mask_rcnn_coco.h5’, by_name=True
    >>> rcnn.load_weights(‘mask_rcnn_coco.h5′, by_name=True)
    Traceback (most recent call last):
    File “”, line 1, in
    File “C:\Users\srtangel\Documents\OpenCV\Code\Mask_RCNN\mrcnn\”, line 2115, in load_weights
    f = h5py.File(filepath, mode=’r’)
    File “C:\Users\srtangel\Anaconda\envs\facecourse-py3\lib\site-packages\h5py\_hl\”, line 394, in __init__
    File “C:\Users\srtangel\Anaconda\envs\facecourse-py3\lib\site-packages\h5py\_hl\”, line 170, in make_fid
    fid =, flags, fapl=fapl)
    File “h5py\_objects.pyx”, line 54, in h5py._objects.with_phil.wrapper
    File “h5py\_objects.pyx”, line 55, in h5py._objects.with_phil.wrapper
    File “h5py\h5f.pyx”, line 85, in
    OSError: Unable to open file (file signature not found)

  12. Arelis August 14, 2019 at 11:19 pm #

    Thank you. I like so much.

  13. Stan October 11, 2019 at 7:03 pm #

    Thanks for nice tutorial.

    Am I always restricted to the ‘resnet’ or other pre-built architecture within the FPN? Is there are a way to incorporate an arbitrary Conv. network into mrcnn-FPN structure? It looks that people use mrcnn in different projects. So far, however, I noticed only different types of resnet and vgg (not fully sure).

    • Jason Brownlee October 12, 2019 at 6:52 am #

      I don’t see why not. You might have to dig into the mask rcnn code a bit to swap out the feature extractor model.

  14. saka October 15, 2019 at 2:10 pm #

    Dear Jason, Thanks! I really learned a lot.

    How do I apply Mask R-CNN on Binary class, that is, people or nothing on images.

    I have tried to implement it by setting NUM_CLASSES = 1 + 1 (background and people), however I got error as below,

    ValueError: Layer #389 (named “mrcnn_bbox_fc”), weight has shape (1024, 8), but the saved weight has shape (1024, 324).

Leave a Reply