@monkvision/camera-web 4.0.0

package/LICENSE

@@ -0,0 +1,32 @@
+The Clear BSD License
+
+Copyright (c) [2022] [Monk](http://monk.ai)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted (subject to the limitations in the disclaimer
+below) provided that the following conditions are met:
+
+     * Redistributions of source code must retain the above copyright notice,
+     this list of conditions and the following disclaimer.
+
+     * Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+     * Neither the name of the copyright holder nor the names of its
+     contributors may be used to endorse or promote products derived from this
+     software without specific prior written permission.
+
+NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,182 @@
+# @monkvision/camera-web
+This package provides tools used to handle the Camera in MonkJs web projects in React. It exports a component called
+Camera, that lets you display a camera preview on your app as well as an HUD on top of it, and provides methods
+to take pictures, compress images, etc.
+
+# Installing
+To install the package, you can run the following command :
+
+```shell
+yarn add @monkvision/camera-web
+```
+
+If you are using TypeScript, this package comes with its type definitions integrated, so you don't need to install
+anything else!
+
+# Camera component
+## Camera Preview
+The main component exported by this package is called `Camera`. When placed in a screen this component displays a
+preview of the user's camera video stream. This component is a smart React wrapper for core JavaScript API
+functionnalities that let you access the user camera :
+- Automatic handling of Camera permissions : if you place this component in your app, the user will automatically be
+  asked permission for camera access
+- Error handling and retry-on-error utilities
+- React memoization of elements
+- Render optimizations
+
+```tsx
+// This super simple bit of code will let you display a camera preview in your app.
+import { Camera } from '@monkvision/camera-web';
+
+function MyCameraPreview() {
+  return <Camera />;
+}
+```
+
+## Camera resolution
+The resolution quality of the pictures taken by the Camera component is configurable by passing it as a prop to the
+Camera component :
+
+```tsx
+import { CameraResolution } from '@monkvision/types';
+import { Camera } from '@monkvision/camera-web';
+
+function MyCameraPreview() {
+  return <Camera resolution={CameraResolution.HD_720P} />;
+}
+```
+
+Notes :
+- This option does not affect the resolution of the Camera preview : the preview will always use the highest
+  resolution available on the current device.
+- If the specified resolution is not equal to the one used by the device's native camera, the pictures taken will be
+  scaled to fit the requirements.
+- The resolutions available in the `CameraResolution` enum are all in the 16:9 format.
+- If the aspect ratio of the specified resolution differs from the one of the device's camera, pictures taken will
+  always have the same aspect ratio as the native camera one, and will be scaled in a way to make sure that neither the
+  width, nor the height of the output picture will exceed the dimensions of the specified resolution.
+
+## Compression options
+When pictures are taken by the camera, they are compressed and encoded. The compression format and quality can be
+configured using props on the camera component in the following ways :
+
+```tsx
+import { Camera } from '@monkvision/camera-web';
+import { CompressionFormat } from '@monkvision/types';
+
+function MyCameraPreview() {
+  return <Camera format={CompressionFormat.JPEG} quality={0.4} />;
+}
+```
+
+For more details on the compression options, see the *API* section below.
+
+## Camera HUD
+In order to control the Camera (take pictures etc.), an HUD component can be passed as a prop to the Camera component.
+An HUD component is a component that takes a camera handle (an object used to control the camera) as well as
+a camera preview element as props and that will display the preview with some additional head-up display on top of it.
+When a HUD component is passed to the Camera component, the Camera will place it in the tree, and will pass him down the
+camera handle and preview already configured.
+
+It is definitely possible to write your own custom Camera HUD component, but if you just need a very basic Camera HUD,
+this package exports one already : the `SimpleCameraHUD` component. It will display a button to take the pictures, error
+messages with proper labels in case there are errors when fetching the camera video stream, and a retry button to try
+to fetch the camera stream again if there was an error.
+
+To use this HUD, simply pass the component to the `HUDComponent` prop of the Camera component :
+
+```tsx
+import { Camera, SimpleCameraHUD } from '@monkvision/camera-web';
+
+function MyCameraPreviewWithHUD() {
+  return <Camera HUDComponent={SimpleCameraHUD} />;
+}
+```
+
+The text displayed by this component (error messages, retry button label...) is by default in english. If you want to
+customize the display language, you can specify the fixed language you want to use by using the `lang` prop of the
+component like this :
+
+```tsx
+import { Camera, SimpleCameraHUD } from '@monkvision/camera-web';
+
+function MyCameraPreviewWithGermanHUD() {
+  return <Camera HUDComponent={SimpleCameraHUD} hudProps={{ lang: 'fr' }} />;
+}
+```
+
+The currently supported languages are :
+- English : `'en'` (default)
+- French : `'fr'`
+- German : `'de'`
+- Dutch : `'nl'`
+
+## Creating a Custom HUD
+In order to implement custom Camera HUD, you simply need to create a component that will take a camera handle and a
+camera preview as props. Additional props can be passed to this HUD component using the `hudProps` prop of the Camera
+component :
+
+```tsx
+import { Camera, CameraHUDProps } from '@monkvision/camera-web';
+
+interface MyCustomCameraHUD extends CameraHUDProps {
+  message: string;
+}
+
+function MyCustomCameraHUD({ handle, cameraPreview, message }: MyCustomCameraHUD) {
+  return (
+    <div>
+      {cameraPreview}
+      <button onClick={handle.takePicture}>Take Picture</button>
+      <div>{message}</div>
+    </div>
+  );
+}
+
+function MyCameraPreviewWithCustomHUD() {
+  return (
+    <Camera
+      HUDComponent={MyCustomCameraHUD}
+      hudProps={{ message: 'Hello World!' }}
+    />
+  );
+}
+```
+
+The complete specification of the camera handle is available in the *API* section below.
+
+## Camera Events
+In order to add side effects when some things happen in the Camera, you can specify event handlers callbacks in the
+Camera component props. For now the supported events available are :
+
+- `onPictureTaken: (picture: MonkPicture) => void` : Callback called when the user takes a picture
+
+# API
+## Camera component
+### Description
+Main component exported by this package, displays a Camera preview and the given HUD on top of it.
+
+### Props
+| Prop           | Type                           | Description                                                                                                                     | Required | Default Value             |
+|----------------|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------|----------|---------------------------|
+| resolution     | CameraResolution               | Resolution of the pictures taken by the camera. This does not affect the resolution of the Camera preview.                      |          | `CameraResolution.UHD_4K` |
+| format         | CompressionFormat              | The compression format used to compress images taken by the camera.                                                             |          | `CompressionFormat.JPEG`  |
+| quality        | number                         | The image quality when using a compression format that supports lossy compression. From 0 (lowest quality) to 1 (best quality). |          | `0.6`                     |
+| HUDComponent   | CameraHUDComponent<T>          | The camera HUD component to display on top of the camera preview.                                                               |          |                           |
+| hudProps       | T                              | Additional props passed down to the Camera HUD component.                                                                       |          |                           |
+| onPictureTaken | (picture: MonkPicture) => void | Callback called when a picture has been taken by the user.                                                                      |          |                           |
+| monitoring     | CameraMonitoringConfig         | Extra options that can be passed to configure how the monitoring is handled in the component.                                   |          |                           |
+
+## Camera Handle interface
+### Description
+Object passed to Camera HUD components that is used to control the camera
+
+### Properties
+| Prop              | Type                        | Description                                                                                              |
+|-------------------|-----------------------------|----------------------------------------------------------------------------------------------------------|
+| takePicture       | () => Promise<MonkPicture>  | A function that you can call to ask the camera to take a picture.                                        |
+| error             | UserMediaError &#124; null  | The error details if there has been an error when fetching the camera stream.                            |
+| isLoading         | boolean                     | Boolean indicating if the camera preview is loading.                                                     |
+| retry             | () => void                  | A function to retry the camera stream fetching in case of error.                                         |
+| dimensions        | PixelDimensions &#124; null | The Camera stream dimensions (`null` if there is no stream).                                             |
+| previewDimensions | PixelDimensions &#124; null | The effective video dimensions of the Camera stream on the client screen (`null` if there is no stream). |

package/lib/Camera/Camera.d.ts

@@ -0,0 +1,51 @@
+import { AllOrNone, CameraConfig, RequiredKeys } from '@monkvision/types';
+import { CameraMonitoringConfig } from './monitoring';
+import { CameraEventHandlers, CameraHUDComponent } from './CameraHUD.types';
+/**
+ * Type definition for the HUD component and its props passed to the Camera component. Monk uses this custom type in
+ * order to enforce typing on the following configurations :
+ *
+ * - If the HUD component does not have any required props, the Camera component will allow developers to pass it either
+ * the HUDComponent or both the component and its props.
+ * - If the HUD component does indeed have required props, the Camera component will only accept either BOTH the
+ * HUDComponent and its props, or none of them.
+ *
+ * This is done in order to ensure that developers do not pass HUD components that need specific props to be rendered to
+ * the Camera without actually passing those props as well.
+ */
+export type HUDConfigProps<T extends object> = RequiredKeys<T> extends never ? {
+    /**
+     * HUD component to display above the camera preview.
+     *
+     * Note: If this component needs custom props to be rendered, don't forget to pass them to the Camera in the
+     * `hudProps` props.
+     */
+    HUDComponent?: CameraHUDComponent<T>;
+    /**
+     * Additional props passed to the HUD component when it will be rendered.
+     */
+    hudProps?: T;
+} : AllOrNone<{
+    HUDComponent: CameraHUDComponent<T>;
+    hudProps: T;
+}>;
+/**
+ * Props given to the Camera component. The generic T type corresponds to the prop types of the HUD.
+ */
+export type CameraProps<T extends object> = CameraConfig & CameraEventHandlers & HUDConfigProps<T> & {
+    /**
+     * Additional monitoring config that can be provided to the Camera component.
+     */
+    monitoring?: CameraMonitoringConfig;
+};
+/**
+ * Component used in MonkJs project used to :
+ * - Display a camera preview on the screen
+ * - Display a given camera HUD (buttons) on top of the camera preview
+ * - Provide tools to control the camera (take picture, compress images etc...)
+ *
+ * Please refer to the official documentation of the @monkvision/camera-web package (available
+ * [here](https://github.com/monkvision/monkjs/blob/main/packages/camera-web/README.md)) for more details on how this
+ * component works.
+ */
+export declare function Camera<T extends object>({ resolution, format, quality, allowImageUpscaling, HUDComponent, hudProps, monitoring, onPictureTaken, }: CameraProps<T>): JSX.Element;

package/lib/Camera/Camera.js

@@ -0,0 +1,69 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Camera = void 0;
+var jsx_runtime_1 = require("react/jsx-runtime");
+var react_1 = require("react");
+var types_1 = require("@monkvision/types");
+var common_1 = require("@monkvision/common");
+var hooks_1 = require("./hooks");
+var Camera_styles_1 = require("./Camera.styles");
+/**
+ * Component used in MonkJs project used to :
+ * - Display a camera preview on the screen
+ * - Display a given camera HUD (buttons) on top of the camera preview
+ * - Provide tools to control the camera (take picture, compress images etc...)
+ *
+ * Please refer to the official documentation of the @monkvision/camera-web package (available
+ * [here](https://github.com/monkvision/monkjs/blob/main/packages/camera-web/README.md)) for more details on how this
+ * component works.
+ */
+function Camera(_a) {
+    var _b = _a.resolution, resolution = _b === void 0 ? types_1.CameraResolution.UHD_4K : _b, _c = _a.format, format = _c === void 0 ? types_1.CompressionFormat.JPEG : _c, _d = _a.quality, quality = _d === void 0 ? 0.6 : _d, _e = _a.allowImageUpscaling, allowImageUpscaling = _e === void 0 ? false : _e, HUDComponent = _a.HUDComponent, hudProps = _a.hudProps, monitoring = _a.monitoring, onPictureTaken = _a.onPictureTaken;
+    var previewResolution = (0, react_1.useMemo)(function () { return ((0, common_1.isMobileDevice)() ? types_1.CameraResolution.UHD_4K : types_1.CameraResolution.FHD_1080P); }, []);
+    var _f = (0, hooks_1.useCameraPreview)({
+        resolution: previewResolution,
+        facingMode: hooks_1.CameraFacingMode.ENVIRONMENT,
+    }), videoRef = _f.ref, streamDimensions = _f.dimensions, previewDimensions = _f.previewDimensions, error = _f.error, retry = _f.retry, isPreviewLoading = _f.isLoading, availableCameraDevices = _f.availableCameraDevices, selectedCameraDeviceId = _f.selectedCameraDeviceId;
+    var _g = (0, hooks_1.useCameraCanvas)({
+        resolution: resolution,
+        streamDimensions: streamDimensions,
+        allowImageUpscaling: allowImageUpscaling,
+    }), canvasRef = _g.ref, canvasDimensions = _g.dimensions;
+    var takeScreenshot = (0, hooks_1.useCameraScreenshot)({
+        videoRef: videoRef,
+        canvasRef: canvasRef,
+        dimensions: canvasDimensions,
+    });
+    var compress = (0, hooks_1.useCompression)({ canvasRef: canvasRef, options: { format: format, quality: quality } });
+    var _h = (0, hooks_1.useTakePicture)({
+        compress: compress,
+        takeScreenshot: takeScreenshot,
+        onPictureTaken: onPictureTaken,
+        monitoring: monitoring,
+        availableCameraDevices: availableCameraDevices,
+        selectedCameraDeviceId: selectedCameraDeviceId,
+    }), takePicture = _h.takePicture, isTakePictureLoading = _h.isLoading;
+    var isLoading = isPreviewLoading || isTakePictureLoading;
+    var cameraPreview = (0, react_1.useMemo)(function () { return ((0, jsx_runtime_1.jsxs)("div", __assign({ style: Camera_styles_1.styles['container'] }, { children: [(0, jsx_runtime_1.jsx)("video", { style: Camera_styles_1.styles['cameraPreview'], ref: videoRef, autoPlay: true, playsInline: true, controls: false, muted: true, "data-testid": 'camera-video-preview' }), (0, jsx_runtime_1.jsx)("canvas", { ref: canvasRef, style: Camera_styles_1.styles['cameraCanvas'], "data-testid": 'camera-canvas' })] }))); }, []);
+    return HUDComponent ? ((0, jsx_runtime_1.jsx)(HUDComponent, __assign({ handle: {
+            takePicture: takePicture,
+            error: error,
+            retry: retry,
+            isLoading: isLoading,
+            dimensions: streamDimensions,
+            previewDimensions: previewDimensions,
+        }, cameraPreview: cameraPreview }, (hudProps !== null && hudProps !== void 0 ? hudProps : {})))) : ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: cameraPreview }));
+}
+exports.Camera = Camera;
+//# sourceMappingURL=Camera.js.map

package/lib/Camera/Camera.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Camera.js","sourceRoot":"","sources":["../../src/Camera/Camera.tsx"],"names":[],"mappings":"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"}

package/lib/Camera/Camera.styles.d.ts

@@ -0,0 +1,2 @@
+import { Styles } from '@monkvision/types';
+export declare const styles: Styles;

package/lib/Camera/Camera.styles.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.styles = void 0;
+exports.styles = {
+    container: {
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#000000',
+    },
+    cameraPreview: {
+        width: '100%',
+        height: '100%',
+    },
+    cameraCanvas: {
+        display: 'none',
+    },
+};
+//# sourceMappingURL=Camera.styles.js.map

package/lib/Camera/Camera.styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Camera.styles.js","sourceRoot":"","sources":["../../src/Camera/Camera.styles.ts"],"names":[],"mappings":";;;AAEa,QAAA,MAAM,GAAW;IAC5B,SAAS,EAAE;QACT,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,MAAM;QACf,UAAU,EAAE,QAAQ;QACpB,cAAc,EAAE,QAAQ;QACxB,eAAe,EAAE,SAAS;KAC3B;IACD,aAAa,EAAE;QACb,KAAK,EAAE,MAAM;QACb,MAAM,EAAE,MAAM;KACf;IACD,YAAY,EAAE;QACZ,OAAO,EAAE,MAAM;KAChB;CACF,CAAC"}

package/lib/Camera/CameraHUD.types.d.ts

@@ -0,0 +1,62 @@
+import { ComponentType, ReactElement } from 'react';
+import { PixelDimensions, MonkPicture } from '@monkvision/types';
+import { UserMediaError } from './hooks';
+/**
+ * A set of properties used to handle a Camera preview.
+ */
+export interface CameraHandle {
+    /**
+     * A function that you can call to ask the camera to take a picture.
+     */
+    takePicture: () => Promise<MonkPicture>;
+    /**
+     * The error details if there has been an error when fetching the camera stream.
+     */
+    error: UserMediaError | null;
+    /**
+     * Boolean indicating if the camera preview is loading.
+     */
+    isLoading: boolean;
+    /**
+     * A function to retry the camera stream fetching in case of error.
+     */
+    retry: () => void;
+    /**
+     * The dimensions of the resulting camera stream. Note that these dimensions can differ from the ones given in the
+     * stream constraints if they are not supported or available on the current device.
+     */
+    dimensions: PixelDimensions | null;
+    /**
+     * The effective pixel dimensions of the video stream on the client screen.
+     */
+    previewDimensions: PixelDimensions | null;
+}
+/**
+ * Interface describing the different event handlers for events dispatched by the Camera component.
+ */
+export interface CameraEventHandlers {
+    /**
+     * Callback called when a picture has been taken by the Camera.
+     *
+     * @param picture The picture that has been taken.
+     */
+    onPictureTaken?: (picture: MonkPicture) => void;
+}
+/**
+ * Props accepted by a CameraHUD component.
+ */
+export interface CameraHUDProps {
+    /**
+     * The camera preview element. The HUD component is expected to take this element as a prop and display it however it
+     * wants to.
+     */
+    cameraPreview: ReactElement;
+    /**
+     * The handle used to control the camera.
+     */
+    handle: CameraHandle;
+}
+/**
+ * Component type definition for a Camera HUD component.
+ */
+export type CameraHUDComponent<T extends object = Record<never, never>> = ComponentType<CameraHUDProps & T>;

package/lib/Camera/CameraHUD.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=CameraHUD.types.js.map

package/lib/Camera/CameraHUD.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraHUD.types.js","sourceRoot":"","sources":["../../src/Camera/CameraHUD.types.ts"],"names":[],"mappings":""}

package/lib/Camera/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export * from './useCameraPreview';
+export * from './useCameraScreenshot';
+export * from './useUserMedia';
+export * from './useCameraCanvas';
+export * from './useCompression';
+export * from './useTakePicture';
+export { type CanvasHandle, CameraFacingMode, type CameraConfig } from './utils';

package/lib/Camera/hooks/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CameraFacingMode = void 0;
+__exportStar(require("./useCameraPreview"), exports);
+__exportStar(require("./useCameraScreenshot"), exports);
+__exportStar(require("./useUserMedia"), exports);
+__exportStar(require("./useCameraCanvas"), exports);
+__exportStar(require("./useCompression"), exports);
+__exportStar(require("./useTakePicture"), exports);
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "CameraFacingMode", { enumerable: true, get: function () { return utils_1.CameraFacingMode; } });
+//# sourceMappingURL=index.js.map

package/lib/Camera/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/Camera/hooks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,wDAAsC;AACtC,iDAA+B;AAC/B,oDAAkC;AAClC,mDAAiC;AACjC,mDAAiC;AACjC,iCAAiF;AAArD,yGAAA,gBAAgB,OAAA"}

package/lib/Camera/hooks/useCameraCanvas.d.ts

@@ -0,0 +1,37 @@
+import { RefObject } from 'react';
+import { CameraResolution, PixelDimensions } from '@monkvision/types';
+/**
+ * Object used to configure the camera canvas.
+ */
+export interface CameraCanvasConfig {
+    /**
+     * The resolution of the pictures taken asked by the user of the Camera component.
+     */
+    resolution: CameraResolution;
+    /**
+     * Boolean indicating if the Camera component should allow image upscaling when the asked resolution is bigger than
+     * the one of the device Camera.
+     */
+    allowImageUpscaling: boolean;
+    /**
+     * The dimensions of the video stream.
+     */
+    streamDimensions: PixelDimensions | null;
+}
+/**
+ * Handle used to manage the camera canvas.
+ */
+export interface CameraCanvasHandle {
+    /**
+     * The ref to the canvas element. Forward this ref to the <canvas> tag to set it up.
+     */
+    ref: RefObject<HTMLCanvasElement>;
+    /**
+     * The dimensions of the canvas.
+     */
+    dimensions: PixelDimensions | null;
+}
+/**
+ * Custom hook used to manage the camera <canvas> element used to take video screenshots and encode images.
+ */
+export declare function useCameraCanvas({ resolution, streamDimensions, allowImageUpscaling, }: CameraCanvasConfig): CameraCanvasHandle;

package/lib/Camera/hooks/useCameraCanvas.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCameraCanvas = void 0;
+var react_1 = require("react");
+var utils_1 = require("./utils");
+/**
+ * This function is used to calculate the dimensions of the canvas that will be used to draw the image, thus also
+ * calculating the output dimensions of the image itself, respecting the following logic :
+ * - If the aspect ratio of the stream and constraints are the same, we simply scale the stream to make it fit the
+ * constraints. Note that if `allowImageUpscaling` is `false`, and the stream is smaller than the constraints, we don't
+ * scale "up" the stream image, and we simply return the stream dimensions.
+ * - If the aspect ratio of the stream is different from the one specified in the constraints, the logic is the same,
+ * but the output aspect ratio will be the same one as the stream. The stream dimensions will simply be scaled
+ * following the same logic as the previous point, making sure that neither the width nor the height of the canvas will
+ * exceed the ones described by the constraints.
+ */
+function getCanvasDimensions(_a) {
+    var resolution = _a.resolution, streamDimensions = _a.streamDimensions, allowImageUpscaling = _a.allowImageUpscaling;
+    if (!streamDimensions) {
+        return null;
+    }
+    var isPortrait = streamDimensions.width < streamDimensions.height;
+    var constraintsDimensions = (0, utils_1.getResolutionDimensions)(resolution, isPortrait);
+    var streamRatio = streamDimensions.width / streamDimensions.height;
+    if (constraintsDimensions.width > streamDimensions.width &&
+        constraintsDimensions.height > streamDimensions.height &&
+        !allowImageUpscaling) {
+        return {
+            width: streamDimensions.width,
+            height: streamDimensions.height,
+        };
+    }
+    var fitToHeight = constraintsDimensions.width / streamRatio > constraintsDimensions.height;
+    return {
+        width: fitToHeight ? constraintsDimensions.height * streamRatio : constraintsDimensions.width,
+        height: fitToHeight ? constraintsDimensions.height : constraintsDimensions.width / streamRatio,
+    };
+}
+/**
+ * Custom hook used to manage the camera <canvas> element used to take video screenshots and encode images.
+ */
+function useCameraCanvas(_a) {
+    var resolution = _a.resolution, streamDimensions = _a.streamDimensions, allowImageUpscaling = _a.allowImageUpscaling;
+    var ref = (0, react_1.useRef)(null);
+    var handle = (0, react_1.useMemo)(function () { return ({
+        ref: ref,
+        dimensions: getCanvasDimensions({ resolution: resolution, streamDimensions: streamDimensions, allowImageUpscaling: allowImageUpscaling }),
+    }); }, [resolution, streamDimensions]);
+    (0, react_1.useEffect)(function () {
+        if (handle.dimensions && ref.current) {
+            ref.current.width = handle.dimensions.width;
+            ref.current.height = handle.dimensions.height;
+        }
+    }, [handle.dimensions]);
+    return handle;
+}
+exports.useCameraCanvas = useCameraCanvas;
+//# sourceMappingURL=useCameraCanvas.js.map

package/lib/Camera/hooks/useCameraCanvas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCameraCanvas.js","sourceRoot":"","sources":["../../../src/Camera/hooks/useCameraCanvas.ts"],"names":[],"mappings":";;;AAAA,+BAA8D;AAE9D,iCAAkD;AAmClD;;;;;;;;;;GAUG;AACH,SAAS,mBAAmB,CAAC,EAIR;QAHnB,UAAU,gBAAA,EACV,gBAAgB,sBAAA,EAChB,mBAAmB,yBAAA;IAEnB,IAAI,CAAC,gBAAgB,EAAE;QACrB,OAAO,IAAI,CAAC;KACb;IACD,IAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC;IACpE,IAAM,qBAAqB,GAAG,IAAA,+BAAuB,EAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC9E,IAAM,WAAW,GAAG,gBAAgB,CAAC,KAAK,GAAG,gBAAgB,CAAC,MAAM,CAAC;IAErE,IACE,qBAAqB,CAAC,KAAK,GAAG,gBAAgB,CAAC,KAAK;QACpD,qBAAqB,CAAC,MAAM,GAAG,gBAAgB,CAAC,MAAM;QACtD,CAAC,mBAAmB,EACpB;QACA,OAAO;YACL,KAAK,EAAE,gBAAgB,CAAC,KAAK;YAC7B,MAAM,EAAE,gBAAgB,CAAC,MAAM;SAChC,CAAC;KACH;IACD,IAAM,WAAW,GAAG,qBAAqB,CAAC,KAAK,GAAG,WAAW,GAAG,qBAAqB,CAAC,MAAM,CAAC;IAC7F,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK;QAC7F,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,GAAG,WAAW;KAC/F,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,EAIX;QAHnB,UAAU,gBAAA,EACV,gBAAgB,sBAAA,EAChB,mBAAmB,yBAAA;IAEnB,IAAM,GAAG,GAAG,IAAA,cAAM,EAAoB,IAAI,CAAC,CAAC;IAC5C,IAAM,MAAM,GAAG,IAAA,eAAO,EACpB,cAAM,OAAA,CAAC;QACL,GAAG,KAAA;QACH,UAAU,EAAE,mBAAmB,CAAC,EAAE,UAAU,YAAA,EAAE,gBAAgB,kBAAA,EAAE,mBAAmB,qBAAA,EAAE,CAAC;KACvF,CAAC,EAHI,CAGJ,EACF,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAC/B,CAAC;IAEF,IAAA,iBAAS,EAAC;QACR,IAAI,MAAM,CAAC,UAAU,IAAI,GAAG,CAAC,OAAO,EAAE;YACpC,GAAG,CAAC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC;YAC5C,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;SAC/C;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAExB,OAAO,MAAM,CAAC;AAChB,CAAC;AAtBD,0CAsBC"}

package/lib/Camera/hooks/useCameraPreview.d.ts

@@ -0,0 +1,22 @@
+import { RefObject } from 'react';
+import { PixelDimensions } from '@monkvision/types';
+import { CameraConfig } from './utils';
+import { UserMediaResult } from './useUserMedia';
+/**
+ * An object containing properties used to handle the camera preview.
+ */
+export interface CameraPreviewHandle extends UserMediaResult {
+    /**
+     * The effective pixel dimensions of the video stream on the client screen.
+     */
+    previewDimensions: PixelDimensions | null;
+    /**
+     * React MutableRefObject referencing the video element displaying the camera preview.
+     */
+    ref: RefObject<HTMLVideoElement>;
+}
+/**
+ * Custom hook used to initialize and handle the camera preview. It initializes the camera stream based on the given
+ * configuration, and provides a handle to manage the camera such as the ref to the video element etc.
+ */
+export declare function useCameraPreview(config: CameraConfig): CameraPreviewHandle;