habana_frameworks.mediapipe.fn.ReadImageDatasetFromDir

Class:
  • habana_frameworks.mediapipe.fn.ReadImageDatasetFromDir(**kwargs)

Define graph call:
  • __call__()

Parameter:
  • None

Description:

This reader is designed for image classification tasks. There are two ways to provide input to ReadImageDatasetFromDir:

  • By specifying input directory path. Sub-directory names will be considered as class_label for all the images in it.

  • By providing file_list, class_list and file_classes to the reader

Reader returns batches of image path and ground truth labels. Output ground truth labels are a list of integers representing class lables of images.

Supported backend:
  • CPU

Keyword Arguments

kwargs

Description

shuffle

If set to True, the reader shuffles the entire dataset before each epoch. In case of multi-card training, it first creates random slices/chunk of files for every card then shuffle.

  • Type: bool

  • Default: True

  • Optional: yes

seed

Seed for randomization. If not provided it will be generated internally. It is used for shuffling the dataset and it is also used for randomly selecting the images to pad the last batch when the drop_reminder is False and pad_reminder is False.

  • Type: int

  • Optional: yes

max_file

Full path of biggest input file. This is used for pre-allocating buffer. If not provided, reader will find it.

  • Type: str

  • Default: None

  • Optional: yes

  • Note: This feature is provided to optimize reading time, especially in case of bigger datasets.

drop_remainder

If True, reader will drop the last partial batch of the epoch. If false - padding mechanism can be controlled by pad_reminder.

  • Type: bool

  • Default: False

  • Optional: yes

pad_remainder

If True then reader will replicate last image of partial batch. If false then partial batch is filled with images randomly selected from dataset.

  • Type: bool

  • Default: False

  • Optional: yes

  • Node: pad reminder is valid when drop reminder is false

label_dtype

Required data type of output ground truth labels. Reader returns batch of image file path and ground truth labels. Output ground truth labels are list of integers, which specifies index of respective image’s class label in sorted list of all class labels. label_dtype specifies data type of these integers.

  • Type: habana_frameworks.mediapipe.media_types.dtype

  • Default: UINT64

  • Optional: yes

num_slices

It indicates number of cards in multi-card training. Before first epoch, input data is divided into num_slices chunks i.e. one chunk for every card. During entire training, same chunk will be used for that particular card for creating batches in every epoch. Default value is one, which indicates single card training.

  • Type: int

  • Default: 1

  • Optional: yes

slice_index

In multi-card training, it indicates index of card.

  • Type: int

  • Default: 0

  • Optional: yes (if num_slices=1, Otherwise user must provide it)

  • Note: Default value is zero for single card training. For multi-card it must be between 0 and num_slices -1.

dir

Input image directory path. Reader will read images from all sub-directories of dir. Name of sub-directory is treated as class label for all the images inside it.

  • Type: str

  • Default: None

  • Optional: yes (either provide dir or provide file_list)

  • Note: Arrange input files as dir_path/class_label/image files. For example, for training pipeline input images are “/user/home/images/train/<class_label>/<image_name>.jpg”, give dir= “/user/home/images/train/”. There may be multiple sub-directories inside “/user/home/images/train/”, one for every class_label.

format

Format or extension of image file names. It will be used to list-out all the images in sub-directories of “dir”.

  • Type: str

  • Default: “jpg”

  • Optional: no

  • Note: Supported image file extensions are “jpg”, “jpeg”

file_list

In-place of providing dir (input image directory path), user can provide list of files to reader.

  • Type: list

  • Default: None

  • Optional: yes

  • Note: file_list must be ordered by class_list i.e. list all the files of class_1 followed by all the files of class_2 and so on.

  • Note: file_list should have full path of all the files. Example [“/path/to/dataset/class_1/img_c1_0.jpg”, “/path/to/dataset/class_1/img_c1_1.jpg”, “/path/to/dataset/class_2/img_c2_0.jpg”, “/path/to/dataset/class_2/img_c2_1.jpg”, …..]

class_list

List of unique class labels must be provided along with file_list. It will be used as a look-up table to generate output ground truth labels.

  • Type: list

  • Default: None

  • Optional: yes (If file_list is provided, class_list is not optional)

  • Note: Output ground truth labels will be index of respective image’s class_label in this class_list. This means, it will act as a look-up table to generate output ground truth labels.

file_sizes

Optional dictionary of file path & file sizes for every file in file_list. If provided, it will be used to compute max_file_size. If not provided reader will find max_file_size itself. max_file_size is used for pre-allocating decoder buffers.

  • Type: dict

  • Default: None

  • Optional: yes

  • Note: This feature is provided to optimize reader time, useful especially in case of bigger datasets.

file_classes

List of class name for every file in file_list. It will be used to generate output ground truth labels. If not provided, last sub-directory name from file_list will be used to generate file_classes.

  • Type: list

  • Default: None

  • Optional: yes

  • Note: For example file_list is provided but file_classes is not provided, file_list=[“/path/to/dataset/class_1/img_c1_0.jpg”, “/path/to/dataset/class_1/img_c1_1.jpg”, “/path/to/dataset/class_2/img_c2_0.jpg”, “/path/to/dataset/class_2/img_c2_1.jpg”, …..]

    In that case Reader will generate file_classes = [“class_1”, “class_1”, “class_2”, “class_2”, …] from last sub-directory name of every image in file_list.

Example #1: Use ReadImageDatasetFromDir by Providing Input Directory

The following code snippet shows use of ReadImageDatasetFromDir by providing input image directory path. Input jpg images are present in sub directories of “//path/to/dataset/”. For example “/path/to/dataset/class_1/img_c1_0.jpg” “/path/to/dataset/class_1/img_c1_1.jpg” “/path/to/dataset/class_1/img_c1_2.jpg” “/path/to/dataset/class_2/img_c2_0.jpg” “/path/to/dataset/class_2/img_c2_1.jpg” “/path/to/dataset/class_2/img_c2_2.jpg”

fn.ReadImageDatasetFromDir(shuffle=False, dir="/path/to/dataset/", format="jpg")

Since the format="jpg", the reader will process all “jpg” files in the sub-directories of dir. Names of sub-directories are considered as class_label for all the images in it. Reader internally creates class_list which is a sorted list of unique class_labels (i.e. sorted list of unique sub-directory names). class_list is used as a dictionary to generate output ground truth labels. Output ground truth label of every image is index of image class_label in class_list (i.e. index of sub-directory name in which that image is present in class_list) In below example reader is returning ground truth label for every image, which is displayed as align title of that image.

import matplotlib.pyplot as plt
from habana_frameworks.mediapipe import fn
from habana_frameworks.mediapipe.mediapipe import MediaPipe
from habana_frameworks.mediapipe.media_types import imgtype as it
from habana_frameworks.mediapipe.media_types import dtype as dt
import os


g_display_timeout = os.getenv("DISPLAY_TIMEOUT") or 5

# Create MediaPipe derived class
class myMediaPipe(MediaPipe):
    def __init__(self, device, queue_depth, batch_size, num_threads, op_device, dir, img_h, img_w):
        super(
            myMediaPipe,
            self).__init__(
            device,
            queue_depth,
            batch_size,
            num_threads,
            self.__class__.__name__)
        self.input = fn.ReadImageDatasetFromDir(shuffle=False,
                                                dir=dir,
                                                format="jpg",
                                                device=op_device)

        self.decode = fn.ImageDecoder(device="hpu",
                                    output_format=it.RGB_I,
                                    resize=[img_w, img_h],
                                    dtype=dt.UINT8)

    def definegraph(self):
        images, labels = self.input()
        images = self.decode(images)
        return images, labels


def display_images(images, labels, batch_size, cols):
    rows = (batch_size + 1) // cols
    plt.figure(figsize=(10, 10))
    for i in range(batch_size):
        ax = plt.subplot(rows, cols, i + 1)
        plt.imshow(images[i])
        plt.title("label:"+str(labels[i]))
        plt.axis("off")
    plt.show(block=False)
    plt.pause(g_display_timeout)
    plt.close()


def run(device, op_device):
    batch_size = 6
    queue_depth = 2
    num_threads = 1
    img_width = 200
    img_height = 200
    base_dir = os.environ['DATASET_DIR']
    dir = base_dir + "/img_data/"
    columns = 3

    # Create MediaPipe object
    pipe = myMediaPipe(device, queue_depth, batch_size,
                    num_threads, op_device, dir,
                    img_height, img_width)

    pipe.build()
    pipe.iter_init()

    try:
        images, labels = pipe.run()
    except StopIteration:
        pass

    def as_cpu(tensor):
        if (callable(getattr(tensor, "as_cpu", None))):
            tensor = tensor.as_cpu()
        return tensor

    # Copy data to host from device as numpy array
    images = as_cpu(images).as_nparray()
    labels = as_cpu(labels).as_nparray()

    del pipe

    display_images(images, labels, batch_size, columns)


if __name__ == "__main__":
    dev_opdev = {'mixed': ['cpu'],
                'legacy': ['cpu']}

    for dev in dev_opdev.keys():
        for op_dev in dev_opdev[dev]:
            run(dev, op_dev)

Example #1: Output Images 1

label 0 label 0
label 0 label 0
label 0 label 0
label 1 label 1
label 1 label 1
label 1 label 1
1

Licensed under a CC BY SA 4.0 license. The images used here are taken from https://data.caltech.edu/records/mzrjq-6wc02.

Example #2: Use ReadImageDatasetFromDir by Providing file_list

The following code snippet shows an alternative method of using ReadImageDatasetFromDir by providing file_list and class_list:

  • file_list specifies list of files to process.

  • class_list must be provided along with file_list. It is list of unique class labels.

  • file_classes is list of class labels for every image.

Output ground truth labels will be index of image’s class label in class_list, which is shown as title of output images.

import matplotlib.pyplot as plt
from habana_frameworks.mediapipe import fn
from habana_frameworks.mediapipe.mediapipe import MediaPipe
from habana_frameworks.mediapipe.media_types import imgtype as it
from habana_frameworks.mediapipe.media_types import dtype as dt
import os

g_display_timeout = os.getenv("DISPLAY_TIMEOUT") or 5

class myMediaPipe(MediaPipe):
    def __init__(self, device, queue_depth, batch_size, num_threads, op_device, dir, img_h, img_w):
        super(
            myMediaPipe,
            self).__init__(
            device,
            queue_depth,
            batch_size,
            num_threads,
            self.__class__.__name__)

        file_list = [dir+"/cougar_body/image_0002.jpg",
                    dir+"/cougar_body/image_0039.jpg",
                    dir+"/cougar_body/image_0024.jpg",
                    dir+"/butterfly//image_0015.jpg",
                    dir+"/butterfly//image_0067.jpg",
                    dir+"/butterfly//image_0090.jpg"
                    ]

        class_list = ["cougar_body", "butterfly"]

        file_classes = ["cougar_body",
                        "cougar_body",
                        "cougar_body",
                        "butterfly",
                        "butterfly",
                        "butterfly"]

        self.input = fn.ReadImageDatasetFromDir(shuffle=False,
                                                file_list=file_list,
                                                class_list=class_list,
                                                file_classes=file_classes,
                                                format="jpg",
                                                device="cpu")

        self.decode = fn.ImageDecoder(device="hpu",
                                      output_format=it.RGB_I,
                                      resize=[img_w, img_h],
                                      dtype=dt.UINT8)

    def definegraph(self):
        images, labels = self.input()
        images = self.decode(images)
        return images, labels


def display_images(images, labels, batch_size, cols):
    rows = (batch_size + 1) // cols
    plt.figure(figsize=(10, 10))
    for i in range(batch_size):
        ax = plt.subplot(rows, cols, i + 1)
        plt.imshow(images[i])
        plt.title("label:"+str(labels[i]))
        plt.axis("off")
    plt.show(block=False)
    plt.pause(g_display_timeout)
    plt.close()


def run(device, op_device):
    batch_size = 6
    queue_depth = 2
    num_threads = 1
    img_width = 200
    img_height = 200
    base_dir = os.environ['DATASET_DIR']
    dir = base_dir + "/img_data/"
    columns = 3

    # Create MediaPipe object
    pipe = myMediaPipe(device, queue_depth, batch_size,
                      num_threads, op_device, dir,
                      img_height, img_width)

    pipe.build()
    pipe.iter_init()

    try:
        images, labels = pipe.run()
    except StopIteration:
        pass

    def as_cpu(tensor):
        if (callable(getattr(tensor, "as_cpu", None))):
            tensor = tensor.as_cpu()
        return tensor

    # Copy data to host from device as numpy array
    images = as_cpu(images).as_nparray()
    labels = as_cpu(labels).as_nparray()

    del pipe

    display_images(images, labels, batch_size, columns)


if __name__ == "__main__":
    dev_opdev = {'mixed': ['cpu'],
                'legacy': ['cpu']}

    for dev in dev_opdev.keys():
        for op_dev in dev_opdev[dev]:
            run(dev, op_dev)

Example #2: Output Images 2

label 0 label 0
label 0 label 0
label 0 label 0
label 1 label 1
label 1 label 1
label 1 label 1
2

Licensed under a CC BY SA 4.0 license. The images used here are taken from https://data.caltech.edu/records/mzrjq-6wc02.