Index
-
DocumentProcessorService(interface) -
Barcode(message) -
BatchDocumentsInputConfig(message) -
BatchProcessMetadata(message) -
BatchProcessMetadata.IndividualProcessStatus(message) -
BatchProcessMetadata.State(enum) -
BatchProcessRequest(message) -
BatchProcessResponse(message) -
BoundingPoly(message) -
CommonOperationMetadata(message) -
CommonOperationMetadata.State(enum) -
CreateProcessorRequest(message) -
DeleteProcessorMetadata(message) -
DeleteProcessorRequest(message) -
DeleteProcessorVersionMetadata(message) -
DeleteProcessorVersionRequest(message) -
DeployProcessorVersionMetadata(message) -
DeployProcessorVersionRequest(message) -
DeployProcessorVersionResponse(message) -
DisableProcessorMetadata(message) -
DisableProcessorRequest(message) -
DisableProcessorResponse(message) -
Document(message) -
Document.ChunkedDocument(message) -
Document.ChunkedDocument.Chunk(message) -
Document.ChunkedDocument.Chunk.ChunkPageFooter(message) -
Document.ChunkedDocument.Chunk.ChunkPageHeader(message) -
Document.ChunkedDocument.Chunk.ChunkPageSpan(message) -
Document.DocumentLayout(message) -
Document.DocumentLayout.DocumentLayoutBlock(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutListBlock(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutListEntry(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutPageSpan(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutTableBlock(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutTableCell(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutTableRow(message) -
Document.DocumentLayout.DocumentLayoutBlock.LayoutTextBlock(message) -
Document.Entity(message) -
Document.Entity.NormalizedValue(message) -
Document.EntityRelation(message) -
Document.Page(message) -
Document.Page.Block(message) -
Document.Page.DetectedBarcode(message) -
Document.Page.DetectedLanguage(message) -
Document.Page.Dimension(message) -
Document.Page.FormField(message) -
Document.Page.Image(message) -
Document.Page.ImageQualityScores(message) -
Document.Page.ImageQualityScores.DetectedDefect(message) -
Document.Page.Layout(message) -
Document.Page.Layout.Orientation(enum) -
Document.Page.Line(message) -
Document.Page.Matrix(message) -
Document.Page.Paragraph(message) -
Document.Page.Symbol(message) -
Document.Page.Table(message) -
Document.Page.Table.TableCell(message) -
Document.Page.Table.TableRow(message) -
Document.Page.Token(message) -
Document.Page.Token.DetectedBreak(message) -
Document.Page.Token.DetectedBreak.Type(enum) -
Document.Page.Token.StyleInfo(message) -
Document.Page.VisualElement(message) -
Document.PageAnchor(message) -
Document.PageAnchor.PageRef(message) -
Document.PageAnchor.PageRef.LayoutType(enum) -
Document.Provenance(message) -
Document.Provenance.OperationType(enum) -
Document.Provenance.Parent(message) -
Document.Revision(message) -
Document.Revision.HumanReview(message) -
Document.ShardInfo(message) -
Document.Style(message) -
Document.Style.FontSize(message) -
Document.TextAnchor(message) -
Document.TextAnchor.TextSegment(message) -
Document.TextChange(message) -
DocumentOutputConfig(message) -
DocumentOutputConfig.GcsOutputConfig(message) -
DocumentOutputConfig.GcsOutputConfig.ShardingConfig(message) -
DocumentSchema(message) -
DocumentSchema.EntityType(message) -
DocumentSchema.EntityType.EnumValues(message) -
DocumentSchema.EntityType.Property(message) -
DocumentSchema.EntityType.Property.OccurrenceType(enum) -
DocumentSchema.Metadata(message) -
EnableProcessorMetadata(message) -
EnableProcessorRequest(message) -
EnableProcessorResponse(message) -
EvaluateProcessorVersionMetadata(message) -
EvaluateProcessorVersionRequest(message) -
EvaluateProcessorVersionResponse(message) -
Evaluation(message) -
Evaluation.ConfidenceLevelMetrics(message) -
Evaluation.Counters(message) -
Evaluation.Metrics(message) -
Evaluation.MultiConfidenceMetrics(message) -
Evaluation.MultiConfidenceMetrics.MetricsType(enum) -
EvaluationReference(message) -
FetchProcessorTypesRequest(message) -
FetchProcessorTypesResponse(message) -
GcsDocument(message) -
GcsDocuments(message) -
GcsPrefix(message) -
GetEvaluationRequest(message) -
GetProcessorRequest(message) -
GetProcessorTypeRequest(message) -
GetProcessorVersionRequest(message) -
HumanReviewStatus(message) -
HumanReviewStatus.State(enum) -
ListEvaluationsRequest(message) -
ListEvaluationsResponse(message) -
ListProcessorTypesRequest(message) -
ListProcessorTypesResponse(message) -
ListProcessorVersionsRequest(message) -
ListProcessorVersionsResponse(message) -
ListProcessorsRequest(message) -
ListProcessorsResponse(message) -
NormalizedVertex(message) -
OcrConfig(message) -
OcrConfig.Hints(message) -
OcrConfig.PremiumFeatures(message) -
ProcessOptions(message) -
ProcessOptions.IndividualPageSelector(message) -
ProcessOptions.LayoutConfig(message) -
ProcessOptions.LayoutConfig.ChunkingConfig(message) -
ProcessRequest(message) -
ProcessResponse(message) -
Processor(message) -
Processor.State(enum) -
ProcessorType(message) -
ProcessorType.LocationInfo(message) -
ProcessorVersion(message) -
ProcessorVersion.DeprecationInfo(message) -
ProcessorVersion.GenAiModelInfo(message) -
ProcessorVersion.GenAiModelInfo.CustomGenAiModelInfo(message) -
ProcessorVersion.GenAiModelInfo.CustomGenAiModelInfo.CustomModelType(enum) -
ProcessorVersion.GenAiModelInfo.FoundationGenAiModelInfo(message) -
ProcessorVersion.ModelType(enum) -
ProcessorVersion.State(enum) -
ProcessorVersionAlias(message) -
RawDocument(message) -
ReviewDocumentOperationMetadata(message) -
ReviewDocumentRequest(message) -
ReviewDocumentRequest.Priority(enum) -
ReviewDocumentResponse(message) -
ReviewDocumentResponse.State(enum) -
SetDefaultProcessorVersionMetadata(message) -
SetDefaultProcessorVersionRequest(message) -
SetDefaultProcessorVersionResponse(message) -
TrainProcessorVersionMetadata(message) -
TrainProcessorVersionMetadata.DatasetValidation(message) -
TrainProcessorVersionRequest(message) -
TrainProcessorVersionRequest.CustomDocumentExtractionOptions(message) -
TrainProcessorVersionRequest.CustomDocumentExtractionOptions.TrainingMethod(enum) -
TrainProcessorVersionRequest.FoundationModelTuningOptions(message) -
TrainProcessorVersionRequest.InputData(message) -
TrainProcessorVersionResponse(message) -
UndeployProcessorVersionMetadata(message) -
UndeployProcessorVersionRequest(message) -
UndeployProcessorVersionResponse(message) -
Vertex(message)
DocumentProcessorService
Service to call Document AI to process documents according to the processor's definition. Processors are built using state-of-the-art Google AI such as natural language, computer vision, and translation to extract structured information from unstructured or semi-structured documents.
rpc BatchProcessDocuments(
BatchProcessRequest
) returns ( Operation
)
LRO endpoint to batch process many documents. The output is written to Cloud Storage as JSON in the [Document] format.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires one of the following IAM permissions on the
nameresource, depending on the resource type:-
documentai.processors.processBatch -
documentai.processorVersions.processBatch
For more information, see the IAM documentation .
-
rpc CreateProcessor(
CreateProcessorRequest
) returns ( Processor
)
Creates a processor from the ProcessorType
provided. The processor will be at ENABLED
state by default after its creation. Note that this method requires the documentai.processors.create
permission on the project, which is highly privileged. A user or service account with this permission can create new processors that can interact with any gcs bucket in your project.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processors.create
For more information, see the IAM documentation .
-
rpc DeleteProcessor(
DeleteProcessorRequest
) returns ( Operation
)
Deletes the processor, unloads all deployed model artifacts if it was enabled and then deletes all artifacts associated with this processor.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processors.delete
For more information, see the IAM documentation .
-
rpc DeleteProcessorVersion(
DeleteProcessorVersionRequest
) returns ( Operation
)
Deletes the processor version, all artifacts under the processor version will be deleted.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processorVersions.delete
For more information, see the IAM documentation .
-
rpc DeployProcessorVersion(
DeployProcessorVersionRequest
) returns ( Operation
)
Deploys the processor version.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processorVersions.update
For more information, see the IAM documentation .
-
rpc DisableProcessor(
DisableProcessorRequest
) returns ( Operation
)
Disables a processor
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processors.update
For more information, see the IAM documentation .
-
rpc EnableProcessor(
EnableProcessorRequest
) returns ( Operation
)
Enables a processor
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processors.update
For more information, see the IAM documentation .
-
rpc EvaluateProcessorVersion(
EvaluateProcessorVersionRequest
) returns ( Operation
)
Evaluates a ProcessorVersion against annotated documents, producing an Evaluation.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
processorVersionresource:-
documentai.evaluations.create
For more information, see the IAM documentation .
-
rpc FetchProcessorTypes(
FetchProcessorTypesRequest
) returns ( FetchProcessorTypesResponse
)
Fetches processor types. Note that we don't use ListProcessorTypes
here, because it isn't paginated.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processorTypes.list
For more information, see the IAM documentation .
-
rpc GetEvaluation(
GetEvaluationRequest
) returns ( Evaluation
)
Retrieves a specific evaluation.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.evaluations.get
For more information, see the IAM documentation .
-
rpc GetProcessor(
GetProcessorRequest
) returns ( Processor
)
Gets a processor detail.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processors.get
For more information, see the IAM documentation .
-
rpc GetProcessorType(
GetProcessorTypeRequest
) returns ( ProcessorType
)
Gets a processor type detail.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processorTypes.get
For more information, see the IAM documentation .
-
rpc GetProcessorVersion(
GetProcessorVersionRequest
) returns ( ProcessorVersion
)
Gets a processor version detail.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processorVersions.get
For more information, see the IAM documentation .
-
rpc ListEvaluations(
ListEvaluationsRequest
) returns ( ListEvaluationsResponse
)
Retrieves a set of evaluations for a given processor version.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.evaluations.list
For more information, see the IAM documentation .
-
rpc ListProcessorTypes(
ListProcessorTypesRequest
) returns ( ListProcessorTypesResponse
)
Lists the processor types that exist.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processorTypes.list
For more information, see the IAM documentation .
-
rpc ListProcessorVersions(
ListProcessorVersionsRequest
) returns ( ListProcessorVersionsResponse
)
Lists all versions of a processor.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processorVersions.list
For more information, see the IAM documentation .
-
rpc ListProcessors(
ListProcessorsRequest
) returns ( ListProcessorsResponse
)
Lists all processors which belong to this project.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processors.list
For more information, see the IAM documentation .
-
rpc ProcessDocument(
ProcessRequest
) returns ( ProcessResponse
)
Processes a single document.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires one of the following IAM permissions on the
nameresource, depending on the resource type:-
documentai.processors.processOnline -
documentai.processorVersions.processOnline
For more information, see the IAM documentation .
-
rpc ReviewDocument(
ReviewDocumentRequest
) returns ( Operation
)
Send a document for Human Review. The input document should be processed by the specified processor.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
humanReviewConfigresource:-
documentai.humanReviewConfigs.review
For more information, see the IAM documentation .
-
rpc SetDefaultProcessorVersion(
SetDefaultProcessorVersionRequest
) returns ( Operation
)
Set the default (active) version of a Processor
that will be used in ProcessDocument
and BatchProcessDocuments
.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
processorresource:-
documentai.processors.update
For more information, see the IAM documentation .
-
rpc TrainProcessorVersion(
TrainProcessorVersionRequest
) returns ( Operation
)
Trains a new processor version. Operation metadata is returned as TrainProcessorVersionMetadata
.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
parentresource:-
documentai.processorVersions.create
For more information, see the IAM documentation .
-
rpc UndeployProcessorVersion(
UndeployProcessorVersionRequest
) returns ( Operation
)
Undeploys the processor version.
- Authorization scopes
-
Requires the following OAuth scope:
-
https://www.googleapis.com/auth/cloud-platform
For more information, see the Authentication Overview .
-
- IAM Permissions
-
Requires the following IAM permission on the
nameresource:-
documentai.processorVersions.update
For more information, see the IAM documentation .
-
Barcode
Encodes the detailed information of a barcode.
format
string
Format of a barcode. The supported formats are:
-
CODE_128: Code 128 type. -
CODE_39: Code 39 type. -
CODE_93: Code 93 type. -
CODABAR: Codabar type. -
DATA_MATRIX: 2D Data Matrix type. -
ITF: ITF type. -
EAN_13: EAN-13 type. -
EAN_8: EAN-8 type. -
QR_CODE: 2D QR code type. -
UPC_A: UPC-A type. -
UPC_E: UPC-E type. -
PDF417: PDF417 type. -
AZTEC: 2D Aztec code type. -
DATABAR: GS1 DataBar code type.
value_format
string
Value format describes the format of the value that a barcode encodes. The supported formats are:
-
CONTACT_INFO: Contact information. -
EMAIL: Email address. -
ISBN: ISBN identifier. -
PHONE: Phone number. -
PRODUCT: Product. -
SMS: SMS message. -
TEXT: Text string. -
URL: URL address. -
WIFI: Wifi information. -
GEO: Geo-localization. -
CALENDAR_EVENT: Calendar event. -
DRIVER_LICENSE: Driver's license.
raw_value
string
Raw value encoded in the barcode. For example: 'MEBKM:TITLE:Google;URL:https://www.google.com;;'
.
BatchDocumentsInputConfig
The common config to specify a set of documents used as input.
source
. Make sure that the caller of the API has storage.objects.get access to the buckets. The source can be only one of the following:gcs_prefix
The set of documents that match the specified Cloud Storage gcs_prefix
.
gcs_documents
The set of documents individually specified on Cloud Storage.
BatchProcessMetadata
The long-running operation metadata for BatchProcessDocuments
.
| Fields | |
|---|---|
state
|
The state of the current batch processing. |
state_message
|
A message providing more details about the current state of processing. For example, the error message if the operation is failed. |
create_time
|
The creation time of the operation. |
update_time
|
The last update time of the operation. |
individual_process_statuses[]
|
The list of response details of each document. |
IndividualProcessStatus
The status of a each individual document in the batch process.
| Fields | |
|---|---|
input_gcs_source
|
The source of the document, same as the |
status
|
The status processing the document. |
output_gcs_destination
|
The Cloud Storage output destination (in the request as |
human_review_status
|
The status of human review on the processed document. |
State
Possible states of the batch processing operation.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
The default value. This value is used if the state is omitted. |
WAITING
|
Request operation is waiting for scheduling. |
RUNNING
|
Request is being processed. |
SUCCEEDED
|
The batch processing completed successfully. |
CANCELLING
|
The batch processing was being cancelled. |
CANCELLED
|
The batch processing was cancelled. |
FAILED
|
The batch processing has failed. |
BatchProcessRequest
Request message for BatchProcessDocuments
.
name
string
Required. The resource name of Processor
or ProcessorVersion
. Format: projects/{project}/locations/{location}/processors/{processor}
, or projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}
Authorization requires one or more of the following IAM
permissions on the specified resource name
:
-
documentai.processors.processBatch -
documentai.processorVersions.processBatch
input_documents
The input documents for the BatchProcessDocuments
method.
document_output_config
The output configuration for the BatchProcessDocuments
method.
skip_human_review
bool
Whether human review should be skipped for this request. Default to false
.
labels
map<string, string>
Optional. The labels with user-defined metadata for the request.
Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.
BatchProcessResponse
This type has no fields.
Response message for BatchProcessDocuments
.
BoundingPoly
A bounding polygon for the detected image annotation.
| Fields | |
|---|---|
vertices[]
|
The bounding polygon vertices. |
normalized_vertices[]
|
The bounding polygon normalized vertices. |
CommonOperationMetadata
The common metadata for long running operations.
| Fields | |
|---|---|
state
|
The state of the operation. |
state_message
|
A message providing more details about the current state of processing. |
resource
|
A related resource to this operation. |
create_time
|
The creation time of the operation. |
update_time
|
The last update time of the operation. |
State
State of the longrunning operation.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
Unspecified state. |
RUNNING
|
Operation is still running. |
CANCELLING
|
Operation is being cancelled. |
SUCCEEDED
|
Operation succeeded. |
FAILED
|
Operation failed. |
CANCELLED
|
Operation is cancelled. |
CreateProcessorRequest
Request message for the CreateProcessor
method. Notice this request is sent to a regionalized backend service. If the ProcessorType
isn't available in that region, the creation fails.
parent
string
Required. The parent (project and location) under which to create the processor. Format: projects/{project}/locations/{location}
processor
Required. The processor to be created, requires Processor.type
and Processor.display_name
to be set. Also, the Processor.kms_key_name
field must be set if the processor is under CMEK.
Authorization requires the following IAM
permission on the specified resource processor
:
-
documentai.processors.create
DeleteProcessorMetadata
The long-running operation metadata for the DeleteProcessor
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
DeleteProcessorRequest
Request message for the DeleteProcessor
method.
name
string
Required. The processor resource name to be deleted.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processors.delete
DeleteProcessorVersionMetadata
The long-running operation metadata for the DeleteProcessorVersion
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
DeleteProcessorVersionRequest
Request message for the DeleteProcessorVersion
method.
name
string
Required. The processor version resource name to be deleted.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processorVersions.delete
DeployProcessorVersionMetadata
The long-running operation metadata for the DeployProcessorVersion
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
DeployProcessorVersionRequest
Request message for the DeployProcessorVersion
method.
name
string
Required. The processor version resource name to be deployed.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processorVersions.update
DeployProcessorVersionResponse
This type has no fields.
Response message for the DeployProcessorVersion
method.
DisableProcessorMetadata
The long-running operation metadata for the DisableProcessor
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
DisableProcessorRequest
Request message for the DisableProcessor
method.
name
string
Required. The processor resource name to be disabled.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processors.update
DisableProcessorResponse
This type has no fields.
Response message for the DisableProcessor
method. Intentionally empty proto for adding fields in future.
Document
Document represents the canonical document resource in Document AI. It is an interchange format that provides insights into documents and allows for collaboration between users and Document AI to iterate and optimize for quality.
mime_type
string
An IANA published media type (MIME type) .
text
string
Optional. UTF-8 encoded text in reading order from the document.
text_styles[]
(deprecated)
Styles for the Document.text
.
entities[]
A list of entities detected on Document.text
. For document shards, entities in this list may cross shard boundaries.
entity_relations[]
Placeholder. Relationship among Document.entities
.
text_changes[]
Placeholder. A list of text corrections made to Document.text
. This is usually used for annotating corrections to OCR mistakes. Text changes for a given revision may not overlap with each other.
shard_info
Information about the sharding if this document is sharded part of a larger document. If the document is not sharded, this message is not specified.
error
Any error that occurred while processing this document.
revisions[]
Placeholder. Revision history of this document.
document_layout
Parsed layout of the document.
chunked_document
Document chunked based on chunking config.
source
. Original source document from the user. source
can be only one of the following:uri
string
Optional. Currently supports Google Cloud Storage URI of the form gs://bucket_name/object_name
. Object versioning is not supported. For more information, refer to Google Cloud Storage Request URIs
.
content
bytes
Optional. Inline document content, represented as a stream of bytes. Note: As with all bytes
fields, protobuffers use a pure binary representation, whereas JSON representations use base64.
ChunkedDocument
Represents the chunks that the document is divided into.
| Fields | |
|---|---|
chunks[]
|
List of chunks. |
Chunk
Represents a chunk.
| Fields | |
|---|---|
chunk_id
|
ID of the chunk. |
source_block_ids[]
|
Unused. |
content
|
Text content of the chunk. |
page_span
|
Page span of the chunk. |
page_headers[]
|
Page headers associated with the chunk. |
page_footers[]
|
Page footers associated with the chunk. |
ChunkPageHeader
Represents the page header associated with the chunk.
| Fields | |
|---|---|
text
|
Header in text format. |
page_span
|
Page span of the header. |
ChunkPageSpan
Represents where the chunk starts and ends in the document.
| Fields | |
|---|---|
page_start
|
Page where chunk starts in the document. |
page_end
|
Page where chunk ends in the document. |
DocumentLayout
Represents the parsed layout of a document as a collection of blocks that the document is divided into.
| Fields | |
|---|---|
blocks[]
|
List of blocks in the document. |
DocumentLayoutBlock
Represents a block. A block could be one of the various types (text, table, list) supported.
block_id
string
ID of the block.
page_span
Page span of the block.
Union field block
.
block
can be only one of the following:
text_block
Block consisting of text content.
table_block
Block consisting of table content/structure.
list_block
Block consisting of list content/structure.
LayoutListBlock
Represents a list type block.
| Fields | |
|---|---|
list_entries[]
|
List entries that constitute a list block. |
type
|
Type of the list_entries (if exist). Available options are |
LayoutListEntry
Represents an entry in the list.
| Fields | |
|---|---|
blocks[]
|
A list entry is a list of blocks. Repeated blocks support further hierarchies and nested blocks. |
LayoutPageSpan
Represents where the block starts and ends in the document.
| Fields | |
|---|---|
page_start
|
Page where block starts in the document. |
page_end
|
Page where block ends in the document. |
LayoutTableBlock
Represents a table type block.
| Fields | |
|---|---|
header_rows[]
|
Header rows at the top of the table. |
body_rows[]
|
Body rows containing main table content. |
caption
|
Table caption/title. |
LayoutTableCell
Represents a cell in a table row.
| Fields | |
|---|---|
blocks[]
|
A table cell is a list of blocks. Repeated blocks support further hierarchies and nested blocks. |
row_span
|
How many rows this cell spans. |
col_span
|
How many columns this cell spans. |
LayoutTableRow
Represents a row in a table.
| Fields | |
|---|---|
cells[]
|
A table row is a list of table cells. |
LayoutTextBlock
Represents a text type block.
| Fields | |
|---|---|
text
|
Text content stored in the block. |
type
|
Type of the text in the block. Available options are: |
blocks[]
|
A text block could further have child blocks. Repeated blocks support further hierarchies and nested blocks. |
Entity
An entity that could be a phrase in the text or a property that belongs to the document. It is a known entity type, such as a person, an organization, or location.
| Fields | |
|---|---|
text_anchor
|
Optional. Provenance of the entity. Text anchor indexing into the |
type
|
Required. Entity type from a schema e.g. |
mention_text
|
Optional. Text value of the entity e.g. |
mention_id
|
Optional. Deprecated. Use |
confidence
|
Optional. Confidence of detected Schema entity. Range |
page_anchor
|
Optional. Represents the provenance of this entity wrt. the location on the page where it was found. |
id
|
Optional. Canonical id. This will be a unique value in the entity list for this document. |
normalized_value
|
Optional. Normalized entity value. Absent if the extracted value could not be converted or the type (e.g. address) is not supported for certain parsers. This field is also only populated for certain supported document types. |
properties[]
|
Optional. Entities can be nested to form a hierarchical data structure representing the content in the document. |
provenance
|
Optional. The history of this annotation. |
redacted
|
Optional. Whether the entity will be redacted for de-identification purposes. |
NormalizedValue
Parsed and normalized entity value.
text
string
Optional. An optional field to store a normalized string. For some entity types, one of respective structured_value
fields may also be populated. Also not all the types of structured_value
will be normalized. For example, some processors may not generate float
or integer
normalized text by default.
Below are sample formats mapped to structured values.
- Money/Currency type (
money_value) is in the ISO 4217 text format. - Date type (
date_value) is in the ISO 8601 text format. - Datetime type (
datetime_value) is in the ISO 8601 text format.
structured_value
. An optional structured entity value. Must match entity type defined in schema if known. If this field is present, the text
field could also be populated. structured_value
can be only one of the following:money_value
Money value. See also: https://github.com/googleapis/googleapis/blob/master/google/type/money.proto
date_value
Date value. Includes year, month, day. See also: https://github.com/googleapis/googleapis/blob/master/google/type/date.proto
datetime_value
DateTime value. Includes date, time, and timezone. See also: https://github.com/googleapis/googleapis/blob/master/google/type/datetime.proto
address_value
Postal address. See also: https://github.com/googleapis/googleapis/blob/master/google/type/postal_address.proto
boolean_value
bool
Boolean value. Can be used for entities with binary values, or for checkboxes.
integer_value
int32
Integer value.
float_value
float
Float value.
EntityRelation
Relationship between Entities
.
| Fields | |
|---|---|
subject_id
|
Subject entity id. |
object_id
|
Object entity id. |
relation
|
Relationship description. |
Page
A page in a Document
.
| Fields | |
|---|---|
page_number
|
1-based index for current |
image
|
Rendered image for this page. This image is preprocessed to remove any skew, rotation, and distortions such that the annotation bounding boxes can be upright and axis-aligned. |
transforms[]
|
Transformation matrices that were applied to the original document image to produce |
dimension
|
Physical dimension of the page. |
layout
|
|
detected_languages[]
|
A list of detected languages together with confidence. |
blocks[]
|
A list of visually detected text blocks on the page. A block has a set of lines (collected into paragraphs) that have a common line-spacing and orientation. |
paragraphs[]
|
A list of visually detected text paragraphs on the page. A collection of lines that a human would perceive as a paragraph. |
lines[]
|
A list of visually detected text lines on the page. A collection of tokens that a human would perceive as a line. |
tokens[]
|
A list of visually detected tokens on the page. |
visual_elements[]
|
A list of detected non-text visual elements e.g. checkbox, signature etc. on the page. |
tables[]
|
A list of visually detected tables on the page. |
form_fields[]
|
A list of visually detected form fields on the page. |
symbols[]
|
A list of visually detected symbols on the page. |
detected_barcodes[]
|
A list of detected barcodes. |
image_quality_scores
|
Image quality scores. |
provenance
|
The history of this page. |
Block
A block has a set of lines (collected into paragraphs) that have a common line-spacing and orientation.
| Fields | |
|---|---|
layout
|
|
detected_languages[]
|
A list of detected languages together with confidence. |
provenance
|
The history of this annotation. |
DetectedBarcode
A detected barcode.
| Fields | |
|---|---|
layout
|
|
barcode
|
Detailed barcode information of the |
DetectedLanguage
Detected language for a structural component.
| Fields | |
|---|---|
language_code
|
The BCP-47 language code
, such as |
confidence
|
Confidence of detected language. Range |
Dimension
Dimension for the page.
| Fields | |
|---|---|
width
|
Page width. |
height
|
Page height. |
unit
|
Dimension unit. |
FormField
A form field detected on the page.
field_name
name_detected_languages[]
A list of detected languages for name together with confidence.
value_detected_languages[]
A list of detected languages for value together with confidence.
value_type
string
If the value is non-textual, this field represents the type. Current valid values are:
- blank (this indicates the
field_valueis normal text) -
unfilled_checkbox -
filled_checkbox
corrected_key_text
string
Created for Labeling UI to export key text. If corrections were made to the text identified by the field_name.text_anchor
, this field will contain the correction.
corrected_value_text
string
Created for Labeling UI to export value text. If corrections were made to the text identified by the field_value.text_anchor
, this field will contain the correction.
provenance
The history of this annotation.
Image
Rendered image contents for this page.
| Fields | |
|---|---|
content
|
Raw byte content of the image. |
mime_type
|
Encoding media type (MIME type) for the image. |
width
|
Width of the image in pixels. |
height
|
Height of the image in pixels. |
ImageQualityScores
Image quality scores for the page image.
| Fields | |
|---|---|
quality_score
|
The overall quality score. Range |
detected_defects[]
|
A list of detected defects. |
DetectedDefect
Image Quality Defects
type
string
Name of the defect type. Supported values are:
-
quality/defect_blurry -
quality/defect_noisy -
quality/defect_dark -
quality/defect_faint -
quality/defect_text_too_small -
quality/defect_document_cutoff -
quality/defect_text_cutoff -
quality/defect_glare
confidence
float
Confidence of detected defect. Range [0, 1]
where 1
indicates strong confidence that the defect exists.
Layout
Visual element describing a layout unit on a page.
| Fields | |
|---|---|
text_anchor
|
Text anchor indexing into the |
confidence
|
Confidence of the current |
bounding_poly
|
The bounding polygon for the |
orientation
|
Detected orientation for the |
Orientation
Detected human reading orientation.
| Enums | |
|---|---|
ORIENTATION_UNSPECIFIED
|
Unspecified orientation. |
PAGE_UP
|
Orientation is aligned with page up. |
PAGE_RIGHT
|
Orientation is aligned with page right. Turn the head 90 degrees clockwise from upright to read. |
PAGE_DOWN
|
Orientation is aligned with page down. Turn the head 180 degrees from upright to read. |
PAGE_LEFT
|
Orientation is aligned with page left. Turn the head 90 degrees counterclockwise from upright to read. |
Line
A collection of tokens that a human would perceive as a line. Does not cross column boundaries, can be horizontal, vertical, etc.
| Fields | |
|---|---|
layout
|
|
detected_languages[]
|
A list of detected languages together with confidence. |
provenance
|
The history of this annotation. |
Matrix
Representation for transformation matrix, intended to be compatible and used with OpenCV format for image manipulation.
| Fields | |
|---|---|
rows
|
Number of rows in the matrix. |
cols
|
Number of columns in the matrix. |
type
|
This encodes information about what data type the matrix uses. For example, 0 (CV_8U) is an unsigned 8-bit image. For the full list of OpenCV primitive data types, please refer to https://docs.opencv.org/4.3.0/d1/d1b/group__core__hal__interface.html |
data
|
The matrix data. |
Paragraph
A collection of lines that a human would perceive as a paragraph.
| Fields | |
|---|---|
layout
|
|
detected_languages[]
|
A list of detected languages together with confidence. |
provenance
|
The history of this annotation. |
Symbol
A detected symbol.
| Fields | |
|---|---|
layout
|
|
detected_languages[]
|
A list of detected languages together with confidence. |
Table
A table representation similar to HTML table structure.
| Fields | |
|---|---|
layout
|
|
header_rows[]
|
Header rows of the table. |
body_rows[]
|
Body rows of the table. |
detected_languages[]
|
A list of detected languages together with confidence. |
provenance
|
The history of this table. |
TableCell
A cell representation inside the table.
| Fields | |
|---|---|
layout
|
|
row_span
|
How many rows this cell spans. |
col_span
|
How many columns this cell spans. |
detected_languages[]
|
A list of detected languages together with confidence. |
TableRow
A row of table cells.
| Fields | |
|---|---|
cells[]
|
Cells that make up this row. |
Token
A detected token.
| Fields | |
|---|---|
layout
|
|
detected_break
|
Detected break at the end of a |
detected_languages[]
|
A list of detected languages together with confidence. |
provenance
|
The history of this annotation. |
style_info
|
Text style attributes. |
DetectedBreak
Detected break at the end of a Token
.
| Fields | |
|---|---|
type
|
Detected break type. |
Type
Enum to denote the type of break found.
| Enums | |
|---|---|
TYPE_UNSPECIFIED
|
Unspecified break type. |
SPACE
|
A single whitespace. |
WIDE_SPACE
|
A wider whitespace. |
HYPHEN
|
A hyphen that indicates that a token has been split across lines. |
StyleInfo
Font and other text style attributes.
| Fields | |
|---|---|
font_size
|
Font size in points ( |
pixel_font_size
|
Font size in pixels, equal to unrounded |
letter_spacing
|
Letter spacing in points. |
font_type
|
Name or style of the font. |
bold
|
Whether the text is bold (equivalent to |
italic
|
Whether the text is italic. |
underlined
|
Whether the text is underlined. |
strikeout
|
Whether the text is strikethrough. This feature is not supported yet. |
subscript
|
Whether the text is a subscript. This feature is not supported yet. |
superscript
|
Whether the text is a superscript. This feature is not supported yet. |
smallcaps
|
Whether the text is in small caps. This feature is not supported yet. |
font_weight
|
TrueType weight on a scale |
handwritten
|
Whether the text is handwritten. |
text_color
|
Color of the text. |
background_color
|
Color of the background. |
VisualElement
Detected non-text visual elements e.g. checkbox, signature etc. on the page.
| Fields | |
|---|---|
layout
|
|
type
|
Type of the |
detected_languages[]
|
A list of detected languages together with confidence. |
PageAnchor
Referencing the visual context of the entity in the Document.pages
. Page anchors can be cross-page, consist of multiple bounding polygons and optionally reference specific layout element types.
| Fields | |
|---|---|
page_refs[]
|
One or more references to visual page elements |
PageRef
Represents a weak reference to a page element within a document.
| Fields | |
|---|---|
page
|
Required. Index into the |
layout_type
|
Optional. The type of the layout element that is being referenced if any. |
layout_id
|
Optional. Deprecated. Use |
bounding_poly
|
Optional. Identifies the bounding polygon of a layout element on the page. If |
confidence
|
Optional. Confidence of detected page element, if applicable. Range |
LayoutType
The type of layout that is being referenced.
| Enums | |
|---|---|
LAYOUT_TYPE_UNSPECIFIED
|
Layout Unspecified. |
BLOCK
|
References a Page.blocks
element. |
PARAGRAPH
|
References a Page.paragraphs
element. |
LINE
|
References a Page.lines
element. |
TOKEN
|
References a Page.tokens
element. |
VISUAL_ELEMENT
|
References a Page.visual_elements
element. |
TABLE
|
Refrrences a Page.tables
element. |
FORM_FIELD
|
References a Page.form_fields
element. |
Provenance
Structure to identify provenance relationships between annotations in different revisions.
| Fields | |
|---|---|
revision
|
The index of the revision that produced this element. |
id
|
The Id of this operation. Needs to be unique within the scope of the revision. |
parents[]
|
References to the original elements that are replaced. |
type
|
The type of provenance operation. |
OperationType
If a processor or agent does an explicit operation on existing elements.
| Enums | |
|---|---|
OPERATION_TYPE_UNSPECIFIED
|
Operation type unspecified. If no operation is specified a provenance entry is simply used to match against a parent
. |
ADD
|
Add an element. |
REMOVE
|
Remove an element identified by parent
. |
UPDATE
|
Updates any fields within the given provenance scope of the message. It overwrites the fields rather than replacing them. Use this when you want to update a field value of an entity without also updating all the child properties. |
REPLACE
|
Currently unused. Replace an element identified by parent
. |
EVAL_REQUESTED
|
Deprecated. Request human review for the element identified by |
EVAL_APPROVED
|
Deprecated. Element is reviewed and approved at human review, confidence will be set to 1.0. |
EVAL_SKIPPED
|
Deprecated. Element is skipped in the validation process. |
Parent
The parent element the current element is based on. Used for referencing/aligning, removal and replacement operations.
| Fields | |
|---|---|
revision
|
The index of the index into current revision's parent_ids list. |
index
|
The index of the parent item in the corresponding item list (eg. list of entities, properties within entities, etc.) in the parent revision. |
id
|
The id of the parent provenance. |
Revision
Contains past or forward revisions of this document.
id
string
Id of the revision, internally generated by doc proto storage. Unique within the context of the document.
parent[]
(deprecated)
int32
The revisions that this revision is based on. This can include one or more parent (when documents are merged.) This field represents the index into the revisions
field.
parent_ids[]
string
The revisions that this revision is based on. Must include all the ids that have anything to do with this revision - eg. there are provenance.parent.revision
fields that index into this field.
create_time
The time that the revision was created, internally generated by doc proto storage at the time of create.
human_review
Human Review information of this revision.
source
. Who/what made the change source
can be only one of the following:agent
string
If the change was made by a person specify the name or id of that person.
processor
string
If the annotation was made by processor identify the processor by its resource name.
HumanReview
Human Review information of the document.
| Fields | |
|---|---|
state
|
Human review state. e.g. |
state_message
|
A message providing more details about the current state of processing. For example, the rejection reason when the state is |
ShardInfo
For a large document, sharding may be performed to produce several document shards. Each document shard contains this field to detail which shard it is.
| Fields | |
|---|---|
shard_index
|
The 0-based index of this shard. |
shard_count
|
Total number of shards. |
text_offset
|
The index of the first character in |
Style
Annotation for common text style attributes. This adheres to CSS conventions as much as possible.
| Fields | |
|---|---|
text_anchor
|
Text anchor indexing into the |
color
|
Text color. |
background_color
|
Text background color. |
font_weight
|
Font weight
. Possible values are |
text_style
|
Text style
. Possible values are |
text_decoration
|
Text decoration . Follows CSS standard. |
font_size
|
Font size. |
font_family
|
Font family such as |
FontSize
Font size with unit.
| Fields | |
|---|---|
size
|
Font size for the text. |
unit
|
Unit for the font size. Follows CSS naming (such as |
TextAnchor
Text reference indexing into the Document.text
.
| Fields | |
|---|---|
text_segments[]
|
The text segments from the |
content
|
Contains the content of the text span so that users do not have to look it up in the text_segments. It is always populated for formFields. |
TextSegment
A text segment in the Document.text
. The indices may be out of bounds which indicate that the text extends into another document shard for large sharded documents. See ShardInfo.text_offset
| Fields | |
|---|---|
start_index
|
|
end_index
|
|
TextChange
This message is used for text changes aka. OCR corrections.
| Fields | |
|---|---|
text_anchor
|
Provenance of the correction. Text anchor indexing into the |
changed_text
|
The text that replaces the text identified in the |
provenance[]
|
The history of this annotation. |
DocumentOutputConfig
Config that controls the output of documents. All documents will be written as a JSON file.
destination
. The destination of the results. destination
can be only one of the following:gcs_output_config
Output config to write the results to Cloud Storage.
GcsOutputConfig
The configuration used when outputting documents.
| Fields | |
|---|---|
gcs_uri
|
The Cloud Storage uri (a directory) of the output. |
field_mask
|
Specifies which fields to include in the output documents. Only supports top level document and pages field so it must be in the form of |
sharding_config
|
Specifies the sharding config for the output document. |
ShardingConfig
The sharding config for the output document.
| Fields | |
|---|---|
pages_per_shard
|
The number of pages per shard. |
pages_overlap
|
The number of overlapping pages between consecutive shards. |
DocumentSchema
The schema defines the output of the processed document by a processor.
| Fields | |
|---|---|
display_name
|
Display name to show to users. |
description
|
Description of the schema. |
entity_types[]
|
Entity types of the schema. |
metadata
|
Metadata of the schema. |
EntityType
EntityType is the wrapper of a label of the corresponding model with detailed attributes and limitations for entity-based processors. Multiple types can also compose a dependency tree to represent nested types.
display_name
string
User defined name for the type.
name
string
Name of the type. It must be unique within the schema file and cannot be a "Common Type". The following naming conventions are used:
- Use
snake_casing. - Name matching is case-sensitive.
- Maximum 64 characters.
- Must start with a letter.
- Allowed characters: ASCII letters
[a-z0-9_-]. (For backward compatibility internal infrastructure and tooling can handle any ascii character.) - The
/is sometimes used to denote a property of a type. For exampleline_item/amount. This convention is deprecated, but will still be honored for backward compatibility.
base_types[]
string
The entity type that this type is derived from. For now, one and only one should be set.
properties[]
Description the nested structure, or composition of an entity.
Union field value_source
.
value_source
can be only one of the following:
enum_values
If specified, lists all the possible values for this entity. This should not be more than a handful of values. If the number of values is >10 or could change frequently use the EntityType.value_ontology
field and specify a list of all possible values in a value ontology file.
EnumValues
Defines the a list of enum values.
| Fields | |
|---|---|
values[]
|
The individual values that this enum values type can include. |
Property
Defines properties that can be part of the entity type.
| Fields | |
|---|---|
name
|
The name of the property. Follows the same guidelines as the EntityType name. |
display_name
|
User defined name for the property. |
value_type
|
A reference to the value type of the property. This type is subject to the same conventions as the |
occurrence_type
|
Occurrence type limits the number of instances an entity type appears in the document. |
OccurrenceType
Types of occurrences of the entity type in the document. This represents the number of instances, not mentions, of an entity. For example, a bank statement might only have one account_number
, but this account number can be mentioned in several places on the document. In this case, the account_number
is considered a REQUIRED_ONCE
entity type. If, on the other hand, we expect a bank statement to contain the status of multiple different accounts for the customers, the occurrence type is set to REQUIRED_MULTIPLE
.
| Enums | |
|---|---|
OCCURRENCE_TYPE_UNSPECIFIED
|
Unspecified occurrence type. |
OPTIONAL_ONCE
|
There will be zero or one instance of this entity type. The same entity instance may be mentioned multiple times. |
OPTIONAL_MULTIPLE
|
The entity type will appear zero or multiple times. |
REQUIRED_ONCE
|
The entity type will only appear exactly once. The same entity instance may be mentioned multiple times. |
REQUIRED_MULTIPLE
|
The entity type will appear once or more times. |
Metadata
Metadata for global schema behavior.
| Fields | |
|---|---|
document_splitter
|
If true, a |
document_allow_multiple_labels
|
If true, on a given page, there can be multiple |
prefixed_naming_on_properties
|
If set, all the nested entities must be prefixed with the parents. |
skip_naming_validation
|
If set, we will skip the naming format validation in the schema. So the string values in |
EnableProcessorMetadata
The long-running operation metadata for the EnableProcessor
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
EnableProcessorRequest
Request message for the EnableProcessor
method.
name
string
Required. The processor resource name to be enabled.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processors.update
EnableProcessorResponse
This type has no fields.
Response message for the EnableProcessor
method. Intentionally empty proto for adding fields in future.
EvaluateProcessorVersionMetadata
Metadata of the EvaluateProcessorVersion
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
EvaluateProcessorVersionRequest
Evaluates the given ProcessorVersion
against the supplied documents.
processor_version
string
Required. The resource name of the ProcessorVersion
to evaluate. projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}
Authorization requires the following IAM
permission on the specified resource processorVersion
:
-
documentai.evaluations.create
evaluation_documents
Optional. The documents used in the evaluation. If unspecified, use the processor's dataset as evaluation input.
EvaluateProcessorVersionResponse
Response of the EvaluateProcessorVersion
method.
| Fields | |
|---|---|
evaluation
|
The resource name of the created evaluation. |
Evaluation
An evaluation of a ProcessorVersion's performance.
| Fields | |
|---|---|
name
|
The resource name of the evaluation. Format: |
create_time
|
The time that the evaluation was created. |
document_counters
|
Counters for the documents used in the evaluation. |
all_entities_metrics
|
Metrics for all the entities in aggregate. |
entity_metrics
|
Metrics across confidence levels, for different entities. |
kms_key_name
|
The KMS key name used for encryption. |
kms_key_version_name
|
The KMS key version with which data is encrypted. |
ConfidenceLevelMetrics
Evaluations metrics, at a specific confidence level.
| Fields | |
|---|---|
confidence_level
|
The confidence level. |
metrics
|
The metrics at the specific confidence level. |
Counters
Evaluation counters for the documents that were used.
| Fields | |
|---|---|
input_documents_count
|
How many documents were sent for evaluation. |
invalid_documents_count
|
How many documents were not included in the evaluation as they didn't pass validation. |
failed_documents_count
|
How many documents were not included in the evaluation as Document AI failed to process them. |
evaluated_documents_count
|
How many documents were used in the evaluation. |
Metrics
Evaluation metrics, either in aggregate or about a specific entity.
| Fields | |
|---|---|
precision
|
The calculated precision. |
recall
|
The calculated recall. |
f1_score
|
The calculated f1 score. |
predicted_occurrences_count
|
The amount of occurrences in predicted documents. |
ground_truth_occurrences_count
|
The amount of occurrences in ground truth documents. |
predicted_document_count
|
The amount of documents with a predicted occurrence. |
ground_truth_document_count
|
The amount of documents with a ground truth occurrence. |
true_positives_count
|
The amount of true positives. |
false_positives_count
|
The amount of false positives. |
false_negatives_count
|
The amount of false negatives. |
total_documents_count
|
The amount of documents that had an occurrence of this label. |
MultiConfidenceMetrics
Metrics across multiple confidence levels.
| Fields | |
|---|---|
confidence_level_metrics[]
|
Metrics across confidence levels with fuzzy matching enabled. |
confidence_level_metrics_exact[]
|
Metrics across confidence levels with only exact matching. |
auprc
|
The calculated area under the precision recall curve (AUPRC), computed by integrating over all confidence thresholds. |
estimated_calibration_error
|
The Estimated Calibration Error (ECE) of the confidence of the predicted entities. |
auprc_exact
|
The AUPRC for metrics with fuzzy matching disabled, i.e., exact matching only. |
estimated_calibration_error_exact
|
The ECE for the predicted entities with fuzzy matching disabled, i.e., exact matching only. |
metrics_type
|
The metrics type for the label. |
MetricsType
A type that determines how metrics should be interpreted.
| Enums | |
|---|---|
METRICS_TYPE_UNSPECIFIED
|
The metrics type is unspecified. By default, metrics without a particular specification are for leaf entity types (i.e., top-level entity types without child types, or child types which are not parent types themselves). |
AGGREGATE
|
Indicates whether metrics for this particular label type represent an aggregate of metrics for other types instead of being based on actual TP/FP/FN values for the label type. Metrics for parent (i.e., non-leaf) entity types are an aggregate of metrics for their children. |
EvaluationReference
Gives a short summary of an evaluation, and links to the evaluation itself.
| Fields | |
|---|---|
operation
|
The resource name of the Long Running Operation for the evaluation. |
evaluation
|
The resource name of the evaluation. |
aggregate_metrics
|
An aggregate of the statistics for the evaluation with fuzzy matching on. |
aggregate_metrics_exact
|
An aggregate of the statistics for the evaluation with fuzzy matching off. |
FetchProcessorTypesRequest
Request message for the FetchProcessorTypes
method. Some processor types may require the project be added to an allowlist.
parent
string
Required. The location of processor types to list. Format: projects/{project}/locations/{location}
.
Authorization requires the following IAM
permission on the specified resource parent
:
-
documentai.processorTypes.list
FetchProcessorTypesResponse
Response message for the FetchProcessorTypes
method.
| Fields | |
|---|---|
processor_types[]
|
The list of processor types. |
GcsDocument
Specifies a document stored on Cloud Storage.
| Fields | |
|---|---|
gcs_uri
|
The Cloud Storage object uri. |
mime_type
|
An IANA MIME type (RFC6838) of the content. |
GcsDocuments
Specifies a set of documents on Cloud Storage.
| Fields | |
|---|---|
documents[]
|
The list of documents. |
GcsPrefix
Specifies all documents on Cloud Storage with a common prefix.
| Fields | |
|---|---|
gcs_uri_prefix
|
The URI prefix. |
GetEvaluationRequest
Retrieves a specific Evaluation.
name
string
Required. The resource name of the Evaluation
to get. projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}/evaluations/{evaluation}
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.evaluations.get
GetProcessorRequest
Request message for the GetProcessor
method.
name
string
Required. The processor resource name.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processors.get
GetProcessorTypeRequest
Request message for the GetProcessorType
method.
name
string
Required. The processor type resource name.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processorTypes.get
GetProcessorVersionRequest
Request message for the GetProcessorVersion
method.
name
string
Required. The processor resource name.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processorVersions.get
HumanReviewStatus
The status of human review on a processed document.
| Fields | |
|---|---|
state
|
The state of human review on the processing request. |
state_message
|
A message providing more details about the human review state. |
human_review_operation
|
The name of the operation triggered by the processed document. This field is populated only when the |
State
The final state of human review on a processed document.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
Human review state is unspecified. Most likely due to an internal error. |
SKIPPED
|
Human review is skipped for the document. This can happen because human review isn't enabled on the processor or the processing request has been set to skip this document. |
VALIDATION_PASSED
|
Human review validation is triggered and passed, so no review is needed. |
IN_PROGRESS
|
Human review validation is triggered and the document is under review. |
ERROR
|
Some error happened during triggering human review, see the state_message
for details. |
ListEvaluationsRequest
Retrieves a list of evaluations for a given ProcessorVersion
.
parent
string
Required. The resource name of the ProcessorVersion
to list evaluations for. projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}
Authorization requires the following IAM
permission on the specified resource parent
:
-
documentai.evaluations.list
page_size
int32
The standard list page size. If unspecified, at most 5
evaluations are returned. The maximum value is 100
. Values above 100
are coerced to 100
.
page_token
string
A page token, received from a previous ListEvaluations
call. Provide this to retrieve the subsequent page.
ListEvaluationsResponse
The response from ListEvaluations
.
| Fields | |
|---|---|
evaluations[]
|
The evaluations requested. |
next_page_token
|
A token, which can be sent as |
ListProcessorTypesRequest
Request message for the ListProcessorTypes
method. Some processor types may require the project be added to an allowlist.
parent
string
Required. The location of processor types to list. Format: projects/{project}/locations/{location}
.
Authorization requires the following IAM
permission on the specified resource parent
:
-
documentai.processorTypes.list
page_size
int32
The maximum number of processor types to return. If unspecified, at most 100
processor types will be returned. The maximum value is 500
. Values above 500
will be coerced to 500
.
page_token
string
Used to retrieve the next page of results, empty if at the end of the list.
ListProcessorTypesResponse
Response message for the ListProcessorTypes
method.
| Fields | |
|---|---|
processor_types[]
|
The processor types. |
next_page_token
|
Points to the next page, otherwise empty. |
ListProcessorVersionsRequest
Request message for list all processor versions belongs to a processor.
parent
string
Required. The parent (project, location and processor) to list all versions. Format: projects/{project}/locations/{location}/processors/{processor}
Authorization requires the following IAM
permission on the specified resource parent
:
-
documentai.processorVersions.list
page_size
int32
The maximum number of processor versions to return. If unspecified, at most 10
processor versions will be returned. The maximum value is 20
. Values above 20
will be coerced to 20
.
page_token
string
We will return the processor versions sorted by creation time. The page token will point to the next processor version.
ListProcessorVersionsResponse
Response message for the ListProcessorVersions
method.
| Fields | |
|---|---|
processor_versions[]
|
The list of processors. |
next_page_token
|
Points to the next processor, otherwise empty. |
ListProcessorsRequest
Request message for list all processors belongs to a project.
parent
string
Required. The parent (project and location) which owns this collection of Processors. Format: projects/{project}/locations/{location}
Authorization requires the following IAM
permission on the specified resource parent
:
-
documentai.processors.list
page_size
int32
The maximum number of processors to return. If unspecified, at most 50
processors will be returned. The maximum value is 100
. Values above 100
will be coerced to 100
.
page_token
string
We will return the processors sorted by creation time. The page token will point to the next processor.
ListProcessorsResponse
Response message for the ListProcessors
method.
| Fields | |
|---|---|
processors[]
|
The list of processors. |
next_page_token
|
Points to the next processor, otherwise empty. |
NormalizedVertex
A vertex represents a 2D point in the image. NOTE: the normalized vertex coordinates are relative to the original image and range from 0 to 1.
| Fields | |
|---|---|
x
|
X coordinate. |
y
|
Y coordinate (starts from the top of the image). |
OcrConfig
Config for Document OCR.
hints
Hints for the OCR model.
enable_native_pdf_parsing
bool
Enables special handling for PDFs with existing text information. Results in better text extraction quality in such PDF inputs.
enable_image_quality_scores
bool
Enables intelligent document quality scores after OCR. Can help with diagnosing why OCR responses are of poor quality for a given input. Adds additional latency comparable to regular OCR to the process call.
enable_symbol
bool
Includes symbol level OCR information if set to true.
compute_style_info
(deprecated)
bool
Turn on font identification model and return font style information. Deprecated, use PremiumFeatures.compute_style_info
instead.
disable_character_boxes_detection
bool
Turn off character box detector in OCR engine. Character box detection is enabled by default in OCR 2.0 (and later) processors.
Hints
Hints for OCR Engine
| Fields | |
|---|---|
language_hints[]
|
List of BCP-47 language codes to use for OCR. In most cases, not specifying it yields the best results since it enables automatic language detection. For languages based on the Latin alphabet, setting hints is not needed. In rare cases, when the language of the text in the image is known, setting a hint will help get better results (although it will be a significant hindrance if the hint is wrong). |
PremiumFeatures
Configurations for premium OCR features.
| Fields | |
|---|---|
enable_selection_mark_detection
|
Turn on selection mark detector in OCR engine. Only available in OCR 2.0 (and later) processors. |
compute_style_info
|
Turn on font identification model and return font style information. |
enable_math_ocr
|
Turn on the model that can extract LaTeX math formulas. |
ProcessOptions
Options for Process API
ocr_config
Only applicable to OCR_PROCESSOR
and FORM_PARSER_PROCESSOR
. Returns error if set on other processor types.
layout_config
Optional. Only applicable to LAYOUT_PARSER_PROCESSOR
. Returns error if set on other processor types.
schema_override
Optional. Override the schema of the ProcessorVersion
. Will return an Invalid Argument error if this field is set when the underlying ProcessorVersion
doesn't support schema override.
page_range
. A subset of pages to process. If not specified, all pages are processed. If a page range is set, only the given pages are extracted and processed from the document. In the output document, Document.Page.page_number
refers to the page number in the original document. This configuration only applies to online processing with ProcessDocument
. page_range
can be only one of the following:individual_page_selector
Which pages to process (1-indexed).
from_start
int32
Only process certain pages from the start. Process all if the document has fewer pages.
from_end
int32
Only process certain pages from the end, same as above.
IndividualPageSelector
A list of individual page numbers.
| Fields | |
|---|---|
pages[]
|
Optional. Indices of the pages (starting from 1). |
LayoutConfig
Serving config for layout parser processor.
| Fields | |
|---|---|
chunking_config
|
Optional. Config for chunking in layout parser processor. |
ChunkingConfig
Serving config for chunking.
| Fields | |
|---|---|
chunk_size
|
Optional. The chunk sizes to use when splitting documents, in order of level. |
include_ancestor_headings
|
Optional. Whether or not to include ancestor headings when splitting. |
ProcessRequest
Request message for the ProcessDocument
method.
name
string
Required. The resource name of the Processor
or ProcessorVersion
to use for processing. If a Processor
is specified, the server will use its default version
. Format: projects/{project}/locations/{location}/processors/{processor}
, or projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}
Authorization requires one or more of the following IAM
permissions on the specified resource name
:
-
documentai.processors.processOnline -
documentai.processorVersions.processOnline
skip_human_review
bool
Whether human review should be skipped for this request. Default to false
.
field_mask
Specifies which fields to include in the ProcessResponse.document
output. Only supports top-level document and pages field, so it must be in the form of {document_field_name}
or pages.{page_field_name}
.
labels
map<string, string>
Optional. The labels with user-defined metadata for the request.
Label keys and values can be no longer than 63 characters (Unicode codepoints) and can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.
imageless_mode
bool
Optional. Option to remove images from the document.
source
. The document payload. source
can be only one of the following:inline_document
An inline document proto.
raw_document
A raw document content (bytes).
gcs_document
A raw document on Google Cloud Storage.
ProcessResponse
Response message for the ProcessDocument
method.
| Fields | |
|---|---|
document
|
The document payload, will populate fields based on the processor's behavior. |
human_review_status
|
The status of human review on the processed document. |
Processor
The first-class citizen for Document AI. Each processor defines how to extract structural information from a document.
| Fields | |
|---|---|
name
|
Output only. Immutable. The resource name of the processor. Format: |
type
|
The processor type, such as: |
display_name
|
The display name of the processor. |
state
|
Output only. The state of the processor. |
default_processor_version
|
The default processor version. |
processor_version_aliases[]
|
Output only. The processor version aliases. |
process_endpoint
|
Output only. Immutable. The http endpoint that can be called to invoke processing. |
create_time
|
The time the processor was created. |
kms_key_name
|
The KMS key used for encryption and decryption in CMEK scenarios. |
satisfies_pzs
|
Output only. Reserved for future use. |
satisfies_pzi
|
Output only. Reserved for future use. |
State
The possible states of the processor.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
The processor is in an unspecified state. |
ENABLED
|
The processor is enabled, i.e., has an enabled version which can currently serve processing requests and all the feature dependencies have been successfully initialized. |
DISABLED
|
The processor is disabled. |
ENABLING
|
The processor is being enabled, will become ENABLED
if successful. |
DISABLING
|
The processor is being disabled, will become DISABLED
if successful. |
CREATING
|
The processor is being created, will become either ENABLED
(for successful creation) or FAILED
(for failed ones). Once a processor is in this state, it can then be used for document processing, but the feature dependencies of the processor might not be fully created yet. |
FAILED
|
The processor failed during creation or initialization of feature dependencies. The user should delete the processor and recreate one as all the functionalities of the processor are disabled. |
DELETING
|
The processor is being deleted, will be removed if successful. |
ProcessorType
A processor type is responsible for performing a certain document understanding task on a certain type of document.
| Fields | |
|---|---|
name
|
The resource name of the processor type. Format: |
type
|
The processor type, such as: |
category
|
The processor category, used by UI to group processor types. |
available_locations[]
|
The locations in which this processor is available. |
allow_creation
|
Whether the processor type allows creation. If true, users can create a processor of this processor type. Otherwise, users need to request access. |
launch_stage
|
Launch stage of the processor type |
sample_document_uris[]
|
A set of Cloud Storage URIs of sample documents for this processor. |
LocationInfo
The location information about where the processor is available.
| Fields | |
|---|---|
location_id
|
The location ID. For supported locations, refer to regional and multi-regional support . |
ProcessorVersion
A processor version is an implementation of a processor. Each processor can have multiple versions, pretrained by Google internally or uptrained by the customer. A processor can only have one default version at a time. Its document-processing behavior is defined by that version.
| Fields | |
|---|---|
name
|
Identifier. The resource name of the processor version. Format: |
display_name
|
The display name of the processor version. |
document_schema
|
The schema of the processor version. Describes the output. |
state
|
Output only. The state of the processor version. |
create_time
|
The time the processor version was created. |
latest_evaluation
|
The most recently invoked evaluation for the processor version. |
kms_key_name
|
The KMS key name used for encryption. |
kms_key_version_name
|
The KMS key version with which data is encrypted. |
google_managed
|
Output only. Denotes that this |
deprecation_info
|
If set, information about the eventual deprecation of this version. |
model_type
|
Output only. The model type of this processor version. |
satisfies_pzs
|
Output only. Reserved for future use. |
satisfies_pzi
|
Output only. Reserved for future use. |
gen_ai_model_info
|
Output only. Information about Generative AI model-based processor versions. |
DeprecationInfo
Information about the upcoming deprecation of this processor version.
| Fields | |
|---|---|
deprecation_time
|
The time at which this processor version will be deprecated. |
replacement_processor_version
|
If set, the processor version that will be used as a replacement. |
GenAiModelInfo
Information about Generative AI model-based processor versions.
model_info
. The processor version is either a pretrained Google-managed foundation model or a custom Generative AI model created by the user. model_info
can be only one of the following:foundation_gen_ai_model_info
Information for a pretrained Google-managed foundation model.
custom_gen_ai_model_info
Information for a custom Generative AI model created by the user.
CustomGenAiModelInfo
Information for a custom Generative AI model created by the user. These are created with Create New Version
in either the Call foundation
model
or Fine tuning
tabs.
| Fields | |
|---|---|
custom_model_type
|
The type of custom model created by the user. |
base_processor_version_id
|
The base processor version ID for the custom model. |
CustomModelType
The type of custom model created by the user.
| Enums | |
|---|---|
CUSTOM_MODEL_TYPE_UNSPECIFIED
|
The model type is unspecified. |
VERSIONED_FOUNDATION
|
The model is a versioned foundation model. |
FINE_TUNED
|
The model is a finetuned foundation model. |
FoundationGenAiModelInfo
Information for a pretrained Google-managed foundation model.
| Fields | |
|---|---|
finetuning_allowed
|
Whether finetuning is allowed for this base processor version. |
min_train_labeled_documents
|
The minimum number of labeled documents in the training dataset required for finetuning. |
ModelType
The possible model types of the processor version.
| Enums | |
|---|---|
MODEL_TYPE_UNSPECIFIED
|
The processor version has unspecified model type. |
MODEL_TYPE_GENERATIVE
|
The processor version has generative model type. |
MODEL_TYPE_CUSTOM
|
The processor version has custom model type. |
State
The possible states of the processor version.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
The processor version is in an unspecified state. |
DEPLOYED
|
The processor version is deployed and can be used for processing. |
DEPLOYING
|
The processor version is being deployed. |
UNDEPLOYED
|
The processor version is not deployed and cannot be used for processing. |
UNDEPLOYING
|
The processor version is being undeployed. |
CREATING
|
The processor version is being created. |
DELETING
|
The processor version is being deleted. |
FAILED
|
The processor version failed and is in an indeterminate state. |
IMPORTING
|
The processor version is being imported. |
ProcessorVersionAlias
Contains the alias and the aliased resource name of processor version.
| Fields | |
|---|---|
alias
|
The alias in the form of |
processor_version
|
The resource name of aliased processor version. |
RawDocument
Payload message of raw document content (bytes).
| Fields | |
|---|---|
content
|
Inline document content. |
mime_type
|
An IANA MIME type (RFC6838) indicating the nature and format of the |
display_name
|
The display name of the document, it supports all Unicode characters except the following: |
ReviewDocumentOperationMetadata
The long-running operation metadata for the ReviewDocument
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
question_id
|
The Crowd Compute question ID. |
ReviewDocumentRequest
Request message for the ReviewDocument
method.
human_review_config
string
Required. The resource name of the HumanReviewConfig
that the document will be reviewed with.
Authorization requires the following IAM
permission on the specified resource humanReviewConfig
:
-
documentai.humanReviewConfigs.review
enable_schema_validation
bool
Whether the validation should be performed on the ad-hoc review request.
priority
The priority of the human review task.
document_schema
The document schema of the human review task.
source
. The document payload. source
can be only one of the following:inline_document
An inline document proto.
Priority
The priority level of the human review task.
| Enums | |
|---|---|
DEFAULT
|
The default priority level. |
URGENT
|
The urgent priority level. The labeling manager should allocate labeler resource to the urgent task queue to respect this priority level. |
ReviewDocumentResponse
Response message for the ReviewDocument
method.
| Fields | |
|---|---|
gcs_destination
|
The Cloud Storage uri for the human reviewed document if the review is succeeded. |
state
|
The state of the review operation. |
rejection_reason
|
The reason why the review is rejected by reviewer. |
State
Possible states of the review operation.
| Enums | |
|---|---|
STATE_UNSPECIFIED
|
The default value. This value is used if the state is omitted. |
REJECTED
|
The review operation is rejected by the reviewer. |
SUCCEEDED
|
The review operation is succeeded. |
SetDefaultProcessorVersionMetadata
The long-running operation metadata for the SetDefaultProcessorVersion
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
SetDefaultProcessorVersionRequest
Request message for the SetDefaultProcessorVersion
method.
processor
default_processor_version
string
Required. The resource name of child ProcessorVersion
to use as default. Format: projects/{project}/locations/{location}/processors/{processor}/processorVersions/{version}
SetDefaultProcessorVersionResponse
This type has no fields.
Response message for the SetDefaultProcessorVersion
method.
TrainProcessorVersionMetadata
The metadata that represents a processor version being created.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
training_dataset_validation
|
The training dataset validation information. |
test_dataset_validation
|
The test dataset validation information. |
DatasetValidation
The dataset validation information. This includes any and all errors with documents and the dataset.
| Fields | |
|---|---|
document_error_count
|
The total number of document errors. |
dataset_error_count
|
The total number of dataset errors. |
document_errors[]
|
Error information pertaining to specific documents. A maximum of 10 document errors will be returned. Any document with errors will not be used throughout training. |
dataset_errors[]
|
Error information for the dataset as a whole. A maximum of 10 dataset errors will be returned. A single dataset error is terminal for training. |
TrainProcessorVersionRequest
Request message for the TrainProcessorVersion
method.
parent
string
Required. The parent (project, location and processor) to create the new version for. Format: projects/{project}/locations/{location}/processors/{processor}
.
processor_version
Required. The processor version to be created.
Authorization requires the following IAM
permission on the specified resource processorVersion
:
-
documentai.processorVersions.create
document_schema
Optional. The schema the processor version will be trained with.
input_data
Optional. The input data used to train the ProcessorVersion
.
base_processor_version
string
Optional. The processor version to use as a base for training. This processor version must be a child of parent
. Format: projects/{project}/locations/{location}/processors/{processor}/processorVersions/{processorVersion}
.
Union field processor_flags
.
processor_flags
can be only one of the following:
CustomDocumentExtractionOptions
Options to control the training of the Custom Document Extraction (CDE) Processor.
| Fields | |
|---|---|
training_method
|
Training method to use for CDE training. |
TrainingMethod
Training Method for CDE. TRAINING_METHOD_UNSPECIFIED
will fall back to MODEL_BASED
.
| Enums | |
|---|---|
TRAINING_METHOD_UNSPECIFIED
|
|
MODEL_BASED
|
|
TEMPLATE_BASED
|
|
FoundationModelTuningOptions
Options to control foundation model tuning of the processor.
| Fields | |
|---|---|
train_steps
|
Optional. The number of steps to run for model tuning. Valid values are between 1 and 400. If not provided, recommended steps will be used. |
learning_rate_multiplier
|
Optional. The multiplier to apply to the recommended learning rate. Valid values are between 0.1 and 10. If not provided, recommended learning rate will be used. |
InputData
The input data used to train a new ProcessorVersion
.
| Fields | |
|---|---|
training_documents
|
The documents used for training the new version. |
test_documents
|
The documents used for testing the trained version. |
TrainProcessorVersionResponse
The response for TrainProcessorVersion
.
| Fields | |
|---|---|
processor_version
|
The resource name of the processor version produced by training. |
UndeployProcessorVersionMetadata
The long-running operation metadata for the UndeployProcessorVersion
method.
| Fields | |
|---|---|
common_metadata
|
The basic metadata of the long-running operation. |
UndeployProcessorVersionRequest
Request message for the UndeployProcessorVersion
method.
name
string
Required. The processor version resource name to be undeployed.
Authorization requires the following IAM
permission on the specified resource name
:
-
documentai.processorVersions.update
UndeployProcessorVersionResponse
This type has no fields.
Response message for the UndeployProcessorVersion
method.
Vertex
A vertex represents a 2D point in the image. NOTE: the vertex coordinates are in the same scale as the original image.
| Fields | |
|---|---|
x
|
X coordinate. |
y
|
Y coordinate (starts from the top of the image). |
