CAPI 235: add onComplete and onPreProcessingChecksFailed callback

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [2.0.0] - 10-06-2024
+
+-   (feat): `init` is now initialised with config and callbacks to retrieve image blob
+-   (feat): add `onComplete` and `onPreProcessingChecksFailed` callbacks
+-   (refactor): `init` no longer returns a promise
+-   (refactor): sdk no longer returns image `metadata`
+
 ## [1.5.1] - 11-06-2024
 
 -   (chore): load demo gif asynchronously before init is called

README.md

@@ -2,74 +2,109 @@
 
 Anyline guidance sdk to retrieve high resolution image from a video stream with tire overlay that helps to point accurately to the tire.
 
+See [Migrating from v1 to v2](#migrating-from-v1-to-v2)
+
 ## Installation
 
 ```shell
 npm install @anyline/anyline-guidance-sdk
 ```
 
-The next step varies based on which environment you are working on.
-
-### ESM
+### SDK Config and Callbacks
 
 ```js
 import init from '@anyline/anyline-guidance-sdk';
+// ...
+// call init when you want to start the sdk
+init(config, callbacks);
 ```
 
-Call the `init()` (refer [Code Example](#code-example)) function whenever you'd want the sdk to start.
+#### 1. `config` (**required**)
 
-### Direction script tag inclusions
-
-Refer [index.html](./public/index.html) for demo implementation.
+The `config` value is used to apply developer specific settings to the SDK.
+Currently, `config` can be used to control the number of times onboarding instructions are shown.
+For example:
 
 ```js
-<script src="anyline-guidance-sdk.js"></script>
+const config = { 
+  onboardingInstructions: { 
+    timesShown: 3, 
+  },
+};
 ```
 
-You can get `anyline-guidance-sdk.js` files in the following ways:
-
-By [installing the package](https://github.com/Anyline/anyline-guidance-sdk) and copying `index.js` from `dist/iife/` folder into your project.
+In this example, onboarding instructions will be shown for a total of 3 times, after which the onboarding instructions will be skipped and sdk will start directly at the Video Stream screen.
 
-(OR)
+> **_NOTE:_** `timesShown` is stored in the localStorage. Clearing the localStorage will reset the setting.
 
-You can also build the sdk by yourself and copy `index.js` from `dist/iife` folder (refer [To Build](#to-build) section).
-
-[//]: # "Call `Anyline.default()` function from within your code whenever you'd want the sdk to start."
-
-### Code Example
+If you wish to show the onboarding instructions everytime the sdk is initialised, set `config` like so
 
 ```js
-const { blob, metadata } = await init();
-// blob represents the image captured by SDK in Blob format
-blob: Blob
-// other metadata related to image viz. width, height and fileSize
-metadata: {
-  width: number,
-  height: number,
-  fileSize: number,
-}
+const config = {};
 ```
 
-### SDK Config
+#### 2. `callbacks` (**required**)
 
-By default, we show onboarding instructions screen everytime the SDK opens, this informs users how to capture a better tire image. You can configure this setting to limit the number of times this onboarding instructions screen is shown.
+The `callbacks` object consists of two functions: `onComplete` and `onPreProcessingChecksFailed`
 
-To achieve this, call sdk `init` method like so:
+-   `onComplete` (**required**) is called once the SDK has finished processing the image.
+-   `onPreProcessingChecksFailed` (**optional**) is called when the image captured by an end-user has failed to pass image quality checks. The user has the option to either proceed with the image or take a new picture.
+    Example:
 
 ```js
-const { blob } = init({
+const callbacks = { 
+  onComplete: ({ blob }) => {
+    // final returned image
+  }, 
+  onPreProcessingChecksFailed: ({ blob, message }) => {
+    // intermediate image
+  },
+};
+```
+
+---
+
+### Migrating from v1 to v2
+
+#### Key changes
+1. Initialisation
+  - v1: `init` called with a single `config` object and returned a promise
+  - v2: `init` called with two arguments: `config` and `callbacks` and no longer returns a promise (use `callbacks` to retrieve blob).
+2. Config
+  - v1: can be empty
+  - v2: for empty config use `{}`
+3. Callbacks (v2 only)
+  - `onComplete` **required**
+  - `onPreProcessingChecksFailed` **optional**
+
+#### Example
+v1:
+```ts
+const { blob } = await init({
   onboardingInstructions: {
     timesShown: 3
   }
 })
 ```
-where `3` is the number of times you'd want to show the onboarding instructions screen everytime a user opens the SDK. When they open the SDK for the 4th time, they will not see the onboarding instructions screen and will be taken directly to the video stream screen.
 
-This feature comes in handy when we assume that after the user has seen onboarding instruction for a certain number of times, they understand the instructions already and thus do not need to read it again. 
+v2:
+```ts
+const config = {
+  onboardingInstructions: {
+    timesShown: 3
+  }
+};
+const callbacks = {
+  onComplete: ({ blob }) => {
+    // ...
+  }
+}
+init(config, callbacks)
+```
 
-If you do not want to show the instructions at all, you can set `timesShown` to `0`.
+See [SDK Config and Callbacks](#sdk-config-and-callbacks) for detailed implementation about `config` and `callbacks`.
 
-Note: This config works by storing a variable in `localStorage`. If you have a functionality within your website/web app that clears the `localStorage`, then this configuration will not be enforced and the onboarding instructions will be shown everytime regardless of what you set `timesShown` to.
+---
 
 ## Developers / Contributors
 

esbuild/injectCSSPlugin.js

@@ -50,7 +50,7 @@ export const injectCSSPlugin = baseDir => {
 						return;
 					}
 					const regex =
-						/(\w+)\.id="anyline-guidance-sdk-style",\1\.textContent=""/;
+						/([$\w]+)\.id="anyline-guidance-sdk-style",\1\.textContent=""/;
 					const replacement = `$1.id="anyline-guidance-sdk-style",$1.textContent=\`${allCSS}\``;
 					const updatedData = data.replace(regex, replacement);
 					fs.writeFile(filePath, updatedData, 'utf8', err => {

package.json

@@ -1,7 +1,7 @@
 {
 	"author": "Anyline",
 	"name": "@anyline/anyline-guidance-sdk",
-	"version": "1.5.1",
+	"version": "2.0.0",
 	"main": "dist/cjs/index.js",
 	"module": "dist/esm/index.js",
 	"types": "dist/esm/index.d.ts",
@@ -72,7 +72,9 @@
 		"typescript-eslint": "^7.5.0",
 		"wdio-wait-for": "^3.0.11"
 	},
-	"dependencies": {},
+	"dependencies": {
+		"joi": "^17.13.1"
+	},
 	"resolutions": {
 		"@typescript-eslint/parser": "6.21.0",
 		"@typescript-eslint/eslint-plugin": "6.21.0"

public/index.html

@@ -14,6 +14,11 @@
 				min-width: 100px;
 				height: 54px;
 			}
+			#poor-quality-image-wrapper > img {
+				margin-bottom: 12px;
+				width: 100%;
+				max-width: 500px;
+			}
 		</style>
 		<!-- Anyline Guidance SDK js -->
 		<script src="./build/index.js"></script>
@@ -24,33 +29,45 @@
 					const errorElement = document.getElementById('error');
 					errorElement.innerText = '';
 					try {
-						const {
-							blob,
-							metadata: { width, height, fileSize },
-						} = await Anyline.default(config);
-						blobUrl = URL.createObjectURL(blob);
-						const imgElement = document.getElementById('new-image');
-
-						imgElement.src = blobUrl;
+						Anyline.default(config, {
+							onComplete: ({ blob }) => {
+								blobUrl = URL.createObjectURL(blob);
+								const imgElement =
+									document.getElementById('new-image');
 
-						const specsElement =
-							document.getElementById('image-specs');
-						specsElement.innerText = `Image specs: ${width}px X ${height}px, ${fileSize}kb`;
+								imgElement.src = blobUrl;
+							},
+							onPreProcessingChecksFailed: ({
+								blob,
+								message,
+							}) => {
+								// console.log('Poor quality image', blob);
+								// console.log('Message', message);
+								const poorQualityImageWrapper =
+									document.getElementById(
+										'poor-quality-image-wrapper'
+									);
+								blobUrl = URL.createObjectURL(blob);
+								const imgElement = new Image();
+								imgElement.src = blobUrl;
+								poorQualityImageWrapper.appendChild(imgElement);
+							},
+						});
 					} catch (err) {
 						console.log('Error', err);
 						errorElement.innerText = err;
 					}
 				};
 
+				const config = {
+					onboardingInstructions: {
+						timesShown: 3,
+					},
+				};
+
 				document
 					.getElementById('start-sdk-btn')
-					.addEventListener('click', () =>
-						startSdk({
-							onboardingInstructions: {
-								timesShown: 3,
-							},
-						})
-					);
+					.addEventListener('click', () => startSdk(config, 'asd'));
 
 				document
 					.getElementById('download-button')
@@ -78,17 +95,22 @@
 		<button id="reset-times-shown" class="button">
 			Reset timesShown to 3
 		</button>
-		<br /><br />
+		<br />
+		<hr />
+		Default image section <br />
 		<img
 			id="new-image"
-			alt="Demo"
+			alt=""
 			width="100%"
 			style="max-width: 500px"
 		/><br />
-		<div id="image-specs"></div>
 		<br />
 		<button id="download-button" class="button">Download Image</button>
 		<br />
+		<hr />
+		Poor quality image(s) section <br />
+		<div id="poor-quality-image-wrapper"></div>
+		<br />
 		<div id="error"></div>
 	</body>
 </html>

src/camera/init.ts

@@ -1,12 +1,11 @@
 import createModal from '../components/modal';
-import { getImageSpecification } from './getImageSpecification';
 import injectCSS from '../lib/injectCSS';
-import ImageManager from '../modules/ImageManager';
 import HostManager from '../modules/HostManager';
 import initRouter from '../lib/initRouter';
-import { type Config } from '../modules/ConfigManager';
+import { type Config } from '../modules/ConfigManager/ConfigManager';
 import OpenCVManager from '../modules/OpenCVManager';
 import DocumentScrollController from '../modules/DocumentScrollController';
+import CallbackHandler from '../modules/CallbackHandler';
 
 // load demoInstructionsImage chunk before it is requested
 // to ensure lower loading time for the gif when sdk is initialised
@@ -16,23 +15,41 @@ void import(
 	console.log('Error loading demo gif');
 });
 
-export interface ImageMetadata {
-	width: number;
-	height: number;
-	fileSize: number;
+export interface OnComplete {
+	blob: Blob;
 }
 
-export interface SDKReturnType {
+export interface OnPreProcessingChecksFailed {
 	blob: Blob;
-	metadata: ImageMetadata;
+	message: string;
+}
+
+export interface Callbacks {
+	onComplete: (response: OnComplete) => void;
+	onPreProcessingChecksFailed?: (
+		response: OnPreProcessingChecksFailed
+	) => void;
 }
 
-async function init(config?: Config): Promise<SDKReturnType> {
+function init(config: Config, callbacks: Callbacks): void {
 	if (
 		navigator.mediaDevices === null ||
 		navigator.mediaDevices === undefined
 	) {
-		await Promise.reject(new Error('Unsupported device'));
+		throw new Error('Unsupported device');
+	}
+
+	const callbackHandler = CallbackHandler.getInstance();
+	// register callbacks
+	const { onComplete, onPreProcessingChecksFailed } = callbacks;
+	callbackHandler.setOnComplete(onComplete);
+	if (
+		onPreProcessingChecksFailed != null &&
+		onPreProcessingChecksFailed !== undefined
+	) {
+		callbackHandler.setOnPreProcessingChecksFailedCallback(
+			onPreProcessingChecksFailed
+		);
 	}
 
 	const opencvManager = OpenCVManager.getInstance();
@@ -51,12 +68,6 @@ async function init(config?: Config): Promise<SDKReturnType> {
 	const modal = createModal(shadowRoot);
 
 	initRouter(modal, config);
-
-	const imageManager = ImageManager.getInstance();
-	const blob = await imageManager.getImageBlob();
-	const metadata = await getImageSpecification(blob);
-
-	return { blob, metadata };
 }
 
 export default init;