@pixelverse/strichjs-sdk 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [1.4.0] - 2023-12-29
+
+### Fixed
+
+- Fixed a performance issue that manifested itself on less powerful devices where the majority of processing time was spent on GPU->CPU buffer transfers, leading to up to 60% performance increase in some situations.
+
+### Changed
+
+- `BarcodeReader.destroy()` now returns a Promise that resolves when the `BarcodeReader` and its resources are destroyed. The returned Promise is typically already resolved, unless `destroy()` is called while the BarcodeReader is being initialized, in which case the destruction happens after initialization completes. Previously, calling `destroy()` while `initialize()` was still pending caused a crash. Existing application code that calls `destroy()` does not need to be adapted.
+
+### Added
+
+- Added basic overlay styling capabilities to overlay. The color of the viewfinder, camera selector control and flashlight icons can now be set via overlay configuration property `primaryColor`. The color of highlighted barcode detections can be set using `highlightColor`, and the `cornerRadius` property can be used to apply rounded corners to the viewfinder and camera selector control. The color of the targeting line when a linear barcode is detected can be set using `targetingLineActiveColor`. The defaults for all these properties match the previous hard-coded values, so if you are happy with the look & feel, you don't have to do anything. 
+- Added overlay configuration property `filterCameras` to control filtering of camera devices shown in camera selector. If set to true `true` (default), only back-facing camera devices are listed. If set to `false`, all camera devices available in the browser are listed.
+- If a `BarcodeReader` could not be initialized due to missing browser capabilities like WebAssembly, WebGL or getUserMedia, mention the missing capability in the `detailMessage` property of the thrown `SdkError`.
+- Report the detected code's location as a quadrilateral instead of an axis-aligned bounding box in the new `quadrilateral` property of the `CodeDetection`. The overlay will also use this more precise location for drawing the detections if `drawDetections` is enabled.
+
 ## [1.3.4] - 2023-11-28
 
 ### Fixed

package/dist/strich.d.ts

@@ -37,21 +37,23 @@ export interface FrameSourceConfiguration {
     /**
      * Video frame resolution.
      *
+     * @remarks
      * The default resolution is 720p, which is usually enough for good quality
      * barcodes. You can try higher resolutions if you have very fine or
      * degraded codes, at the expense of higher computational requirements.
      *
-     * @default hd
+     * @defaultValue hd
      */
     resolution?: 'hd' | 'full-hd' | 'auto';
     /**
      * Remember the camera that was last used to successfully scan a code.
      *
+     * @remarks
      * If this is set to true, the frame source will remember the camera used
      * whenever a code was successfully scanned, and attempt to use the same
      * camera again when re-initialized.
      *
-     * @default false
+     * @defaultValue false
      */
     rememberCameraDeviceId?: boolean;
 }
@@ -70,27 +72,27 @@ export function defaultFrameSourceConfiguration(): FrameSourceConfiguration;
  */
 export interface RegionOfInterest {
     /**
-     * Left inset, relative [0 .. 0.5]
+     * Left inset, relative [0 .. 0.5].
      *
-     * @default A default is selected at run-time depending on enabled symbologies.
+     * @example 0.1
      */
     left: number;
     /**
-     * Top inset, relative [0 .. 0.5]
+     * Top inset, relative [0 .. 0.5].
      *
-     * @default A default is selected at run-time depending on enabled symbologies.
+     * @example 0.25
      */
     top: number;
     /**
-     * Right inset, relative [0 .. 0.5]
+     * Right inset, relative [0 .. 0.5].
      *
-     * @default A default is selected at run-time depending on enabled symbologies.
+     * @example 0.1
      */
     right: number;
     /**
      * Bottom inset, relative [0 .. 0.5]
      *
-     * @default A default is selected at run-time depending on enabled symbologies.
+     * @example 0.25
      */
     bottom: number;
 }
@@ -100,27 +102,33 @@ export interface RegionOfInterest {
 export interface LocatorConfiguration {
     /**
      * The region of interest in viewport coordinates.
+     *
+     * @remarks if no region of interest is specified, an appropriate one will automatically be selected at run-time
+     * depending on the configured symbologies.
      */
     regionOfInterest?: RegionOfInterest;
     /**
-     * Disregard colorful areas, assumes that codes are printed black on white.
-     * This is an advanced configuration option, use with care.
+     * Disregard colorful areas, assume barcodes are printed black on white.
      *
-     * @default false
+     * @remarks This is an advanced setting and should normally not be changed.
+     * @defaultValue false
      */
     chromaReject?: boolean;
     /**
      * The locator implementation to use. This should normally not be changed, unless it is specifically required
      * to target WebGL 1.
      *
-     * @default 'auto'
+     * @remarks This is an advanced setting and should normally not be changed, unless targeting WebGL1 and not
+     * WebGL2 is explicitly required.
+     * @defaultValue auto
      */
     impl?: 'auto' | 'webgl1' | 'webgl2';
     /**
-     * An advanced option for disabling asynchronous reads from GPU when using 'webgl2'.
-     * Some older iOS versions have issues with WebGL2 asynchronous readbacks.
+     * Disable asynchronous reads from GPU when using `webgl2` {@link impl}.
      *
-     * @default false
+     * @remarks Some older iOS versions have issues with WebGL2 asynchronous reads. There is usually no need to change
+     * this setting from its default.
+     * @defaultValue false
      */
     forceSyncReadback?: boolean;
 }
@@ -152,63 +160,64 @@ export interface EngineConfiguration {
     /**
      * The enabled symbologies.
      *
-     * It is highly recommended to configure only the symbologies required by
-     * your application.
-     *
+     * @remarks
+     * It is highly recommended to configure only the symbologies required by your application.
      * An empty array or undefined is interpreted as 'all symbologies enabled'.
      *
-     * @default undefined (all symbologies enabled - NOT RECOMMENDED)
+     * @example ['qr', 'code128']
+     *
+     * @default
+     * ```undefined```
+     * (all symbologies enabled - NOT RECOMMENDED)
      */
     symbologies?: (SymbologyName | SymbologySpec)[];
     /**
      * The number of scanlines to run over a located barcode candidate.
      *
-     * @default 10
+     * @defaultValue 10
      */
     numScanlines?: number;
     /**
-     * The number of scanlines that need to decodd successfully for a valid
-     * decode.
+     * The number of scanlines that need to decoded successfully for a valid decode.
      *
+     * @remarks
      * Increasing this parameter reduces the possibility of a misread, but
      * makes it more likely for degraded codes to not be read at all.
      *
      * The default value is two scanlines and usually should not be changed.
      *
-     * @default 2
+     * @defaultValue 2
      */
     minScanlinesNeeded?: number;
     /**
      * Toggle recognition of inverted barcodes (light print on dark background).
      *
-     * @default false
+     * @remarks
+     * This should only be enabled if you need to detect these barcodes, as additional processing will take place.
+     *
+     * @defaultValue false
      */
     invertedCodes?: boolean;
     /**
      * Time interval in milliseconds during which multiple detections of the same code are not repeated.
      *
-     * The default behavior is to pass through detections as they are detected and not perform any filtering.
-     *
-     * It is recommended to set a low duplicateInterval as scans are metered in non-Enterprise subscriptions.
+     * @remarks It is recommended to set a duplicateInterval as scans are metered except in Enterprise subscriptions.
+     * @defaultValue 750
      */
     duplicateInterval?: number;
     /**
-     * Hysteresis parameterization for 1D barcodes with weak checksums.
-     *
-     * This parameter sets the minimum threshold for the number of detections of a barcode in the hysteresis
-     * window for it to be accepted.
+     * Set the minimum occurrence count for 1D barcodes with weak checksums in a given time window for it be accepted.
      *
+     * @remarks
      * Setting this parameter to 0 disables hysteresis (default behavior for versions <= 1.1.0)
      *
-     * @default 2
+     * @defaultValue 2
      */
     hysteresisMinCount?: number;
     /**
-     * Hysteresis parameterization for 1D barcodes with weak checksums.
+     * Set the duration of the hysteresis window in milliseconds.
      *
-     * This parameter sets the size of the hysteresis window in milliseconds.
-     *
-     * @default 350
+     * @defaultValue 350
      */
     hysteresisInterval?: number;
 }
@@ -219,41 +228,113 @@ export interface OverlayConfiguration {
     /**
      * Indicate if a horizontal line should be drawn to aid in positioning 1D barcodes.
      *
-     * @default true
+     * @defaultValue true
+     * @category Styling
      */
     showTargetingLine?: boolean;
     /**
      * Indicate if the overlay should draw the bounding boxes of detected barcodes on top of the camera preview.
      *
-     * @default true
+     * @defaultValue true
+     * @category Styling
      */
     showDetections?: boolean;
     /**
      * Indicate if the camera selector should be shown in the overlay.
      *
-     * @default true
+     * @defaultValue true
+     * @category Interaction
      */
     showCameraSelector?: boolean;
     /**
-     * Indicate if the flashlight toggle should be shown in the overlay.
+     * Filter cameras returned by the browser.
      *
-     * Flashlight functionality is not supported in some browsers.
+     * If set to true, only cameras that are deemed appropriate for barcode scanning will be
+     * offered in the camera selector.
      *
-     * @default true
+     * @defaultValue true
+     * @category Interaction
+     */
+    filterCameras?: boolean;
+    /**
+     * Indicate if the flashlight toggle should be shown in the overlay.
+     *
+     * @remarks Flashlight functionality is not supported in some browsers.
+     * @defaultValue true
+     * @category Interaction
      */
     showFlashlight?: boolean;
     /**
-     * @default true (where supported)
+     * Indicate if single-tapping the overlay should attempt to trigger autofocus.
+     *
+     * @remarks Triggering autofocus is currently only available on Android devices.
+     * @defaultValue true
+     * @category Interaction
      */
     focusOnTap?: boolean;
+    /**
+     * Color to use for drawing UI elements such as the view finder and camera selector. Must be specified in rgb()
+     * format, with the color components given as integers with no separating whitespace.
+     *
+     * @defaultValue rgb(255,255,255)
+     * @category Styling
+     */
+    primaryColor?: string;
+    /**
+     * Color to use for filling area of detected barcodes. Must be specified in rgb() format, with the color
+     * components given as integers with no separating whitespace. The fill will become transparent when the
+     * detection becomes stale.
+     *
+     * @remarks Only has an effect if {@link showDetections} is true.
+     * @defaultValue rgb(0,0,255)
+     * @category Styling
+     */
+    detectionFillColor?: string;
+    /**
+     * Color to use for drawing a border around the area of detected barcodes. Must be specified in rgb() format,
+     * with the color components given as integers with no separating whitespace. The border will become transparent
+     * when the detection becomes stale.
+     *
+     * @remarks Only has an effect if {@link showDetections} is true.
+     * @defaultValue undefined
+     * @category Styling
+     */
+    detectionBorderColor?: string;
+    /**
+     * The border width in pixels to use for drawing a border around the area of detected barcodes.
+     *
+     * @remarks
+     * The allowed range is 0 to 4 pixels. Values outside the range are clamped.
+     *
+     * @defaultValue 0
+     * @category Styling
+     */
+    detectionBorderWidth?: number;
+    /**
+     * Color to use for drawing the horizontal targeting line when a barcode was detected.
+     * Must be specified in rgb() format, with the color components given as integers with no separating whitespace.
+     *
+     * @defaultvalue rgb(255,0,0)
+     * @category Styling
+     */
+    targetingLineActiveColor?: string;
+    /**
+     * Corner radius in pixels for rectangular elements such as view finder and camera selector.
+     *
+     * The allowed range of the corner radius is 0 to 8 pixels.
+     *
+     * @defaultValue 0
+     * @category Styling
+     */
+    cornerRadius?: number;
     /**
      * Override the STRICH logo displayed in the bottom-right corner with a custom image.
      *
-     * The image is supplied as a URL (e.g. https://example.com/assets/overlay.png) or inline as a data URL
-     * (recommended, avoids network request). The image should have a transparent background (WebP or PNG format
-     * recommended) and a recommended size of 140x30 pixels.
+     * The image is supplied as a URL (e.g. https://example.com/assets/overlay.png) or inline as a data URL. The image
+     * should have a transparent background (WebP or PNG format). The recommended size is 140x30 pixels.
      *
-     * This is an enterprise-only capability.
+     * @remarks This is an enterprise-only capability.
+     * @category Styling
      */
     customLogoSrc?: string;
 }
@@ -262,15 +343,15 @@ export interface OverlayConfiguration {
  */
 export interface FeedbackConfiguration {
     /**
-     * If true, an audible beep will be emitted upon successful scan.
+     * Toggle audible beep upon successful scan.
      *
-     * @default true
+     * @defaultValue true
      */
     audio?: boolean;
     /**
-     * If true, a vibration will be emitted upon successful scan (where supported by device).
+     * Toggle vibration upon successful scan, if supported by device.
      *
-     * @default true
+     * @defaultValue true
      */
     vibration?: boolean;
 }
@@ -279,16 +360,16 @@ export interface FeedbackConfiguration {
  */
 export interface Configuration {
     /**
-     * CSS Selector or reference to the HTML element that will host the visible elements of
-     * the BarcodeReader.
+     * CSS Selector or reference to the HTML element that will host the visible elements of the BarcodeReader.
      *
-     * When using a selector, make sure the selector only matches a single element.
+     * @remarks
+     * When using a selector, make sure the selector only matches a single element, e.g. by using an ID.
      */
     selector: string | HTMLElement;
     /**
      * Mode: can be 'immediate' (default) for always-on scanning, and 'touch', to only scan when a touch occurs.
      *
-     * @default immediate
+     * @defaultValue immediate
      */
     mode?: 'immediate' | 'touch';
     /**
@@ -353,6 +434,15 @@ export interface Rect {
      */
     size: Size;
 }
+/**
+ * A non-intersecting polygon with four points.
+ */
+export interface Quadrilateral {
+    /**
+     * The 4 points forming the quadrilateral.
+     */
+    points: Point[];
+}
 /**
  * Before the STRICH SDK {@link BarcodeReader} can be used, a one-time initialization of the SDK must be performed.
  */
@@ -422,6 +512,12 @@ export interface CodeDetection {
      * Note: this might not be precise, especially for 1D barcodes.
      */
     boundingRect: Rect;
+    /**
+     * The quadrilateral in which the code was detected.
+     *
+     * For rotated or warped codes, this might contain a more precise location estimate than boundingRect.
+     */
+    quadrilateral: Quadrilateral;
     /**
      * The time of detection.
      */
@@ -477,8 +573,10 @@ export class BarcodeReader {
      *
      * This will release all associated resources, and should be called whenever an application no longer needs to
      * scan.
+     *
+     * @return Promise that resolves when the BarcodeReader and its associated resources are fully destroyed.
      */
-    destroy(): void;
+    destroy(): Promise<void>;
     /**
      * Show/hide the BarcodeReader instance.
      *