README.md

中文

Paddle.js Core

As the core part of the Paddle.js ecosystem, this package hosts @paddlejs/paddlejs-core, which is responsible for the operation of the inference process of the entire engine, and provides interfaces for backend registration and environment variable registration.

RunnerConfig

When registering the engine you need to configure the engine, you must configure the items modelPath, feedShape, all items are configured as follows.

// model struture
enum GraphType {
    SingleOutput = 'single',
    MultipleOutput = 'multiple',
    MultipleInput = 'multipleInput'
}

interface RunnerConfig {
    modelPath: string; // model path (local or web address)
    modelName?: string; // model name
    feedShape: { // input feed shape
        fc?: number; // feed channel, default is 3.
        fw: number; // feed width
        fh: number; // feed height
    };
    fill?: Color; // the color used to padding
    mean?: number[]; // mean value
    std?: number[]; // standard deviation
    bgr?: boolean; // whether the image channel alignment is BGR, default is false (RGB)
    type?: GraphType; // model structure, default is singleInput and singleOutput
    needPreheat?: boolean; // whether to warm up the engine during initialization, default is true
    plugins?: { // register model topology transform plugin
        preTransforms?: Transformer[]; // transform before creating network topology
        transforms?: Transformer[]; // transform when traversing model layers
        postTransforms?: Transformer[]; // transform the model topology diagram after it has been created
    };
}

Importing

You can install this package via npm., @paddlejs/paddlejs-core

// Import @paddlejs/paddlejs-core
import { Runner } from '@paddlejs/paddlejs-core';
// Import the registered WebGL backend.
import '@paddlejs/paddlejs-backend-webgl';

const runner = new Runner({
    modelPath: '/model/mobilenetv2', // model path, e.g. http://xx.cc/path, http://xx.cc/path/model.json, /localModelDir/model.json, /localModelDir
    feedShape: { // input shape
        fw: 256,
        fh: 256
    },
    fill?: '#fff', // fill color when resize image, default value is #fff
    webglFeedProcess?: true // Turn on `webglFeedProcess` to convert all pre-processing parts of the model to shader processing, and keep the original image texture.
});

// init runner
await runner.init();
// predict and get result
const res = await runner.predict(mediadata, callback?);

Note: If you are importing the Core package, you also need to import a backend (e.g., paddlejs-backend-webgl, paddlejs-backend-webgpu).

High-level use

1. @paddlejs/paddlejs-core provides the interface registerOp, through which developers can register custom operators.

2. @paddlejs/paddlejs-core provides the global variable env module, through which developers can register environment variables, using the following method:

   // set env key/flag and value
   env.set(key, value);
   
   // get value by key/flag
   env.get(key);

3. transform model stucture

   By registering the model transformers through runnerConfig.plugins, developers can make changes (add, delete, change) to the model structure, such as pruning to remove unnecessary layers to speed up inference, or adding custom layers to the end of the model and turning post-processing into layers in the model to speed up post-processing.

4. Turn on performance flag for acceleration

   Paddle.js currently provides five performance flags, which can be set to true if you want to enable inference acceleration.

   env.set('webgl_pack_channel', true);

   Turn on webgl_pack_channel and the eligible conv2d will use packing shader to perform packing transformations to improve performance through vectorization calculations.

   env.set('webgl_force_half_float_texture', true);

   Enable webgl_force_half_float_texture, feature map uses half float HALF_FLOAT.

   env.set('webgl_gpu_pipeline', true);

   Turn on webgl_gpu_pipeline to convert all model pre-processing parts to shader processing, and render the model results to WebGL2RenderingContext of webgl backend on screen. Developers can perform model post-processing on the output texture and the original image texture to achieve the GPU_PIPELINE: pre-processing + inference + post-processing (rendering processing) to get high performance. Take humanseg model case for reference.

   env.set('webgl_pack_output', true);

   Enable webgl_pack_output to migrate the NHWC to NCHW layout transformation of the model output to the GPU, and pack to a four-channel layout to reduce loop processing when reading the results from the GPU