# Image Interface

This file contains some common interfaces for image preprocess. Many users are confused about the image layout. We introduce the image layout as follows.

- CHW Layout

  - The abbreviations: C=channel, H=Height, W=Width
  - The default layout of image opened by cv2 or PIL is HWC. PaddlePaddle only supports the CHW layout. And CHW is simply a transpose of HWC. It must transpose the input image.

- Color format: RGB or BGR

  OpenCV use BGR color format. PIL use RGB color format. Both formats can be used for training. Noted that, the format should be keep consistent between the training and inference peroid.

`paddle.v2.image.``batch_images_from_tar`(data_file, dataset_name, img2label, num_per_batch=1024)

  Read images from tar file and batch them into batch file.

  参数:

  - data_file (string) – path of image tar file
  - dataset_name (string) – ‘train’,’test’ or ‘valid’
  - img2label (dic) – a dic with image file name as key and image’s label as value
  - num_per_batch (int) – image number per batch file

  返回: | path of list file containing paths of batch file
  返回类型: | string

`paddle.v2.image.``load_image_bytes`(bytes, is_color=True)

  Load an color or gray image from bytes array.

  Example usage:

      with open('cat.jpg') as f:
          im = load_image_bytes(f.read())

  参数:

  - bytes (str) – the input image bytes array.
  - is_color (bool) – If set is_color True, it will load and return a color image. Otherwise, it will load and return a gray image.

`paddle.v2.image.``load_image`(file, is_color=True)

  Load an color or gray image from the file path.

  Example usage:

      im = load_image('cat.jpg')

  参数:

  - file (string) – the input image path.
  - is_color (bool) – If set is_color True, it will load and return a color image. Otherwise, it will load and return a gray image.

`paddle.v2.image.``resize_short`(im, size)

  Resize an image so that the length of shorter edge is size.

  Example usage:

      im = load_image('cat.jpg')
      im = resize_short(im, 256)

  参数:

  - im (ndarray) – the input image with HWC layout.
  - size (int) – the shorter edge size of image after resizing.

`paddle.v2.image.``to_chw`(im, order=(2, 0, 1))

  Transpose the input image order. The image layout is HWC format opened by cv2 or PIL. Transpose the input image to CHW layout according the order (2,0,1).

  Example usage:

      im = load_image('cat.jpg')
      im = resize_short(im, 256)
      im = to_chw(im)

  参数:

  - im (ndarray) – the input image with HWC layout.
  - order (tuple|list) – the transposed order.

`paddle.v2.image.``center_crop`(im, size, is_color=True)

  Crop the center of image with size.

  Example usage:

      im = center_crop(im, 224)

  参数:

  - im (ndarray) – the input image with HWC layout.
  - size (int) – the cropping size.
  - is_color (bool) – whether the image is color or not.

`paddle.v2.image.``random_crop`(im, size, is_color=True)

  Randomly crop input image with size.

  Example usage:

      im = random_crop(im, 224)

  参数:

  - im (ndarray) – the input image with HWC layout.
  - size (int) – the cropping size.
  - is_color (bool) – whether the image is color or not.

`paddle.v2.image.``left_right_flip`(im)

  Flip an image along the horizontal direction. Return the flipped image.

  Example usage:

      im = left_right_flip(im)

  Paam im: | input image with HWC layout

`paddle.v2.image.``simple_transform`(im, resize_size, crop_size, is_train, is_color=True, mean=None)

  Simply data argumentation for training. These operations include resizing, croping and flipping.

  Example usage:

      im = simple_transform(im, 256, 224, True)

  参数:

  - im (ndarray) – The input image with HWC layout.
  - resize_size (int) – The shorter edge length of the resized image.
  - crop_size (int) – The cropping size.
  - is_train (bool) – Whether it is training or not.
  - is_color (bool) – whether the image is color or not.
  - mean (numpy array | list) – the mean values, which can be element-wise mean values or mean values per channel.

`paddle.v2.image.``load_and_transform`(filename, resize_size, crop_size, is_train, is_color=True, mean=None)

  Load image from the input file filename and transform image for data argumentation. Please refer to the simple_transform interface for the transform operations.

  Example usage:

      im = load_and_transform('cat.jpg', 256, 224, True)

  参数:

  - filename (string) – The file name of input image.
  - resize_size (int) – The shorter edge length of the resized image.
  - crop_size (int) – The cropping size.
  - is_train (bool) – Whether it is training or not.
  - is_color (bool) – whether the image is color or not.
  - mean (numpy array | list) – the mean values, which can be element-wise mean values or mean values per channel.