From cf22524dcb725de5c3cc23b0526efbd6ef8ef5e6 Mon Sep 17 00:00:00 2001 From: Alicja Miloszewska Date: Wed, 5 Jun 2024 09:37:00 +0200 Subject: [PATCH] [OV JS] Add methods descriptions for Model, Tensor & InferRequest (#24768) ### Details: - Add methods descriptions for Model, Tensor & InferRequest --------- Co-authored-by: Maciej Smyk Co-authored-by: Michal Lukaszewski --- src/bindings/js/node/lib/addon.ts | 263 +++++++++++++++++++++++++++--- 1 file changed, 242 insertions(+), 21 deletions(-) diff --git a/src/bindings/js/node/lib/addon.ts b/src/bindings/js/node/lib/addon.ts index 90d16d975e5..38ff1d43d7d 100644 --- a/src/bindings/js/node/lib/addon.ts +++ b/src/bindings/js/node/lib/addon.ts @@ -188,17 +188,80 @@ interface CoreConstructor { new(): Core; } +/** + * A user-defined model read by {@link Core.readModel}. + */ interface Model { - outputs: Output[]; - inputs: Output[]; - output(nameOrId?: string | number): Output; - input(nameOrId?: string | number): Output; - getName(): string; - isDynamic(): boolean; - getOutputSize(): number; - setFriendlyName(name: string): void; + /** + * It gets the friendly name for a model. If a friendly name is not set + * via {@link Model.setFriendlyName}, a unique model name is returned. + * @returns A string with a friendly name of the model. + */ getFriendlyName(): string; - getOutputShape(): number[]; + /** + * It gets the unique name of the model. + * @returns A string with the name of the model. + */ + getName(): string; + /** + * It returns the shape of the element at the specified index. + * @param index The index of the element. + */ + getOutputShape(index: number): number[]; + /** + * It returns the number of the model outputs. + */ + getOutputSize(): number; + /** + * It gets the input of the model. + * If a model has more than one input, this method throws an exception. + */ + input(): Output; + /** + * It gets the input of the model identified by the tensor name. + * @param name The tensor name. + */ + input(name: string): Output; + /** + * It gets the input of the model identified by the index. + * @param index The index of the input. + */ + input(index: number): Output; + /** + * It returns true if any of the op’s defined in the model contains a partial + * shape. + */ + isDynamic(): boolean; + /** + * It gets the output of the model. + * If a model has more than one output, this method throws an exception. + */ + output(): Output; + /** + * It gets the output of the model identified by the tensor name. + * @param name The tensor name. + */ + output(name: string): Output; + /** + * It gets the output of the model identified by the index. + * @param index The index of the input. + */ + output(index: number): Output; + /** + * Sets a friendly name for the model. This does not overwrite the unique + * model name and is retrieved via {@link Model.getFriendlyName}. + * Mainly used for debugging. + * @param name The string to set as the friendly name. + */ + setFriendlyName(name: string): void; + /** + * It gets all the model inputs as an array. + */ + inputs: Output[]; + /** + * It gets all the model outputs as an array + */ + outputs: Output[]; } /** @@ -262,31 +325,189 @@ interface CompiledModel { } +/** + * The {@link Tensor} is a lightweight class that represents data used for + * inference. There are different ways to create a tensor. You can find them + * in {@link TensorConstructor} section. + */ interface Tensor { + /** + * This property provides access to the tensor's data. + * + * Its getter returns a subclass of TypedArray that corresponds to the + * tensor element type, e.g. Float32Array corresponds to float32. The + * content of the TypedArray subclass is a copy of the tensor underlaying + * memory. + * + * Its setter fills the underlaying tensor memory by copying the binary data + * buffer from the TypedArray subclass. An exception will be thrown if the size + * or type of array does not match the tensor. + */ data: SupportedTypedArray; + /** + * It gets the tensor element type. + */ getElementType(): element; + /** + * It gets tensor data. + * @returns A subclass of TypedArray corresponding to the tensor + * element type, e.g. Float32Array corresponds to float32. + */ + getData(): SupportedTypedArray; + /** + * It gets the tensor shape. + */ getShape(): number[]; - getData(): number[]; + /** + * It gets the tensor size as a total number of elements. + */ getSize(): number; } + +/** + * This interface contains constructors of the {@link Tensor} class. + * + * @remarks + * The tensor memory is shared with the TypedArray. That is, + * the responsibility for maintaining the reference to the TypedArray lies with + * the user. Any action performed on the TypedArray will be reflected in this + * tensor memory. + */ interface TensorConstructor { - new(type: element | elementTypeString, - shape: number[], - tensorData?: number[] | SupportedTypedArray): Tensor; + /** + * It constructs a tensor using the element type and shape. The new tensor data + * will be allocated by default. + * @param type The element type of the new tensor. + * @param shape The shape of the new tensor. + */ + new(type: element | elementTypeString, shape: number[]): Tensor; + /** + * It constructs a tensor using the element type and shape. The new tensor wraps + * allocated host memory. + * @param type The element type of the new tensor. + * @param shape The shape of the new tensor. + * @param tensorData A subclass of TypedArray that will be wrapped + * by a {@link Tensor}. + */ + new(type: element | elementTypeString, shape: number[], + tensorData: SupportedTypedArray): Tensor; } +/** + * The {@link InferRequest} object is created using + * {@link CompiledModel.createInferRequest} method and is specific for a given + * deployed model. It is used to make predictions and can be run in + * asynchronous or synchronous manners. + */ interface InferRequest { - setTensor(name: string, tensor: Tensor): void; - setInputTensor(idxOrTensor: number | Tensor, tensor?: Tensor): void; - setOutputTensor(idxOrTensor: number | Tensor, tensor?: Tensor): void; - getTensor(nameOrOutput: string | Output): Tensor; - getInputTensor(idx?: number): Tensor; - getOutputTensor(idx?: number): Tensor; - infer(inputData?: { [inputName: string]: Tensor | SupportedTypedArray} - | Tensor[] | SupportedTypedArray[]): { [outputName: string] : Tensor}; + /** + * It infers specified input(s) in the synchronous mode. + * @remarks + * Inputs have to be specified earlier using {@link InferRequest.setTensor} + * or {@link InferRequest.setInputTensor} + */ + infer(): { [outputName: string] : Tensor}; + /** + * It infers specified input(s) in the synchronous mode. + * @param inputData An object with the key-value pairs where the key is the + * input name and value can be either a tensor or a TypedArray. TypedArray + * will be wrapped into Tensor underneath using the input shape and element type + * of the deployed model. + */ + infer(inputData: { [inputName: string]: Tensor | SupportedTypedArray}) + : { [outputName: string] : Tensor}; + /** + * It infers specified input(s) in the synchronous mode. + * @param inputData An array with tensors or TypedArrays. TypedArrays will be + * wrapped into Tensors underneath using the input shape and element type + * of the deployed model. If the model has multiple inputs, the Tensors + * and TypedArrays must be passed in the correct order. + */ + infer(inputData: Tensor[] | SupportedTypedArray[]) + : { [outputName: string] : Tensor}; + /** + * It infers specified input(s) in the asynchronous mode. + * @param inputData An object with the key-value pairs where the key is the + * input name and value is a tensor or an array with tensors. If the model has + * multiple inputs, the Tensors must be passed in the correct order. + */ inferAsync(inputData: { [inputName: string]: Tensor} | Tensor[] ): Promise<{ [outputName: string] : Tensor}>; + /** + * It gets the compiled model used by the InferRequest object. + */ getCompiledModel(): CompiledModel; + /** + * It gets the input tensor for inference. + * @returns The input tensor for the model. If the model has several inputs, + * an exception is thrown. + */ + getInputTensor(): Tensor; + /** + * It gets the input tensor for inference. + * @param idx An index of the tensor to get. + * @returns A tensor at the specified index. If the tensor with the specified + * idx is not found, an exception is thrown. + */ + getInputTensor(idx: number): Tensor; + /** + * It gets the output tensor for inference. + * @returns The output tensor for the model. If the model has several outputs, + * an exception is thrown. + */ + getOutputTensor(): Tensor; + /** + * It gets the output tensor for inference. + * @param idx An index of the tensor to get. + * @returns A tensor at the specified index. If the tensor with the specified + * idx is not found, an exception is thrown. + */ + getOutputTensor(idx?: number): Tensor; + /** + * It gets an input/output tensor for inference. + * + * @remarks + * If a tensor with the specified name or port is not found, an exception + * is thrown. + * @param nameOrOutput The name of the tensor or output object. + */ + getTensor(nameOrOutput: string | Output): Tensor; + /** + * It sets the input tensor to infer models with a single input. + * @param tensor The input tensor. The element type and shape of the tensor + * must match the type and size of the model's input element. If the model has several + * inputs, an exception is thrown. + */ + setInputTensor(tensor: Tensor): void; + /** + * It sets the input tensor to infer. + * @param idx The input tensor index. If idx is greater than the number of + * model inputs, an exception is thrown. + * @param tensor The input tensor. The element type and shape of the tensor + * must match the input element type and size of the model. + */ + setInputTensor(idx: number, tensor: Tensor): void; + /** + * It sets the output tensor to infer models with a single output. + * @param tensor The output tensor. The element type and shape of the tensor + * must match the output element type and size of the model. If the model has several + * outputs, an exception is thrown. + */ + setOutputTensor(tensor: Tensor): void; + /** + * It sets the output tensor to infer. + * @param idx The output tensor index. + * @param tensor The output tensor. The element type and shape of the tensor + * must match the output element type and size of the model. + */ + setOutputTensor(idx: number, tensor: Tensor): void; + /** + * It sets the input/output tensor to infer. + * @param name The input or output tensor name. + * @param tensor The tensor. The element type and shape of the tensor + * must match the input/output element type and size of the model. + */ + setTensor(name: string, tensor: Tensor): void; } type Dimension = number | [number, number];