paddleclas 2.4.0

A treasure chest for visual recognition powered by PaddlePaddle.

PaddleClas wheel package

Paddleclas supports Python WHL package for prediction. At present, WHL package only supports image classification, but does not support subject detection, feature extraction and vector retrieval.

---

Catalogue

• 1. Installation
• 2. Quick Start
• 3. Definition of Parameters
• 4. Usage
  • 4.1 View help information
  • 4.2 Prediction using inference model provide by PaddleClas
  • 4.3 Prediction using local model files
  • 4.4 Prediction by batch
  • 4.5 Prediction of Internet image
  • 4.6 Prediction of NumPy.array format image
  • 4.7 Save the prediction result(s)
  • 4.8 Specify the mapping between class id and label name

1. Installation

• installing from pypi

pip3 install paddleclas==2.2.1

• build own whl package and install

python3 setup.py bdist_wheel
pip3 install dist/*

2. Quick Start

• Using the ResNet50 model provided by PaddleClas, the following image('docs/images/inference_deployment/whl_demo.jpg') as an example.

• Python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50')
infer_imgs='docs/images/inference_deployment/whl_demo.jpg'
result=clas.predict(infer_imgs)
print(next(result))

Note: PaddleClas.predict() is a generator. Therefore you need to use next() or for call it iteratively. It will perform a prediction by batch_size and return the prediction result(s) when called. Examples of returned results are as follows:

>>> result
[{'class_ids': [8, 7, 136, 80, 84], 'scores': [0.79368, 0.16329, 0.01853, 0.00959, 0.00239], 'label_names': ['hen', 'cock', 'European gallinule, Porphyrio porphyrio', 'black grouse', 'peacock']}]

• CLI

paddleclas --model_name=ResNet50  --infer_imgs="docs/images/inference_deployment/whl_demo.jpg"

>>> result
filename: docs/images/inference_deployment/whl_demo.jpg, top-5, class_ids: [8, 7, 136, 80, 84], scores: [0.79368, 0.16329, 0.01853, 0.00959, 0.00239], label_names: ['hen', 'cock', 'European gallinule, Porphyrio porphyrio', 'black grouse', 'peacock']
Predict complete!

3. Definition of Parameters

The following parameters can be specified in Command Line or used as parameters of the constructor when instantiating the PaddleClas object in Python.

• model_name(str): If using inference model based on ImageNet1k provided by Paddle, please specify the model's name by the parameter.
• inference_model_dir(str): Local model files directory, which is valid when model_name is not specified. The directory should contain inference.pdmodel and inference.pdiparams.
• infer_imgs(str): The path of image to be predicted, or the directory containing the image files, or the URL of the image from Internet.
• use_gpu(bool): Whether to use GPU or not, default by True.
• gpu_mem(int): GPU memory usages，default by 8000。
• use_tensorrt(bool): Whether to open TensorRT or not. Using it can greatly promote predict preformance, default by False.
• enable_mkldnn(bool): Whether enable MKLDNN or not, default False.
• cpu_num_threads(int): Assign number of cpu threads, valid when --use_gpu is False and --enable_mkldnn is True, default by 10.
• batch_size(int): Batch size, default by 1.
• resize_short(int): Resize the minima between height and width into resize_short, default by 256.
• crop_size(int): Center crop image to crop_size, default by 224.
• topk(int): Print (return) the topk prediction results, default by 5.
• class_id_map_file(str): The mapping file between class ID and label, default by ImageNet1K dataset's mapping.
• pre_label_image(bool): whether prelabel or not, default=False.
• save_dir(str): The directory to save the prediction results that can be used as pre-label, default by None, that is, not to save.

Note: If you want to use Transformer series models, such as DeiT_***_384, ViT_***_384, etc., please pay attention to the input size of model, and need to set resize_short=384, resize=384. The following is a demo.

• CLI:

from paddleclas import PaddleClas, get_default_confg
paddleclas --model_name=ViT_base_patch16_384 --infer_imgs='docs/images/inference_deployment/whl_demo.jpg' --resize_short=384 --crop_size=384

• Python:

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ViT_base_patch16_384', resize_short=384, crop_size=384)

4. Usage

PaddleClas provides two ways to use:

1. Python interative programming;
2. Bash command line programming.

4.1 View help information

• CLI

paddleclas -h

4.2 Prediction using inference model provide by PaddleClas

You can use the inference model provided by PaddleClas to predict, and only need to specify model_name. In this case, PaddleClas will automatically download files of specified model and save them in the directory ~/.paddleclas/.

• Python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50')
infer_imgs = 'docs/images/inference_deployment/whl_demo.jpg'
result=clas.predict(infer_imgs)
print(next(result))

• CLI

paddleclas --model_name='ResNet50' --infer_imgs='docs/images/inference_deployment/whl_demo.jpg'

4.3 Prediction using local model files

You can use the local model files trained by yourself to predict, and only need to specify inference_model_dir. Note that the directory must contain inference.pdmodel and inference.pdiparams.

• Python

from paddleclas import PaddleClas
clas = PaddleClas(inference_model_dir='./inference/')
infer_imgs = 'docs/images/inference_deployment/whl_demo.jpg'
result=clas.predict(infer_imgs)
print(next(result))

• CLI

paddleclas --inference_model_dir='./inference/' --infer_imgs='docs/images/inference_deployment/whl_demo.jpg'

4.4 Prediction by batch

You can predict by batch, only need to specify batch_size when infer_imgs is direcotry contain image files.

• Python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50', batch_size=2)
infer_imgs = 'docs/images/'
result=clas.predict(infer_imgs)
for r in result:
    print(r)

• CLI

paddleclas --model_name='ResNet50' --infer_imgs='docs/images/' --batch_size 2

4.5 Prediction of Internet image

You can predict the Internet image, only need to specify URL of Internet image by infer_imgs. In this case, the image file will be downloaded and saved in the directory ~/.paddleclas/images/.

• Python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50')
infer_imgs = 'https://raw.githubusercontent.com/paddlepaddle/paddleclas/release/2.2/docs/images/inference_deployment/whl_demo.jpg'
result=clas.predict(infer_imgs)
print(next(result))

• CLI

paddleclas --model_name='ResNet50' --infer_imgs='https://raw.githubusercontent.com/paddlepaddle/paddleclas/release/2.2/docs/images/inference_deployment/whl_demo.jpg'

4.6 Prediction of NumPy.array format image

In Python code, you can predict the NumPy.array format image, only need to use the infer_imgs to transfer variable of image data. Note that the models in PaddleClas only support to predict 3 channels image data, and channels order is RGB.

• python

import cv2
from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50')
infer_imgs = cv2.imread("docs/en/inference_deployment/whl_deploy_en.md")[:, :, ::-1]
result=clas.predict(infer_imgs)
print(next(result))

4.7 Save the prediction result(s)

You can save the prediction result(s) as pre-label, only need to use pre_label_out_dir to specify the directory to save.

• python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50', save_dir='./output_pre_label/')
infer_imgs = 'docs/images/' # it can be infer_imgs folder path which contains all of images you want to predict.
result=clas.predict(infer_imgs)
print(next(result))

• CLI

paddleclas --model_name='ResNet50' --infer_imgs='docs/images/' --save_dir='./output_pre_label/'

4.8 Specify the mapping between class id and label name

You can specify the mapping between class id and label name, only need to use class_id_map_file to specify the mapping file. PaddleClas uses ImageNet1K's mapping by default.

The content format of mapping file shall be:

class_id<space>class_name<\n>

For example:

0 tench, Tinca tinca
1 goldfish, Carassius auratus
2 great white shark, white shark, man-eater, man-eating shark, Carcharodon carcharias
......

• Python

from paddleclas import PaddleClas
clas = PaddleClas(model_name='ResNet50', class_id_map_file='./ppcls/utils/imagenet1k_label_list.txt')
infer_imgs = 'docs/images/inference_deployment/whl_demo.jpg'
result=clas.predict(infer_imgs)
print(next(result))

• CLI

paddleclas --model_name='ResNet50' --infer_imgs='docs/images/inference_deployment/whl_demo.jpg' --class_id_map_file='./ppcls/utils/imagenet1k_label_list.txt'