@tensorflow-models/coco-ssd
Version:
Object detection model (coco-ssd) in TensorFlow.js
263 lines (262 loc) • 11.2 kB
TypeScript
/**
* @license
* Copyright 2017 Google Inc. All Rights Reserved.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* =============================================================================
*/
import { Engine, MemoryInfo, ProfileInfo, ScopeFn, TimingInfo } from './engine';
import { Features } from './environment_util';
import { KernelBackend } from './kernels/backend';
import { Tensor } from './tensor';
import { TensorContainer } from './tensor_types';
export declare const EPSILON_FLOAT16 = 0.0001;
export declare const EPSILON_FLOAT32 = 1e-7;
export declare class Environment {
private features;
private globalEngine;
private registry;
backendName: string;
constructor(features?: Features);
/**
* Sets the backend (cpu, webgl, etc) responsible for creating tensors and
* executing operations on those tensors.
*
* Note this disposes the current backend, if any, as well as any tensors
* associated with it. A new backend is initialized, even if it is of the
* same type as the previous one.
*
* @param backendName The name of the backend. Currently supports
* `'webgl'|'cpu'` in the browser, and `'tensorflow'` under node.js
* (requires tfjs-node).
* @param safeMode Defaults to false. In safe mode, you are forced to
* construct tensors and call math operations inside a `tidy()` which
* will automatically clean up intermediate tensors.
*/
/** @doc {heading: 'Environment'} */
static setBackend(backendName: string, safeMode?: boolean): void;
/**
* Returns the current backend name (cpu, webgl, etc). The backend is
* responsible for creating tensors and executing operations on those tensors.
*/
/** @doc {heading: 'Environment'} */
static getBackend(): string;
/**
* Dispose all variables kept in backend engine.
*/
/** @doc {heading: 'Environment'} */
static disposeVariables(): void;
/**
* Returns memory info at the current time in the program. The result is an
* object with the following properties:
*
* - `numBytes`: Number of bytes allocated (undisposed) at this time.
* - `numTensors`: Number of unique tensors allocated.
* - `numDataBuffers`: Number of unique data buffers allocated
* (undisposed) at this time, which is ≤ the number of tensors
* (e.g. `a.reshape(newShape)` makes a new Tensor that shares the same
* data buffer with `a`).
* - `unreliable`: True if the memory usage is unreliable. See `reasons` when
* `unrealible` is true.
* - `reasons`: `string[]`, reasons why the memory is unreliable, present if
* `unreliable` is true.
*/
/** @doc {heading: 'Performance', subheading: 'Memory'} */
static memory(): MemoryInfo;
/**
* Executes the provided function `f()` and returns a promise that resolves
* with information about the function's memory use:
* - `newBytes`: tne number of new bytes allocated
* - `newTensors`: the number of new tensors created
* - `peakBytes`: the peak number of bytes allocated
* - `kernels`: an array of objects for each kernel involved that reports
* their input and output shapes, number of bytes used, and number of new
* tensors created.
*
* ```js
* const profile = await tf.profile(() => {
* const x = tf.tensor1d([1, 2, 3]);
* let x2 = x.square();
* x2.dispose();
* x2 = x.square();
* x2.dispose();
* return x;
* });
*
* console.log(`newBytes: ${profile.newBytes}`);
* console.log(`newTensors: ${profile.newTensors}`);
* console.log(`byte usage over all kernels: ${profile.kernels.map(k =>
* k.totalBytesSnapshot)}`);
* ```
*
*/
/** @doc {heading: 'Performance', subheading: 'Profile'} */
static profile(f: () => TensorContainer): Promise<ProfileInfo>;
/**
* Executes the provided function `fn` and after it is executed, cleans up all
* intermediate tensors allocated by `fn` except those returned by `fn`.
* `fn` must not return a Promise (async functions not allowed). The returned
* result can be a complex object.
*
* Using this method helps avoid memory leaks. In general, wrap calls to
* operations in `tf.tidy` for automatic memory cleanup.
*
* When in safe mode, you must enclose all `tf.Tensor` creation and ops
* inside a `tf.tidy` to prevent memory leaks.
*
* ```js
* // y = 2 ^ 2 + 1
* const y = tf.tidy(() => {
* // a, b, and one will be cleaned up when the tidy ends.
* const one = tf.scalar(1);
* const a = tf.scalar(2);
* const b = a.square();
*
* console.log('numTensors (in tidy): ' + tf.memory().numTensors);
*
* // The value returned inside the tidy function will return
* // through the tidy, in this case to the variable y.
* return b.add(one);
* });
*
* console.log('numTensors (outside tidy): ' + tf.memory().numTensors);
* y.print();
* ```
*
* @param nameOrFn The name of the closure, or the function to execute.
* If a name is provided, the 2nd argument should be the function.
* If debug mode is on, the timing and the memory usage of the function
* will be tracked and displayed on the console using the provided name.
* @param fn The function to execute.
*/
/** @doc {heading: 'Performance', subheading: 'Memory'} */
static tidy<T extends TensorContainer>(nameOrFn: string | ScopeFn<T>, fn?: ScopeFn<T>): T;
/**
* Disposes any `tf.Tensor`s found within the provided object.
*
* @param container an object that may be a `tf.Tensor` or may directly
* contain `tf.Tensor`s, such as a `Tensor[]` or `{key: Tensor, ...}`. If
* the object is not a `tf.Tensor` or does not contain `Tensors`, nothing
* happens. In general it is safe to pass any object here, except that
* `Promise`s are not supported.
*/
/** @doc {heading: 'Performance', subheading: 'Memory'} */
static dispose(container: TensorContainer): void;
/**
* Keeps a `tf.Tensor` generated inside a `tf.tidy` from being disposed
* automatically.
*
* ```js
* let b;
* const y = tf.tidy(() => {
* const one = tf.scalar(1);
* const a = tf.scalar(2);
*
* // b will not be cleaned up by the tidy. a and one will be cleaned up
* // when the tidy ends.
* b = tf.keep(a.square());
*
* console.log('numTensors (in tidy): ' + tf.memory().numTensors);
*
* // The value returned inside the tidy function will return
* // through the tidy, in this case to the variable y.
* return b.add(one);
* });
*
* console.log('numTensors (outside tidy): ' + tf.memory().numTensors);
* console.log('y:');
* y.print();
* console.log('b:');
* b.print();
* ```
*
* @param result The tensor to keep from being disposed.
*/
/** @doc {heading: 'Performance', subheading: 'Memory'} */
static keep<T extends Tensor>(result: T): T;
/**
* Executes `f()` and returns a promise that resolves with timing
* information.
*
* The result is an object with the following properties:
*
* - `wallMs`: Wall execution time.
* - `kernelMs`: Kernel execution time, ignoring data transfer.
* - On `WebGL` The following additional properties exist:
* - `uploadWaitMs`: CPU blocking time on texture uploads.
* - `downloadWaitMs`: CPU blocking time on texture downloads (readPixels).
*
* ```js
* const x = tf.randomNormal([20, 20]);
* const time = await tf.time(() => x.matMul(x));
*
* console.log(`kernelMs: ${time.kernelMs}, wallTimeMs: ${time.wallMs}`);
* ```
*
* @param f The function to execute and time.
*/
/** @doc {heading: 'Performance', subheading: 'Timing'} */
static time(f: () => void): Promise<TimingInfo>;
get<K extends keyof Features>(feature: K): Features[K];
getFeatures(): Features;
set<K extends keyof Features>(feature: K, value: Features[K]): void;
private getBestBackendName;
private evaluateFeature;
setFeatures(features: Features): void;
reset(): void;
readonly backend: KernelBackend;
findBackend(name: string): KernelBackend;
/**
* Registers a global backend. The registration should happen when importing
* a module file (e.g. when importing `backend_webgl.ts`), and is used for
* modular builds (e.g. custom tfjs bundle with only webgl support).
*
* @param factory The backend factory function. When called, it should
* return an instance of the backend.
* @param priority The priority of the backend (higher = more important).
* In case multiple backends are registered, the priority is used to find
* the best backend. Defaults to 1.
* @return False if the creation/registration failed. True otherwise.
*/
registerBackend(name: string, factory: () => KernelBackend, priority?: number): boolean;
removeBackend(name: string): void;
readonly engine: Engine;
private initEngine;
readonly global: {
ENV: Environment;
};
}
/**
* Enables production mode which disables correctness checks in favor of
* performance.
*/
/** @doc {heading: 'Environment'} */
export declare function enableProdMode(): void;
/**
* Enables debug mode which will log information about all executed kernels:
* the ellapsed time of the kernel execution, as well as the rank, shape, and
* size of the output tensor.
*
* Debug mode will significantly slow down your application as it will
* download the result of every operation to the CPU. This should not be used in
* production. Debug mode does not affect the timing information of the kernel
* execution as we do not measure download time in the kernel execution time.
*
* See also: `tf.profile`, `tf.memory`.
*/
/** @doc {heading: 'Environment'} */
export declare function enableDebugMode(): void;
/** Globally disables deprecation warnings */
export declare function disableDeprecationWarnings(): void;
/** Warn users about deprecated functionality. */
export declare function deprecationWarn(msg: string): void;
export declare let ENV: Environment;