react-native-scanbot-sdk/src/dqa/DocumentQualityAnalyzerTypes.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/DocumentQualityAnalyzerTypes.yaml

import { ImageRef } from '../imageRef/image';
import { ToJsonConfiguration } from '../utils/json/JsonSerializationTypes';
import { DeepPartial, PartiallyConstructible } from '../utils/utils';

/**
Result of document quality analysis.

- `VERY_POOR`:
   Very poor quality.
- `POOR`:
   Poor quality.
- `REASONABLE`:
   Reasonable quality.
- `GOOD`:
   Good quality.
- `EXCELLENT`:
   Excellent quality.
*/
export type DocumentQuality = 'VERY_POOR' | 'POOR' | 'REASONABLE' | 'GOOD' | 'EXCELLENT';

export const DocumentQualityValues: DocumentQuality[] = [
  'VERY_POOR',
  'POOR',
  'REASONABLE',
  'GOOD',
  'EXCELLENT',
];

/**
Point in the quality-number of symbols space to separate quality levels.
*/
export class DocumentQualityThreshold extends PartiallyConstructible {
  /**
    Symbol quality.
    */
  public readonly symbolQuality: number;
  /**
    Symbol ratio.
    */
  public readonly symbolRatio: number;

  /** @param source {@displayType `DeepPartial<DocumentQualityThreshold>`} */
  public constructor(source: DeepPartial<DocumentQualityThreshold> = {}) {
    super();
    if (source.symbolQuality !== undefined) {
      this.symbolQuality = source.symbolQuality;
    } else {
      throw new Error('symbolQuality must be present in constructor argument');
    }
    if (source.symbolRatio !== undefined) {
      this.symbolRatio = source.symbolRatio;
    } else {
      throw new Error('symbolRatio must be present in constructor argument');
    }
  }
}

/**
Document Quality Analyzer configuration.
*/
export class DocumentQualityAnalyzerConfiguration extends PartiallyConstructible {
  /**
    Quality thresholds to separate quality levels.
    */
  public qualityThresholds: DocumentQualityThreshold[] = [
    new DocumentQualityThreshold({ symbolQuality: 0.5, symbolRatio: 0.5 }),
    new DocumentQualityThreshold({ symbolQuality: 0.7, symbolRatio: 0.3 }),
    new DocumentQualityThreshold({ symbolQuality: 0.85, symbolRatio: 0.3 }),
    new DocumentQualityThreshold({ symbolQuality: 0.9, symbolRatio: 0.1 }),
  ];
  /**
    quality levels.
    */
  public qualityIndices: DocumentQuality[] = [
    'VERY_POOR',
    'POOR',
    'REASONABLE',
    'GOOD',
    'EXCELLENT',
  ];
  /**
    Enable orientation detection. Document orientation will be returned in `DocumentQualityAnalyzerResult.orientation`.
    
    Default is false
    */
  public detectOrientation: boolean = false;
  /**
    Inspect small text (typically less than 12 pixels height) when analyzing the document quality.
    If true, processing will be slower, but when the quality issue with a document is the low resolution of the text,
    then the issue will be caught.
    
    Default is false
    */
  public inspectSmallText: boolean = false;
  /**
    Maximum image size in pixels, if image is bigger, it will be resized.
    
    Default is 2000
    */
  public maxImageSize: number = 2000;
  /**
    If estimated number of symbols is less than this value, return that document is not found.
    
    Default is 20
    */
  public minEstimatedNumberOfSymbolsForDocument: number = 20;
  /**
    At least this fraction of the image will be processed, range is from 0 to 1.
    
    Default is 0
    */
  public minProcessedFraction: number = 0.0;
  /**
    At most this fraction of the image will be processed, range is from 0 to 1.
    
    Default is 0.5
    */
  public maxProcessedFraction: number = 0.5;
  /**
    If this number of symbols is found and minProcessedFraction of the image is processed, the processing stops.
    
    Default is 100
    */
  public earlyStopIfNSymbolsFound: number = 100;
  /**
    Image will be processed in tiles of this size; will be ignored if image is small.
    
    Default is 300
    */
  public tileSize: number = 300;
  /**
    If true, will return the quality heatmap as a part of the result.
    In this case, the entire image will be processed and the minProcessedFraction will be ignored.
    Useful for debugging situations where the returned quality doesn't appear to match the perceived quality.
    
    Default is false
    */
  public returnQualityHeatmap: boolean = false;

  /** @param source {@displayType `DeepPartial<DocumentQualityAnalyzerConfiguration>`} */
  public constructor(source: DeepPartial<DocumentQualityAnalyzerConfiguration> = {}) {
    super();
    if (source.qualityThresholds !== undefined) {
      this.qualityThresholds = source.qualityThresholds.map((it: any) => {
        return new DocumentQualityThreshold(it);
      });
    }
    if (source.qualityIndices !== undefined) {
      this.qualityIndices = source.qualityIndices.map((it: any) => {
        return it;
      });
    }
    if (source.detectOrientation !== undefined) {
      this.detectOrientation = source.detectOrientation;
    }
    if (source.inspectSmallText !== undefined) {
      this.inspectSmallText = source.inspectSmallText;
    }
    if (source.maxImageSize !== undefined) {
      this.maxImageSize = source.maxImageSize;
    }
    if (source.minEstimatedNumberOfSymbolsForDocument !== undefined) {
      this.minEstimatedNumberOfSymbolsForDocument = source.minEstimatedNumberOfSymbolsForDocument;
    }
    if (source.minProcessedFraction !== undefined) {
      this.minProcessedFraction = source.minProcessedFraction;
    }
    if (source.maxProcessedFraction !== undefined) {
      this.maxProcessedFraction = source.maxProcessedFraction;
    }
    if (source.earlyStopIfNSymbolsFound !== undefined) {
      this.earlyStopIfNSymbolsFound = source.earlyStopIfNSymbolsFound;
    }
    if (source.tileSize !== undefined) {
      this.tileSize = source.tileSize;
    }
    if (source.returnQualityHeatmap !== undefined) {
      this.returnQualityHeatmap = source.returnQualityHeatmap;
    }
  }
}

/**
Result of document quality analysis. It can be used to determine, e.g., if a document is good enough to be used for OCR processing.
*/
export class DocumentQualityAnalyzerResult extends PartiallyConstructible {
  /**
    True if a document was found.
    */
  public readonly documentFound: boolean;
  /**
    Quality of the document, if found.
    */
  public readonly quality: DocumentQuality | null;
  /**
    Dominant orientation of the document, if found and if orientation detection is enabled.
    The value is in degrees counter-clockwise, where 0 corresponds to the document
    being straight, and the value is in the range of [-180, 180].
    To rotate the document to be straight, rotate the image clockwise by this value.
    */
  public readonly orientation: number | null;
  /**
    Cumulative histogram where every entry is equal to the number of symbols with quality equal or lower than N percent, where N is the index of the entry in the array.
    */
  public readonly cumulativeQualityHistogram: number[];
  /**
    Quality heatmap.
    Black marks areas of no detected text. Colors represent the quality of detected text,
    with red meaning the lowest quality and yellow and green meaning progressively higher quality.
    */
  public readonly qualityHeatmap: ImageRef | null = null;

  /** @param source {@displayType `DeepPartial<DocumentQualityAnalyzerResult>`} */
  public constructor(source: DeepPartial<DocumentQualityAnalyzerResult> = {}) {
    super();
    if (source.documentFound !== undefined) {
      this.documentFound = source.documentFound;
    } else {
      throw new Error('documentFound must be present in constructor argument');
    }
    if (source.quality !== undefined) {
      this.quality =
        source.quality != null
          ? DocumentQualityValues.includes(source.quality)
            ? source.quality
            : null
          : null;
    } else {
      throw new Error('quality must be present in constructor argument');
    }
    if (source.orientation !== undefined) {
      this.orientation = source.orientation != null ? source.orientation : null;
    } else {
      throw new Error('orientation must be present in constructor argument');
    }
    if (source.cumulativeQualityHistogram !== undefined) {
      this.cumulativeQualityHistogram = source.cumulativeQualityHistogram.map((it: any) => {
        return it;
      });
    } else {
      throw new Error('cumulativeQualityHistogram must be present in constructor argument');
    }
    if (source.qualityHeatmap !== undefined) {
      this.qualityHeatmap =
        source.qualityHeatmap != null ? ImageRef.From(source.qualityHeatmap) : null;
    }
  }

  public async serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): Promise<DeepPartial<DocumentQualityAnalyzerResult>> {
    return {
      documentFound: this.documentFound,
      quality: this.quality != null ? this.quality : null,
      orientation: this.orientation != null ? this.orientation : null,
      cumulativeQualityHistogram: this.cumulativeQualityHistogram.map((it: any) => {
        return it;
      }),
      qualityHeatmap: config.serializeImages
        ? this.qualityHeatmap != null
          ? await this.qualityHeatmap.serialize(config.imageSerializationMode)
          : null
        : undefined,
    };
  }

  private _released: Boolean = false;

  public release() {
    if (this._released) {
      return;
    }
    {
      if (this.qualityHeatmap != null) {
        this.qualityHeatmap.release();
      }
    }
    this._released = true;
  }

  public async encodeImages(): Promise<void> {
    if (this.qualityHeatmap != null) {
      await this.qualityHeatmap.encodeInPlace();
    }
  }
}