railbird/react-native-vision-camera
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Automatically build API documentation (#11)

Browse Source 
* Automatically build API documentation using Typedoc and Docusaurus
* Move MD and move to MDX for Docusaurus Guides
This commit is contained in:
Marc Rousavy
2021-03-03 12:37:43 +01:00
committed by GitHub
parent d7409e31df
commit 0b7b4d50b5
84 changed files with 15605 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
src/Camera.tsx
View File

@@ -101,7 +101,11 @@ export type CameraDeviceProps = {
export type CameraDynamicProps = {
/**
* `true` enables streaming from the camera's input stream, `false` "pauses" the camera input stream.
* Whether the Camera should actively stream video frames, or not.
*
* This can be compared to a Video component, where `isActive` specifies whether the video is paused or not.
*
* > Note: If you fully unmount the `<Camera>` component instead of using `isActive={false}`, the Camera will take a bit longer to start again. In return, it will use less resources since the Camera will be completely destroyed when unmounted.
*/
isActive: boolean;
/**
@@ -174,6 +178,30 @@ type RefType = React.Component<CameraProps> & Readonly<NativeMethods>;
/**
* ### A powerful `<Camera>` component.
*
* The `<Camera>` component's most important (and therefore _required_) properties are:
*
* * `device`: Specifies the {@link CameraDevice} to use. Get a {@link CameraDevice} by using the {@link useCameraDevices} hook, or manually by using the {@link Camera.getAvailableCameraDevices} function.
* * `isActive`: A boolean value that specifies whether the Camera should actively stream video frames or not. This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. If you fully unmount the `<Camera>` component instead of using `isActive={false}`, the Camera will take a bit longer to start again.
*
* @example
* ```jsx
* function App() {
* const devices = useCameraDevices('wide-angle-camera')
* const device = devices.back
*
* if (device == null) return <LoadingView />
* return (
* <Camera
* style={StyleSheet.absoluteFill}
* device={device}
* isActive={true}
* />
* )
* }
* ```
*
* @component
*/
export class Camera extends React.PureComponent<CameraProps, CameraState> {
static displayName = 'Camera';
@@ -241,6 +269,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* @throws {CameraCaptureError} When any kind of error occured. Use the `CameraCaptureError.code` property to get the actual error
*
* @example
* ```js
* camera.current.startRecording({
* onRecordingFinished: (video) => console.log(video),
* onRecordingError: (error) => console.error(error),
@@ -248,6 +277,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* setTimeout(() => {
* camera.current.stopRecording()
* }, 5000)
* ```
*/
public startRecording(options: RecordVideoOptions): void {
const { onRecordingError, onRecordingFinished, ...passThroughOptions } = options;
@@ -269,10 +299,12 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
* Stop the current video recording.
*
* @example
* ```js
* await camera.current.startRecording()
* setTimeout(async () => {
* const video = await camera.current.stopRecording()
* }, 5000)
* ```
*/
public async stopRecording(): Promise<void> {
try {
@@ -284,7 +316,7 @@ export class Camera extends React.PureComponent<CameraProps, CameraState> {
/**
* Focus the camera to a specific point in the coordinate system.
* @param point The point to focus to. This should be relative to the Camera view's coordinate system,
* @param {Point} point The point to focus to. This should be relative to the Camera view's coordinate system,
* and expressed in Pixel on iOS and Points on Android.
* * `(0, 0)` means **top left**.
* * `(CameraView.width, CameraView.height)` means **bottom right**.

1
src/CameraDevice.ts
View File

@@ -21,6 +21,7 @@ export type LogicalCameraDeviceType = 'dual-camera' | 'dual-wide-camera' | 'trip
/**
* Parses an array of physical device types into a single `PhysicalCameraDeviceType` or `LogicalCameraDeviceType`, depending what matches.
* @method
*/
export const parsePhysicalDeviceTypes = (physicalDeviceTypes: PhysicalCameraDeviceType[]): PhysicalCameraDeviceType | LogicalCameraDeviceType => {
if (physicalDeviceTypes.length === 1) {

6
src/CameraError.ts
View File

@@ -36,6 +36,9 @@ export type CaptureError =
export type SystemError = 'system/no-camera-manager';
export type UnknownError = 'unknown/unknown';
/**
* Represents a JSON-style error cause. This contains native `NSError`/`Throwable` information, and can have recursive `.cause` properties until the ultimate cause has been found.
*/
export interface ErrorWithCause {
/**
* The native error's code.
@@ -143,8 +146,9 @@ const isCameraErrorJson = (error: unknown): error is { code: string; message: st
/**
* Tries to parse an error coming from native to a typed JS camera error.
* @param nativeError The native error instance. This is a JSON in the legacy native module architecture.
* @param {CameraError} nativeError The native error instance. This is a JSON in the legacy native module architecture.
* @returns A `CameraRuntimeError` or `CameraCaptureError`, or the nativeError if it's not parsable
* @method
*/
export const tryParseNativeCameraError = <T>(nativeError: T): (CameraRuntimeError | CameraCaptureError) | T => {
if (isCameraErrorJson(nativeError)) {

5
src/hooks/useCameraDevices.ts
View File

@@ -20,21 +20,26 @@ const DefaultCameraDevices: CameraDevices = {
* @returns The best matching `CameraDevice`.
* @throws `CameraRuntimeError` if no device was found.
* @example
* ```jsx
* const device = useCameraDevice()
* // ...
* return <Camera device={device} />
* ```
*/
export function useCameraDevices(): CameraDevices;
/**
* Gets a `CameraDevice` for the requested device type.
*
* @param {PhysicalCameraDeviceType | LogicalCameraDeviceType} deviceType Specifies a device type which will be used as a device filter.
* @returns A `CameraDevice` for the requested device type.
* @throws `CameraRuntimeError` if no device was found.
* @example
* ```jsx
* const device = useCameraDevice('wide-angle-camera')
* // ...
* return <Camera device={device} />
* ```
*/
export function useCameraDevices(deviceType: PhysicalCameraDeviceType | LogicalCameraDeviceType): CameraDevices;

4
src/hooks/useCameraFormat.ts
View File

@@ -8,8 +8,8 @@ import type { Size } from '../utils/FormatFilter';
*
* This function tries to choose a format with the highest possible photo-capture resolution and best matching aspect ratio.
*
* @param device The Camera Device
* @param cameraViewSize The Camera View's size. This can be an approximation and **must be memoized**! Default: `SCREEN_SIZE`
* @param {CameraDevice} device The Camera Device
* @param {Size} cameraViewSize The Camera View's size. This can be an approximation and **must be memoized**! Default: `SCREEN_SIZE`
*
* @returns The best matching format for the given camera device, or `undefined` if the camera device is `undefined`.
*/

32
src/utils/FormatFilter.ts
View File

@@ -9,8 +9,11 @@ import type { CameraDevice, CameraDeviceFormat, FrameRateRange } from 'react-nat
* > Note that this makes the `sort()` function descending, so the first element (`[0]`) is the "best" device.
*
* @example
* ```js
* const devices = camera.devices.sort(sortDevices)
* const bestDevice = devices[0]
* ```
* @method
*/
export const sortDevices = (left: CameraDevice, right: CameraDevice): number => {
let leftPoints = 0;
@@ -27,7 +30,19 @@ export const sortDevices = (left: CameraDevice, right: CameraDevice): number =>
return rightPoints - leftPoints;
};
export type Size = { width: number; height: number };
/**
* Represents a Size in any unit.
*/
export type Size = {
/**
* Points in width.
*/
width: number;
/**
* Points in height.
*/
height: number;
};
const SCREEN_SIZE: Size = {
width: Dimensions.get('window').width,
height: Dimensions.get('window').height,
@@ -64,10 +79,15 @@ const getFormatAspectRatioOverflow = (format: CameraDeviceFormat, size: Size): n
/**
* Filters Camera Device Formats by the best matching aspect ratio for the given `viewSize`.
*
* @param {CameraDeviceFormat[]} formats A list of formats the current device has (see {@link CameraDevice.formats})
* @param {Size} viewSize The size of the camera view which will be used to find the best aspect ratio. Defaults to the screen size.
* @returns A list of Camera Device Formats that match the given `viewSize`' aspect ratio _as close as possible_.
*
* @example
* ```js
* const formats = useMemo(() => filterFormatsByAspectRatio(device.formats, CAMERA_VIEW_SIZE), [device.formats])
* ```
* @method
*/
export const filterFormatsByAspectRatio = (formats: CameraDeviceFormat[], viewSize = SCREEN_SIZE): CameraDeviceFormat[] => {
const minOverflow = formats.reduce((prev, curr) => {
@@ -80,11 +100,14 @@ export const filterFormatsByAspectRatio = (formats: CameraDeviceFormat[], viewSi
};
/**
* Sorts Camera Device Formats by highest photo-capture resolution, descending.
* Sorts Camera Device Formats by highest photo-capture resolution, descending. Use this in a `.sort` function.
*
* @example
* ```js
* const formats = useMemo(() => device.formats.sort(sortFormatsByResolution), [device.formats])
* const bestFormat = formats[0]
* ```
* @method
*/
export const sortFormatsByResolution = (left: CameraDeviceFormat, right: CameraDeviceFormat): number => {
let leftPoints = left.photoHeight * left.photoWidth;
@@ -102,8 +125,13 @@ export const sortFormatsByResolution = (left: CameraDeviceFormat, right: CameraD
/**
* Returns `true` if the given Frame Rate Range (`range`) contains the given frame rate (`fps`)
*
* @param {FrameRateRange} range The range to check if the given `fps` are included in
* @param {number} fps The FPS to check if the given `range` supports.
* @example
* ```js
* // get all formats that support 60 FPS
* const formatsWithHighFps = useMemo(() => device.formats.filter((f) => f.frameRateRanges.some((r) => frameRateIncluded(r, 60))), [device.formats])
* ```
* @method
*/
export const frameRateIncluded = (range: FrameRateRange, fps: number): boolean => fps >= range.minFrameRate && fps <= range.maxFrameRate;