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

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

/**
Result of OCR text recognition.
*/
export class OcrResult extends PartiallyConstructible {
  /**
    Maximum number of accumulated frames to inspect before actual result is returned.
    */
  public readonly text: string;
  /**
    Minimum number of accumulated frames that have equal result.
    */
  public readonly confidence: number;

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

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<OcrResult> {
    return {
      text: this.text,
      confidence: this.confidence,
    };
  }
}

/**
Field validation status.

Optical character recognition (OCR) invariably introduces errors in the recognized text.
There are numerous ways to verify that what has been recognized is, in fact, what was
written in the document.

The best way to validate the value of a field is for it to have a known format or validation
logic. For example, an IBAN number has a known format and two check digits that make it
very unlikely that a value with OCR errors will pass validation. Fields with known
validation rules will have a validation status of either VALID or INVALID.

Fields whose value can be inferred from other fields, or from domain knowledge (for example,
the field may have the same value in every instance of this type of document), will have the
status INFERRED. Inferring the value of a field is a strong validation method, provided that
there are no unexpected changes to the document format.

Fields that do not have validation rules and cannot be inferred can still be validated by checking whether the same
value is recognized from multiple attempts, e.g. across multiple frames of a camera stream.
If the same value is recognized in multiple frames, the value is considered CONFIRMED, otherwise
it will have the status NONE. This is the least strict validation method, as it does not protect
from systemic OCR errors, but in practice it still provides good results for most fields.

- `INVALID`:
   Field value failed validation. This status is used for fields that have validation rules, like
   IBAN, date fields, etc. that have check digits or a known format that can be validated.
- `NONE`:
   Field value was not validated, typically because the field does not support validation and the value
   has not been seen enough times to confirm it.
   If the same value is seen in multiple frames, the validation status will transition to CONFIRMED,
   but only if that particular recognizer supports multiple frame accumulation.
- `CONFIRMED`:
   The same field value was recognized in multiple frames, thereby confirming the value.
   Occurs only for fields that have no validation rules otherwise.
   A CONFIRMED value gives a strong guarantee that the field value has been read out without errors,
   but not as strong as VALID. The value may still be incorrect, due to systemic OCR errors.
   In case of OCR errors, increase the number of frames needed to confirm the value in the
   recognizer configuration.
- `INFERRED`:
   Field value was inferred from other fields or from domain knowledge.
   The field value may differ from what is actually written in the document in unexpected situations.
- `VALID`:
   Field value passed validation. This status is used for fields that have validation rules, like
   IBAN, date fields, etc. that have check digits or a known format that can be validated.
   The VALID status gives the strongest guarantee that the field value has been read out without errors.
- `IGNORED`:
   The document contains a field of this type, but recognition for this field is disabled.
   The value of this field is always empty, although the field may be non-empty in the document.
*/
export type FieldValidationStatus =
  | 'INVALID'
  | 'NONE'
  | 'CONFIRMED'
  | 'INFERRED'
  | 'VALID'
  | 'IGNORED';

export const FieldValidationStatusValues: FieldValidationStatus[] = [
  'INVALID',
  'NONE',
  'CONFIRMED',
  'INFERRED',
  'VALID',
  'IGNORED',
];

/**
Type of parsing applied to field.

- `ISO_DATE`:
   Field value is parsed as ISO 8601 date in format YYYY-MM-DD.
- `ISO_COUNTRY_ALPHA_2`:
   Field value is parsed as ISO 3166-1 alpha-2 country code. E.g. "DE" for Germany.
- `ISO_COUNTRY_ALPHA_3`:
   Field value is parsed as ISO 3166-1 alpha-3 country code. E.g. "DEU" for Germany.
- `ISO_COUNTRY_NUMERIC`:
   Field value is parsed as ISO 3166-1 numeric country code. E.g. "276" for Germany.
- `ISO_COUNTRY_NAME`:
   Field value is parsed as ISO 3166-1 country name. E.g. "Germany".
- `GENDER`:
   Field value is parsed as "Male", "Female".
*/
export type FieldDataFormat =
  | 'ISO_DATE'
  | 'ISO_COUNTRY_ALPHA_2'
  | 'ISO_COUNTRY_ALPHA_3'
  | 'ISO_COUNTRY_NUMERIC'
  | 'ISO_COUNTRY_NAME'
  | 'GENDER';

export const FieldDataFormatValues: FieldDataFormat[] = [
  'ISO_DATE',
  'ISO_COUNTRY_ALPHA_2',
  'ISO_COUNTRY_ALPHA_3',
  'ISO_COUNTRY_NUMERIC',
  'ISO_COUNTRY_NAME',
  'GENDER',
];

/**
Parsed data.
*/
export class FieldParsedData extends PartiallyConstructible {
  /**
    Parsing type.
    */
  public readonly type: FieldDataFormat;
  /**
    Parsed value.
    */
  public readonly value: string;

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

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<FieldParsedData> {
    return {
      type: this.type,
      value: this.value,
    };
  }
}

/**
Generic Document Type.
*/
export class FieldType extends PartiallyConstructible {
  /**
    Local field type name scoped to the containing document type.
    */
  public readonly name: string;
  /**
    Unique global field type name prefixed with the document types of all containing documents.
    */
  public readonly fullName: string;
  /**
    Normalized global field type name. Fields in document types derived from the same base document type in the schema will have the same normalized name.
    */
  public readonly normalizedName: string;
  /**
    Commonly occurring fields that have the same semantic meaning in different document types will often have a set common type.
    */
  public readonly commonType: CommonFieldType | null;
  /**
    A document can contain multiple fields of the same name, the property serves for storing natural order of such fields, null if multiple entries aren't allowed for this field.
    */
  public readonly listIndex: number | null = null;

  /** @param source {@displayType `DeepPartial<FieldType>`} */
  public constructor(source: DeepPartial<FieldType> = {}) {
    super();
    if (source.name !== undefined) {
      this.name = source.name;
    } else {
      throw new Error('name must be present in constructor argument');
    }
    if (source.fullName !== undefined) {
      this.fullName = source.fullName;
    } else {
      throw new Error('fullName must be present in constructor argument');
    }
    if (source.normalizedName !== undefined) {
      this.normalizedName = source.normalizedName;
    } else {
      throw new Error('normalizedName must be present in constructor argument');
    }
    if (source.commonType !== undefined) {
      this.commonType =
        source.commonType != null
          ? CommonFieldTypeValues.includes(source.commonType)
            ? source.commonType
            : null
          : null;
    } else {
      throw new Error('commonType must be present in constructor argument');
    }
    if (source.listIndex !== undefined) {
      this.listIndex = source.listIndex != null ? source.listIndex : null;
    }
  }

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<FieldType> {
    return {
      name: this.name,
      fullName: this.fullName,
      normalizedName: this.normalizedName,
      commonType: this.commonType != null ? this.commonType : null,
      listIndex: this.listIndex != null ? this.listIndex : null,
    };
  }
}

/**
Generic document field.
*/
export class Field extends PartiallyConstructible {
  /**
    The type of the field.
    */
  public readonly type: FieldType;
  /**
    Value of the field. Applicable only to text fields.
    */
  public readonly value: OcrResult | null;
  /**
    Confidence weight.
    
    Default is 1.0
    */
  public readonly confidenceWeight: number = 1.0;
  /**
    Crop of the field.
    */
  public readonly image: ImageRef | null = null;
  /**
    Coordinates of the field in the root document coordinate system.
    */
  public readonly polygonInRoot: Point[];
  /**
    Field validation status. Applicable only to fields that support some kind of validation.
    
    Default is NONE
    */
  public readonly validationStatus: FieldValidationStatus = 'NONE';
  /**
    Parsed data.
    */
  public readonly parsedData: FieldParsedData[] = [];

  /** @param source {@displayType `DeepPartial<Field>`} */
  public constructor(source: DeepPartial<Field> = {}) {
    super();
    if (source.type !== undefined) {
      this.type = new FieldType(source.type);
    } else {
      throw new Error('type must be present in constructor argument');
    }
    if (source.value !== undefined) {
      this.value = source.value != null ? new OcrResult(source.value) : null;
    } else {
      throw new Error('value must be present in constructor argument');
    }
    if (source.confidenceWeight !== undefined) {
      this.confidenceWeight = source.confidenceWeight;
    }
    if (source.image !== undefined) {
      this.image = source.image != null ? ImageRef.From(source.image) : null;
    }
    if (source.polygonInRoot !== undefined) {
      this.polygonInRoot = source.polygonInRoot.map((it: any) => {
        return { x: it.x, y: it.y };
      });
    } else {
      throw new Error('polygonInRoot must be present in constructor argument');
    }
    if (source.validationStatus !== undefined) {
      this.validationStatus = source.validationStatus;
    }
    if (source.parsedData !== undefined) {
      this.parsedData = source.parsedData.map((it: any) => {
        return new FieldParsedData(it);
      });
    }
  }

  public async serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): Promise<DeepPartial<Field>> {
    return {
      type: this.type.serialize(config),
      value: this.value != null ? this.value.serialize(config) : null,
      confidenceWeight: this.confidenceWeight,
      image: config.serializeImages
        ? this.image != null
          ? await this.image.serialize(config.imageSerializationMode)
          : null
        : undefined,
      polygonInRoot: this.polygonInRoot.map((it: any) => {
        return it;
      }),
      validationStatus: this.validationStatus,
      parsedData: this.parsedData.map((it: any) => {
        return it.serialize(config);
      }),
    };
  }

  private _released: Boolean = false;

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

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

/**
Generic Document Type.
*/
export class GenericDocumentType extends PartiallyConstructible {
  /**
    Local document type name.
    */
  public readonly name: string;
  /**
    Unique global document type name prefixed with the document types of all containing documents.
    */
  public readonly fullName: string;
  /**
    Normalized global document type name. Common document types appearing as child documents in different places will often have the same normalized type name.
    */
  public readonly normalizedName: string;
  /**
    A document can contain multiple fields of the same name, the property serves for storing natural order of such fields, null if multiple entries aren't allowed for this field.
    */
  public readonly listIndex: number | null = null;

  /** @param source {@displayType `DeepPartial<GenericDocumentType>`} */
  public constructor(source: DeepPartial<GenericDocumentType> = {}) {
    super();
    if (source.name !== undefined) {
      this.name = source.name;
    } else {
      throw new Error('name must be present in constructor argument');
    }
    if (source.fullName !== undefined) {
      this.fullName = source.fullName;
    } else {
      throw new Error('fullName must be present in constructor argument');
    }
    if (source.normalizedName !== undefined) {
      this.normalizedName = source.normalizedName;
    } else {
      throw new Error('normalizedName must be present in constructor argument');
    }
    if (source.listIndex !== undefined) {
      this.listIndex = source.listIndex != null ? source.listIndex : null;
    }
  }

  public serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): DeepPartial<GenericDocumentType> {
    return {
      name: this.name,
      fullName: this.fullName,
      normalizedName: this.normalizedName,
      listIndex: this.listIndex != null ? this.listIndex : null,
    };
  }
}

/**
Generic document.
*/
export class GenericDocument extends PartiallyConstructible {
  /**
    Document type.
    */
  public readonly type: GenericDocumentType;
  /**
    List of document fields.
    */
  public readonly fields: Field[];
  /**
    List of document sub-documents.
    */
  public readonly children: GenericDocument[];
  /**
    Coordinates of the document in the parent document coordinate system.
    */
  public readonly quad: Point[];
  /**
    Coordinates of the document in the root document coordinate system.
    */
  public readonly quadInRoot: Point[];
  /**
    Image crop of the document.
    */
  public readonly crop: ImageRef | null = null;
  /**
    The average confidence in the accuracy of the document recognition result.
    
    Default is 0
    */
  public readonly confidence: number = 0.0;
  /**
    The weight of the confidence. Can be used to calculate the weighted average confidence of two documents.
    
    Default is 0
    */
  public readonly confidenceWeight: number = 0.0;

  /** @param source {@displayType `DeepPartial<GenericDocument>`} */
  public constructor(source: DeepPartial<GenericDocument> = {}) {
    super();
    if (source.type !== undefined) {
      this.type = new GenericDocumentType(source.type);
    } else {
      throw new Error('type must be present in constructor argument');
    }
    if (source.fields !== undefined) {
      this.fields = source.fields.map((it: any) => {
        return new Field(it);
      });
    } else {
      throw new Error('fields must be present in constructor argument');
    }
    if (source.children !== undefined) {
      this.children = source.children.map((it: any) => {
        return new GenericDocument(it);
      });
    } else {
      throw new Error('children must be present in constructor argument');
    }
    if (source.quad !== undefined) {
      this.quad = source.quad.map((it: any) => {
        return { x: it.x, y: it.y };
      });
    } else {
      throw new Error('quad must be present in constructor argument');
    }
    if (source.quadInRoot !== undefined) {
      this.quadInRoot = source.quadInRoot.map((it: any) => {
        return { x: it.x, y: it.y };
      });
    } else {
      throw new Error('quadInRoot must be present in constructor argument');
    }
    if (source.crop !== undefined) {
      this.crop = source.crop != null ? ImageRef.From(source.crop) : null;
    }
    if (source.confidence !== undefined) {
      this.confidence = source.confidence;
    }
    if (source.confidenceWeight !== undefined) {
      this.confidenceWeight = source.confidenceWeight;
    }
  }

  public async serialize(
    config: ToJsonConfiguration = new ToJsonConfiguration()
  ): Promise<DeepPartial<GenericDocument>> {
    return {
      type: this.type.serialize(config),
      fields: await Promise.all(
        this.fields.map(async (it: any) => {
          return await it.serialize(config);
        })
      ),
      children: await Promise.all(
        this.children.map(async (it: any) => {
          return await it.serialize(config);
        })
      ),
      quad: this.quad.map((it: any) => {
        return it;
      }),
      quadInRoot: this.quadInRoot.map((it: any) => {
        return it;
      }),
      crop: config.serializeImages
        ? this.crop != null
          ? await this.crop.serialize(config.imageSerializationMode)
          : null
        : undefined,
      confidence: this.confidence,
      confidenceWeight: this.confidenceWeight,
    };
  }

  private _released: Boolean = false;

  public release() {
    if (this._released) {
      return;
    }
    this.fields.forEach((it) => {
      it.release();
    });
    this.children.forEach((it) => {
      it.release();
    });
    {
      if (this.crop != null) {
        this.crop.release();
      }
    }
    this._released = true;
  }

  public async encodeImages(): Promise<void> {
    await Promise.all(
      this.fields.map(async (it) => {
        await it.encodeImages();
      })
    );
    await Promise.all(
      this.children.map(async (it) => {
        await it.encodeImages();
      })
    );
    if (this.crop != null) {
      await this.crop.encodeInPlace();
    }
  }
}