Datastore for extracting random patches from images or pixel label images


A randomPatchExtractionDatastore extracts corresponding randomly-positioned patches from two datastores. The input datastores can be two image datastores that contain the network inputs and desired network responses for training deep neural networks, or ground truth images and pixel label data for training semantic segmentation networks.

This object requires that you have Deep Learning Toolbox™.


When you use a randomPatchExtractionDatastore as a source of training data, the datastore extracts multiple random patches from each image for each epoch, so that each epoch uses a slightly different data set. The actual number of training patches at each epoch is the number of training images multiplied by PatchesPerImage. The image patches are not stored in memory.



patchds = randomPatchExtractionDatastore(imds1,imds2,patchSize)
patchds = randomPatchExtractionDatastore(imds1,pxds,patchSize)
patchds = randomPatchExtractionDatastore(___,Name,Value)



patchds = randomPatchExtractionDatastore(imds1,imds2,patchSize) creates a datastore that extracts randomly-positioned patches of size patchSize from images in image datastore imds1 and corresponding patches from images in image datastore imds2.


patchds = randomPatchExtractionDatastore(imds1,pxds,patchSize) creates a datastore that extracts randomly-positioned patches of size patchSize from ground truth images in image datastore imds1 and corresponding patches from pixel label images in pixel label datastore pxds.

This syntax requires Computer Vision Toolbox™.

patchds = randomPatchExtractionDatastore(___,Name,Value) uses name-value pairs to set the PatchesPerImage, DataAugmentation, and DispatchInBackground properties. You can specify multiple name-value pairs. Enclose each argument or property name in quotes.

For example, randomPatchExtractionDatastore(imds1,imds2,50,'PatchesPerImage',40) creates a datastore that randomly generates 40 patches of size 50-by-50 pixels from each image in image datastores imds1 and imds2.

Input Arguments

expand all

Input image data containing training input to the network, specified as an ImageDatastore object.

ImageDatastore allows batch-reading of JPG or PNG image files using prefetching. If you use a custom function for reading the images, then prefetching does not happen.

Response image data representing the desired network responses, specified as an ImageDatastore object.

Response pixel label data representing the desired network responses, specified as a pixelLabelDatastore object.

Patch size, specified as one of the following.

  • A positive integer that specifies the number of rows and columns of square patches.

  • A 2-element vector of positive integers, of the form [r c]. The first element specifies the number of rows in the patch, and the second element specifies the number of columns.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32


expand all

Number of random patches per image, specified as a positive integer.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32

Preprocessing applied to input images, specified as an imageDataAugmenter object or 'none'. When DataAugmentation is 'none', no preprocessing is applied to input images.

Augment data with random transformations, such as resizing, rotation, and reflection, to help prevent the network from overfitting and memorizing the exact details of the training data. The randomPatchExtractionDatastore applies the same random transformation to both patches in each pair.

Dispatch observations in the background during training, prediction, or classification, specified as false or true. To use background dispatching, you must have Parallel Computing Toolbox™.

This property is read-only.

Number of observations that are returned in each batch. For training, prediction, and classification, the MiniBatchSize property is set to the mini-batch size defined in trainingOptions.

This property is read-only.

Total number of observations in the randomPatchExtractionDatastore. The number of observations is the length of one training epoch.

Object Functions

hasdataDetermine if data is available to read
partitionByIndexPartition randomPatchExtractionDatastore according to indices
previewSubset of data in datastore
readRead data from randomPatchExtractionDatastore
readallRead all data in datastore
readByIndexRead data specified by index from randomPatchExtractionDatastore
resetReset datastore to initial state
shuffleShuffle data in randomPatchExtractionDatastore


collapse all

Create an image datastore containing training images. The datastore in this example contains JPEG color images.

imageDir = fullfile(toolboxdir('images'),'imdata');
imds1 = imageDatastore(imageDir,'FileExtensions','.jpg');

Create a second image datastore containing desired network responses. This image datastore includes a custom read function called myreadfcn (defined at the end of the example) that smooths images using a Gaussian blur.

imds2 = imageDatastore(imageDir,'FileExtensions','.jpg','ReadFcn',@myreadfcn);

Create an imageDataAugmenter that rotates images by random angles in the range [0, 90] degrees and randomly reflects image data horizontally.

augmenter = imageDataAugmenter('RandRotation',[0 90],'RandXReflection',true)
augmenter = 
  imageDataAugmenter with properties:

           FillValue: 0
     RandXReflection: 1
     RandYReflection: 0
        RandRotation: [0 90]
           RandScale: [1 1]
          RandXScale: [1 1]
          RandYScale: [1 1]
          RandXShear: [0 0]
          RandYShear: [0 0]
    RandXTranslation: [0 0]
    RandYTranslation: [0 0]

Create a randomPatchExtractionDatastore object that extracts random patches of size [100 100] from the unprocessed training images and corresponding smoothed response images. Specify the augmentation options by setting the DataAugmentation property.

patchds = randomPatchExtractionDatastore(imds1,imds2,[100 100], ...
patchds = 
  randomPatchExtractionDatastore with properties:

         PatchesPerImage: 128
               PatchSize: [100 100]
        DataAugmentation: [1×1 imageDataAugmenter]
           MiniBatchSize: 128
         NumObservations: 4736
    DispatchInBackground: 0

Preview a set of augmented image patches and the corresponding smoothed image patches.

minibatch = preview(patchds);
inputs = minibatch.InputImage;
responses = minibatch.ResponseImage;
test = cat(2,inputs,responses);
montage(test','Size',[8 2])
title('Inputs (Left) and Responses (Right)')

Supporting Function

This example defines the myreadfcn function that reads a file from disk then smooths the image by appling a Gaussian blur. The function returns the smoothed image.

function J = myreadfcn(filename)
    I = imread(filename);
    J = imgaussfilt(I,2);

Create an image datastore containing training images.

dataDir = fullfile(toolboxdir('vision'),'visiondata','triangleImages');
imageDir = fullfile(dataDir,'trainingImages');
imds = imageDatastore(imageDir);

Define class names and their associated label IDs. Then, create a pixel label datastore containing the ground truth pixel labels for the training images.

classNames = ["triangle","background"];
labelIDs = [255 0];
labelDir = fullfile(dataDir,'trainingLabels');
pxds = pixelLabelDatastore(labelDir,classNames,labelIDs);

Create a random patch extraction datastore to extract random patches of size 32-by-32 pixels from the images and corresponding pixel labels. Set the optional PatchesPerImage property to extract 512 random patches from each image and pixel label pair.

patchds = randomPatchExtractionDatastore(imds,pxds,32, ...

Create a network for semantic segmentation.

layers = [
    imageInputLayer([32 32 1])
layers = 
  10x1 Layer array with layers:

     1   ''   Image Input                  32x32x1 images with 'zerocenter' normalization
     2   ''   Convolution                  64 3x3 convolutions with stride [1  1] and padding [1  1  1  1]
     3   ''   ReLU                         ReLU
     4   ''   Max Pooling                  2x2 max pooling with stride [2  2] and padding [0  0  0  0]
     5   ''   Convolution                  64 3x3 convolutions with stride [1  1] and padding [1  1  1  1]
     6   ''   ReLU                         ReLU
     7   ''   Transposed Convolution       64 4x4 transposed convolutions with stride [2  2] and output cropping [1  1]
     8   ''   Convolution                  2 1x1 convolutions with stride [1  1] and padding [0  0  0  0]
     9   ''   Softmax                      softmax
    10   ''   Pixel Classification Layer   Cross-entropy loss 

Set up training options. To reduce training time, set MaxEpochs to 5.

options = trainingOptions('sgdm', ...
    'InitialLearnRate',1e-3, ...
    'MaxEpochs',5, ...

Train the network.

net = trainNetwork(patchds,layers,options);


  • The randomPatchExtractionDatastore expects that the output from the read operation on the input datastores return arrays of the same size.

  • The randomPatchExtractionDatastore always reads one image at a time from each input datastore. It accomplishes this by setting the ReadSize property of the input datastores to 1.

  • If the input datastore is an ImageDatastore, then the values in its Labels property are ignored by the randomPatchExtractionDatastore.

  • To visualize the data in a randomPatchExtractionDatastore, you can use the preview function, which returns a subset of data in a table. Visualize all of the patches in the same figure by using the montage function. For example, this code displays a preview of image patches from a randomPatchExtractionDatastore called patchds.

    minibatch = preview(patchds);

Introduced in R2018b