From 56d184dbb1d5cfa7f247662301af671903a9111c Mon Sep 17 00:00:00 2001 From: Alicja Miloszewska Date: Mon, 3 Jun 2024 09:31:07 +0200 Subject: [PATCH] [OV JS] Add method descriptions for Core (#24693) ### Details: - Add method descriptions to TS for Core ### Tickets: - *141290* --------- Co-authored-by: Sebastian Golebiewski --- src/bindings/js/node/lib/addon.ts | 186 +++++++++++++++++++++++++----- 1 file changed, 154 insertions(+), 32 deletions(-) diff --git a/src/bindings/js/node/lib/addon.ts b/src/bindings/js/node/lib/addon.ts index d1bbc9ec58d..90d16d975e5 100644 --- a/src/bindings/js/node/lib/addon.ts +++ b/src/bindings/js/node/lib/addon.ts @@ -21,46 +21,168 @@ type elementTypeString = | 'f32' | 'string'; +/** + * Core represents an OpenVINO runtime Core entity. + * + * User applications can create several Core class instances, + * but in this case, the underlying plugins + * are created multiple times and not shared between several Core instances. + * It is recommended to have a single Core instance per application. + */ interface Core { + /** + * Registers extensions to a Core object. + * @param libraryPath Path to the library with ov::Extension. + */ + addExtension(libraryPath: string): void; + /** + * Asynchronously creates a compiled model from a source {@link Model} object. + * + * You can create as many compiled models as needed and use them + * simultaneously (up to the limitation of the hardware resources). + * @param model The {@link Model} object acquired from {@link Core.readModel} + * @param deviceName The name of a device, to which the model is loaded. + * @param config An object with the key-value pairs + * (property name, property value): relevant only for this load operation. + */ compileModel( model: Model, deviceName: string, - config?: { [option: string]: string } + config?: { [propertyName: string]: string } ): Promise; + /** + * Asynchronously reads a model and creates a compiled model + * from the IR/ONNX/PDPD file. + * + * This can be more efficient + * than using {@link Core.readModel} + core.compileModel(Model) flow + * especially for cases when caching is enabled and a cached model is + * available. You can create as many compiled models as needed and use + * them simultaneously (up to the limitation of the hardware resources). + * @param modelPath The path to a model. + * @param deviceName The name of a device, to which a model is loaded. + * @param config An object with the key-value pairs + * (property name, property value): relevant only for this load operation. + */ + compileModel( + modelPath: string, + deviceName: string, + config?: { [propertyName: string]: string } + ): Promise; + /** + * A synchronous version of {@link Core.compileModel}. + * It creates a compiled model from a source model object. + */ compileModelSync( model: Model, deviceName: string, - config?: { [option: string]: string } + config?: { [propertyName: string]: string } ): CompiledModel; - readModel(modelPath: string, weightsPath?: string): Promise; - readModel( - modelBuffer: Uint8Array, weightsBuffer?: Uint8Array): Promise; - readModelSync(modelPath: string, weightsPath?: string): Model; - readModelSync(modelBuffer: Uint8Array, weightsBuffer?: Uint8Array): Model; - importModelSync(modelStream: Buffer, device: string): CompiledModel; - importModelSync( - modelStream: Buffer, - device: string, - props: { [key: string]: string | number | boolean } + /** + * A synchronous version of {@link Core.compileModel}. + * It reads a model and creates a compiled model from the IR/ONNX/PDPD file. + */ + compileModelSync( + modelPath: string, + deviceName: string, + config?: { [propertyName: string]: string } ): CompiledModel; + /** + * It returns a list of available inference devices. + * Core objects go over all registered plugins. + * @returns The list of devices may include any of the following: CPU, GPU.0, + * GPU.1, NPU… If there is more than one device of a specific type, they are + * enumerated with .# suffix. Such enumerated devices can later be used + * as a device name in all Core methods, like compile_model, query_model, + * set_property and so on. + */ getAvailableDevices(): string[]; + /** + * It gets the properties dedicated to device behaviour. + * @param propertyName A property name. + */ + getProperty(propertyName: string): string | number | boolean; + + /** + * It gets the properties dedicated to device behaviour. + * @param deviceName The name of a device, the properties of which you get. + * @param propertyName Property name. + */ + getProperty( + deviceName: string, + propertyName: string, + ): string | number | boolean; + /** + * It returns information on the version of device plugins. + * @param deviceName A device name to identify a plugin. + */ getVersions(deviceName: string): { [deviceName: string]: { buildNumber: string, description: string, }, }; - setProperty(props: { [key: string]: string | number | boolean }): void; + /** + * It imports a previously exported compiled model. + * @param modelStream The input stream that contains a model, previously exported + * with the {@link CompiledModel.exportModelSync} method. + * @param device The name of a device, for which you import a compiled model. + * Note, if the device name was not used to compile the original model, + * an exception is thrown. + * @param config An object with the key-value pairs + * (property name, property value): relevant only for this load operation. + */ + importModelSync( + modelStream: Buffer, + device: string, + config?: { [key: string]: string | number | boolean } + ): CompiledModel; + /** + * It reads models from the IR / ONNX / PDPD / TF and TFLite formats. + * @param modelPath The path to a model + * in the IR / ONNX / PDPD / TF or TFLite format. + * @param weightsPath The path to a data file for the IR format (.bin): if the path + * is empty, it tries to read the bin file with the same name as xml and if + * the bin file with the same name was not found, it loads IR without weights. + * For the ONNX format (.onnx), the weights parameter is not used. + * For the PDPD format (.pdmodel), the weights parameter is not used. + * For the TF format (.pb), the weights parameter is not used. + * For the TFLite format (*.tflite), the weights parameter is not used. + */ + readModel(modelPath: string, weightsPath?: string): Promise; + + /** + * It reads models from the IR / ONNX / PDPD / TF and TFLite formats. + * @param modelBuffer Binary data with a model + * in the IR / ONNX / PDPD / TF or TFLite format. + * @param weightsBuffer Binary data with tensor data. + */ + readModel( + modelBuffer: Uint8Array, weightsBuffer?: Uint8Array): Promise; + /** + * A synchronous version of {@link Core.readModel}. + * It reads models from the IR / ONNX / PDPD / TF and TFLite formats. + */ + readModelSync(modelPath: string, weightsPath?: string): Model; + /** + * A synchronous version of {@link Core.readModel}. + * It reads models from the IR / ONNX / PDPD / TF and TFLite formats. + */ + readModelSync(modelBuffer: Uint8Array, weightsBuffer?: Uint8Array): Model; + /** + * It sets the properties. + * @param properties An object with the property name - property value pairs. + */ + setProperty(properties: { [key: string]: string | number | boolean }): void; + /** + * It sets the properties for a device. + * @param deviceName The name of a device. + * @param properties An object with the property name - property value pairs. + */ setProperty( deviceName: string, - props: { [key: string]: string | number | boolean }, + properties: { [key: string]: string | number | boolean }, ): void; - getProperty(propertyName: string): string | number | boolean, - getProperty( - deviceName: string, - propertyName: string, - ): string | number | boolean; - addExtension(libraryPath: string): void; } interface CoreConstructor { new(): Core; @@ -80,59 +202,59 @@ interface Model { } /** - * CompiledModel represents Model that is compiled for a specific device + * CompiledModel represents a model that is compiled for a specific device * by applying multiple optimization transformations, * then mapping to compute kernels. */ interface CompiledModel { - /** Gets all inputs of a compiled model. */ + /** It gets all inputs of a compiled model. */ inputs: Output[]; - /** Gets all outputs of a compiled model. */ + /** It gets all outputs of a compiled model. */ outputs: Output[]; /** - * Creates an inference request object used to infer the compiled model. + * It creates an inference request object used to infer the compiled model. * @return {InferRequest} */ createInferRequest(): InferRequest; /** - * Exports the compiled model to binary data. + * It exports the compiled model to binary data. * @remarks * The exported model can be imported via the {@link Core.importModelSync}. - * @return {Buffer} The binary data that contains this compiled model. + * @return {Buffer} The binary data that contains the compiled model. */ exportModelSync(): Buffer; /** - * Gets a single output of a compiled model. + * It gets a single output of a compiled model. * If a model has more than one output, this method throws an exception. * @returns {Output} A compiled model output. */ output(): Output; /** - * Gets output of a compiled model identified by an index. + * It gets output of a compiled model identified by an index. * @param index An output tensor index. * @returns {Output} A compiled model output. */ output(index: number): Output; /** - * Gets output of a compiled model identified by a tensorName. + * It gets output of a compiled model identified by a tensorName. * @param name An output tensor name. * @returns {Output} A compiled model output. */ output(name: string): Output; /** - * Gets a single input of a compiled model. + * It gets a single input of a compiled model. * If a model has more than one input, this method throws an exception. * @returns {Output} A compiled model input. */ input(): Output; /** - * Gets input of a compiled model identified by an index. + * It gets input of a compiled model identified by an index. * @param index An input tensor index. * @returns {Output} A compiled model input. */ input(index: number): Output; /** - * Gets input of a compiled model identified by a tensorName. + * It gets input of a compiled model identified by a tensorName. * @param name An input tensor name. * @returns {Output} A compiled model input. */