react-native-scanbot-sdk/src/document_scanner/DocumentScannerTypes.ts

Scanbot Document and Barcode Scanner SDK React Native Plugin for Android and iOS

/// Auto-generated with ScanbotSDKCodegenV3. Modifications will be overwritten.
/// Generated from core/schemas/DocumentScannerTypes.yaml

import { AspectRatio, LineSegmentFloat, LineSegmentInt } from '../utils/geometry/Geometry';
import { ToJsonConfiguration } from '../utils/json/JsonSerializationTypes';
import { DeepPartial, PartiallyConstructible, Point } from '../utils/utils';

/**
Engines for document scanning.

- `ML`:
   Use the ML document scanner.
- `LEGACY`:
   Use the legacy edge-based document scanner.
*/
export type DocumentScannerEngineMode = 'ML' | 'LEGACY';

export const DocumentScannerEngineModeValues: DocumentScannerEngineMode[] = ['ML', 'LEGACY'];

/**
Parameters for the document scanner.
*/
export class DocumentScannerParameters extends PartiallyConstructible {
  /**
    The minimum score in percent (0 - 100) of the perspective distortion to accept a detected document.
    Set lower values to accept more perspective distortion.
    
    Warning: Lower values result in more blurred document images.
    
    Default is 75
    */
  public acceptedAngleScore: number = 75;
  /**
    The minimum size in percent (0 - 100) of the screen size to accept a detected document.
    It is sufficient that height or width match the score.
    
    Warning: Lower values result in low resolution document images.
    
    Default is 80
    */
  public acceptedSizeScore: number = 80;
  /**
    The minimum brightness value (0-255) to accept a detected document.
    
    Default is 0
    */
  public acceptedBrightnessThreshold: number = 0;
  /**
    The minimum score in percent (0 - 100) that the aspect ratio of the document
    must match one of the required aspect ratios (if any) to accept a detected document.
    If acceptedAspectRatioScore is more than 0, then the document is only accepted if the aspect ratio
    matches one of the given aspect ratios (if any), otherwise OK_BUT_BAD_ASPECT_RATIO is returned.
    
    Default is 85
    */
  public acceptedAspectRatioScore: number = 85;
  /**
    The possible desired aspect ratios for the detected document.
    A document matches if its aspect ratio matches any of the given aspect ratios.
    If acceptedAspectRatioScore is more than 0, then the document is only accepted if the aspect ratio
    matches one of the given aspect ratios, otherwise OK_BUT_BAD_ASPECT_RATIO is returned.
    If empty, no aspect ratio is preferred.
    */
  public aspectRatios: AspectRatio[] = [];
  /**
    If false, the document scanner will return OK_BUT_ORIENTATION_MISMATCH if the
    detected document orientation does not match the input image orientation,
    e.g. if the document is detected as landscape but the input image is portrait.
    If true, the document scanner will ignore orientation mismatches.
    
    Default is false
    */
  public ignoreOrientationMismatch: boolean = false;

  /** @param source {@displayType `DeepPartial<DocumentScannerParameters>`} */
  public constructor(source: DeepPartial<DocumentScannerParameters> = {}) {
    super();
    if (source.acceptedAngleScore !== undefined) {
      this.acceptedAngleScore = source.acceptedAngleScore;
    }
    if (source.acceptedSizeScore !== undefined) {
      this.acceptedSizeScore = source.acceptedSizeScore;
    }
    if (source.acceptedBrightnessThreshold !== undefined) {
      this.acceptedBrightnessThreshold = source.acceptedBrightnessThreshold;
    }
    if (source.acceptedAspectRatioScore !== undefined) {
      this.acceptedAspectRatioScore = source.acceptedAspectRatioScore;
    }
    if (source.aspectRatios !== undefined) {
      this.aspectRatios = source.aspectRatios.map((it: any) => {
        return new AspectRatio(it);
      });
    }
    if (source.ignoreOrientationMismatch !== undefined) {
      this.ignoreOrientationMismatch = source.ignoreOrientationMismatch;
    }
  }
}

/**
Configuration for the document scanner.
*/
export class DocumentScannerConfiguration extends PartiallyConstructible {
  /**
    The engine to use for document scanning.
    
    Default is ML
    */
  public engineMode: DocumentScannerEngineMode = 'ML';
  /**
    Initial parameters for the document scanner.
    */
  public parameters: DocumentScannerParameters = new DocumentScannerParameters({});

  /** @param source {@displayType `DeepPartial<DocumentScannerConfiguration>`} */
  public constructor(source: DeepPartial<DocumentScannerConfiguration> = {}) {
    super();
    if (source.engineMode !== undefined) {
      this.engineMode = source.engineMode;
    }
    if (source.parameters !== undefined) {
      this.parameters = new DocumentScannerParameters(source.parameters);
    }
  }
}

/**
Status of the document detection.

- `NOT_ACQUIRED`:
   Detection has not yet happened.
- `OK`:
   An acceptable document was detected.
- `OK_BUT_TOO_SMALL`:
   A document was detected, but it is too small.
- `OK_BUT_BAD_ANGLES`:
   A document was detected, but it has too much perspective distortion.
- `OK_BUT_BAD_ASPECT_RATIO`:
   A document was detected, but its aspect ratio is not acceptable.
- `OK_BUT_ORIENTATION_MISMATCH`:
   A document was detected, but its orientation does not match the input image orientation.
- `OK_BUT_OFF_CENTER`:
   A document was detected, but its center is too far away from the input image center.
- `OK_BUT_TOO_DARK`:
   A document was detected, but it is too dark.
- `ERROR_NOTHING_DETECTED`:
   No document was detected.
- `ERROR_TOO_DARK`:
   No document was detected, likely because the input image is too dark.
- `ERROR_TOO_NOISY`:
   No document was detected, likely because the input image is too noisy or has a complex background.
*/
export type DocumentDetectionStatus =
  | 'NOT_ACQUIRED'
  | 'OK'
  | 'OK_BUT_TOO_SMALL'
  | 'OK_BUT_BAD_ANGLES'
  | 'OK_BUT_BAD_ASPECT_RATIO'
  | 'OK_BUT_ORIENTATION_MISMATCH'
  | 'OK_BUT_OFF_CENTER'
  | 'OK_BUT_TOO_DARK'
  | 'ERROR_NOTHING_DETECTED'
  | 'ERROR_TOO_DARK'
  | 'ERROR_TOO_NOISY';

export const DocumentDetectionStatusValues: DocumentDetectionStatus[] = [
  'NOT_ACQUIRED',
  'OK',
  'OK_BUT_TOO_SMALL',
  'OK_BUT_BAD_ANGLES',
  'OK_BUT_BAD_ASPECT_RATIO',
  'OK_BUT_ORIENTATION_MISMATCH',
  'OK_BUT_OFF_CENTER',
  'OK_BUT_TOO_DARK',
  'ERROR_NOTHING_DETECTED',
  'ERROR_TOO_DARK',
  'ERROR_TOO_NOISY',
];

/**
The total and partial scores for the detected document contour.
*/
export class DocumentDetectionScores extends PartiallyConstructible {
  /**
    Weighted sum of all partial scores.
    */
  public readonly totalScore: number;
  /**
    100 points, if the center of the contour is exactly in the image center.
    */
  public readonly distanceScore: number;
  /**
    100 points, if all angles are 90 degrees.
    */
  public readonly angleScore: number;
  /**
    100 points, if the contour occupies at least 50% of the area of the image.
    */
  public readonly sizeScore: number;
  /**
    100 points, if the aspect ratio matches exactly one of the given aspect ratios.
    */
  public readonly aspectRatioScore: number;
  /**
    Percentage of the document contour that the edge detector was able to find (in LEGACY engine mode only).
    */
  public readonly lineCoverageScore: number;
  /**
    Percentage of the image width taken by the detected document.
    */
  public readonly widthScore: number;
  /**
    Percentage of the image height taken by the detected document.
    */
  public readonly heightScore: number;

  /** @param source {@displayType `DeepPartial<DocumentDetectionScores>`} */
  public constructor(source: DeepPartial<DocumentDetectionScores> = {}) {
    super();
    if (source.totalScore !== undefined) {
      this.totalScore = source.totalScore;
    } else {
      throw new Error('totalScore must be present in constructor argument');
    }
    if (source.distanceScore !== undefined) {
      this.distanceScore = source.distanceScore;
    } else {
      throw new Error('distanceScore must be present in constructor argument');
    }
    if (source.angleScore !== undefined) {
      this.angleScore = source.angleScore;
    } else {
      throw new Error('angleScore must be present in constructor argument');
    }
    if (source.sizeScore !== undefined) {
      this.sizeScore = source.sizeScore;
    } else {
      throw new Error('sizeScore must be present in constructor argument');
    }
    if (source.aspectRatioScore !== undefined) {
      this.aspectRatioScore = source.aspectRatioScore;
    } else {
      throw new Error('aspectRatioScore must be present in constructor argument');
    }
    if (source.lineCoverageScore !== undefined) {
      this.lineCoverageScore = source.lineCoverageScore;
    } else {
      throw new Error('lineCoverageScore must be present in constructor argument');
    }
    if (source.widthScore !== undefined) {
      this.widthScore = source.widthScore;
    } else {
      throw new Error('widthScore must be present in constructor argument');
    }
    if (source.heightScore !== undefined) {
      this.heightScore = source.heightScore;
    } else {
      throw new Error('heightScore must be present in constructor argument');
    }
  }

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<DocumentDetectionScores> {
    return {
      totalScore: this.totalScore,
      distanceScore: this.distanceScore,
      angleScore: this.angleScore,
      sizeScore: this.sizeScore,
      aspectRatioScore: this.aspectRatioScore,
      lineCoverageScore: this.lineCoverageScore,
      widthScore: this.widthScore,
      heightScore: this.heightScore,
    };
  }
}

/**
Result of the document contour detection.
*/
export class DocumentDetectionResult extends PartiallyConstructible {
  /**
    Detection status.
    
    Default is NOT_ACQUIRED
    */
  public readonly status: DocumentDetectionStatus = 'NOT_ACQUIRED';
  /**
    The total and partial scores for the detected quad.
    */
  public readonly detectionScores: DocumentDetectionScores;
  /**
    Absolute coordinates of the detected document contour in image space 
    sorted in clockwise order, starting from the top left corner.
    */
  public readonly points: Point[];
  /**
    All detected horizontal lines in image space.
    */
  public readonly horizontalLines: LineSegmentInt[];
  /**
    All detected vertical lines in image space.
    */
  public readonly verticalLines: LineSegmentInt[];
  /**
    Normalized coordinates of the detected document contour in image space 
    sorted in clockwise order, starting from the top left corner.
    */
  public readonly pointsNormalized: Point[];
  /**
    Normalized horizontal lines in image space.
    */
  public readonly horizontalLinesNormalized: LineSegmentFloat[];
  /**
    Normalized vertical lines in image space.
    */
  public readonly verticalLinesNormalized: LineSegmentFloat[];
  /**
    Aspect ratio of the detected document contour.
    */
  public readonly aspectRatio: number;
  /**
    Average brightness, calculated as the average
    of the Value channel in the HSV color space of:
    - the whole image, if no document was detected
    - the document crop, if a document was detected
    Ranges from 0 to 255.
    
    Default is 0
    */
  public readonly averageBrightness: number = 0;

  /** @param source {@displayType `DeepPartial<DocumentDetectionResult>`} */
  public constructor(source: DeepPartial<DocumentDetectionResult> = {}) {
    super();
    if (source.status !== undefined) {
      this.status = source.status;
    }
    if (source.detectionScores !== undefined) {
      this.detectionScores = new DocumentDetectionScores(source.detectionScores);
    } else {
      throw new Error('detectionScores must be present in constructor argument');
    }
    if (source.points !== undefined) {
      this.points = source.points.map((it: any) => {
        return { x: it.x, y: it.y };
      });
    } else {
      throw new Error('points must be present in constructor argument');
    }
    if (source.horizontalLines !== undefined) {
      this.horizontalLines = source.horizontalLines.map((it: any) => {
        return new LineSegmentInt(it);
      });
    } else {
      throw new Error('horizontalLines must be present in constructor argument');
    }
    if (source.verticalLines !== undefined) {
      this.verticalLines = source.verticalLines.map((it: any) => {
        return new LineSegmentInt(it);
      });
    } else {
      throw new Error('verticalLines must be present in constructor argument');
    }
    if (source.pointsNormalized !== undefined) {
      this.pointsNormalized = source.pointsNormalized.map((it: any) => {
        return { x: it.x, y: it.y };
      });
    } else {
      throw new Error('pointsNormalized must be present in constructor argument');
    }
    if (source.horizontalLinesNormalized !== undefined) {
      this.horizontalLinesNormalized = source.horizontalLinesNormalized.map((it: any) => {
        return new LineSegmentFloat(it);
      });
    } else {
      throw new Error('horizontalLinesNormalized must be present in constructor argument');
    }
    if (source.verticalLinesNormalized !== undefined) {
      this.verticalLinesNormalized = source.verticalLinesNormalized.map((it: any) => {
        return new LineSegmentFloat(it);
      });
    } else {
      throw new Error('verticalLinesNormalized must be present in constructor argument');
    }
    if (source.aspectRatio !== undefined) {
      this.aspectRatio = source.aspectRatio;
    } else {
      throw new Error('aspectRatio must be present in constructor argument');
    }
    if (source.averageBrightness !== undefined) {
      this.averageBrightness = source.averageBrightness;
    }
  }

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<DocumentDetectionResult> {
    return {
      status: this.status,
      detectionScores: this.detectionScores.serialize(config),
      points: this.points.map((it: any) => {
        return it;
      }),
      horizontalLines: this.horizontalLines.map((it: any) => {
        return it.serialize(config);
      }),
      verticalLines: this.verticalLines.map((it: any) => {
        return it.serialize(config);
      }),
      pointsNormalized: this.pointsNormalized.map((it: any) => {
        return it;
      }),
      horizontalLinesNormalized: this.horizontalLinesNormalized.map((it: any) => {
        return it.serialize(config);
      }),
      verticalLinesNormalized: this.verticalLinesNormalized.map((it: any) => {
        return it.serialize(config);
      }),
      aspectRatio: this.aspectRatio,
      averageBrightness: this.averageBrightness,
    };
  }
}