GoodMemOCR
Document OCR — text extraction from PDFs / images.
Namespace: Goodmem.Client.Api · Class: OcrApi
Reach this surface as client.Ocr on a GoodmemClient. Every network method is asynchronous — it returns a Task<T> (or an IAsyncEnumerable<T> for pagination and streaming) and accepts a CancellationToken; the Async suffix marks the standard .NET Task-based async pattern.
Methods
| Method | Summary |
|---|---|
DocumentAsync | Run OCR on a document or image. |
DocumentFromFileAsync | Run OCR over a local file. Any Content on is replaced by the file's base64-encoded bytes; other fields (page range, markdown, …) are preserved. The caller's request is never mutated. |
DocumentAsync
Run OCR on a document or image. Pass base64-encoded document bytes as content. The server auto-detects format; set format explicitly only if needed.
Declaration
public Task<OcrDocumentResponse> DocumentAsync(OcrDocumentRequest request, CancellationToken ct = default)
HTTP — POST /v1/ocr:document
Parameters
| Type | Name | Description |
|---|---|---|
OcrDocumentRequest | request | The request payload; the linked model lists every field and its JSON wire name. |
CancellationToken | ct | Cancellation / deadline signal for the call. (optional) |
Returns
Task<OcrDocumentResponse> — an awaitable that resolves to OcrDocumentResponse.
Exceptions
| Type | Condition |
|---|---|
ArgumentNullException | request is null. |
NetworkException | The request could not reach the server (DNS, connection, or TLS failure). |
ApiException | The server returned a non-success (non-2xx) status. A status-specific subtype is thrown where it applies — e.g. NotFoundException (404), PermissionDeniedException (403), ConflictException (409). |
Example
var imageB64 = Convert.ToBase64String(Encoding.UTF8.GetBytes("not-a-real-image"));
var result = await client.Ocr.DocumentAsync(
new OcrDocumentRequest
{
Content = imageB64,
Format = OcrInputFormat.Png,
IncludeMarkdown = true,
}
);
Console.WriteLine(result.PageCount);DocumentFromFileAsync
Run OCR on a document or image. Pass base64-encoded document bytes as content. The server auto-detects format; set format explicitly only if needed.
File overload: reads filePath from disk (memory-create uploads it as a multipart file part; OCR base64-encodes it into the JSON body) — the content type is inferred from the extension.
Declaration
public Task<OcrDocumentResponse> DocumentFromFileAsync(string filePath, OcrDocumentRequest? request = null, CancellationToken ct = default)
HTTP — POST /v1/ocr:document
Parameters
| Type | Name | Description |
|---|---|---|
string | filePath | Path to a local file; it is read into memory and (for OCR) base64-encoded, with the content type inferred from the extension. |
OcrDocumentRequest | request | The request payload; the linked model lists every field and its JSON wire name. (optional) |
CancellationToken | ct | Cancellation / deadline signal for the call. (optional) |
Returns
Task<OcrDocumentResponse> — an awaitable that resolves to OcrDocumentResponse.
Exceptions
| Type | Condition |
|---|---|
ArgumentException | filePath is null or empty. |
GoodmemException | The local file could not be read (I/O error, missing file, or access denied). |
NetworkException | The request could not reach the server (DNS, connection, or TLS failure). |
ApiException | The server returned a non-success (non-2xx) status. A status-specific subtype is thrown where it applies — e.g. NotFoundException (404), PermissionDeniedException (403), ConflictException (409). |
Example
var result = await client.Ocr.DocumentFromFileAsync("/path/to/document.pdf", new OcrDocumentRequest());Data Models
Types in the Goodmem.Client.Models namespace. Each row lists the C# property, its type, the JSON wire name, and a description.
OcrDocumentRequest
Request body for OCR document processing.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
Content | string | content | Base64-encoded document bytes |
Format | OcrInputFormat | format | Input format hint (AUTO, PDF, TIFF, PNG, JPEG, BMP) (optional) |
IncludeRawJson | bool | includeRawJson | Include raw OCR JSON payload in the response (optional) |
IncludeMarkdown | bool | includeMarkdown | Include markdown rendering in the response (optional) |
StartPage | int | startPage | 0-based inclusive start page (optional) |
EndPage | int | endPage | 0-based inclusive end page (optional) |
OcrInputFormat
OCR input format hint.
String enum: "AUTO" · "PDF" · "TIFF" · "PNG" · "JPEG" · "BMP"
OcrDocumentResponse
Response containing page-ordered OCR results.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
DetectedFormat | OcrInputFormat | detectedFormat | Detected input format |
PageCount | int | pageCount | Number of pages processed after applying the range |
Pages | IReadOnlyList<OcrPageResult> | pages | Ordered per-page OCR results |
Timings | DocumentTimings | timings | Aggregate timing statistics |
OcrPageResult
Per-page OCR result containing output or error status.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
PageIndex | int | pageIndex | 0-based page index |
Page | OcrPage | page | OCR output for the page (optional) |
Status | RpcStatus | status | Error status for the page (optional) |
DocumentTimings
Aggregate timing statistics for an OCR request.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
WallTimeMs | long | wallTimeMs | End-to-end request time (ms) |
SumQueueWaitMs | long | sumQueueWaitMs | Sum of per-page queue wait times (ms) |
SumRenderMs | long | sumRenderMs | Sum of per-page render times (ms) |
SumOcrMs | long | sumOcrMs | Sum of per-page OCR times (ms) |
SumPageTotalMs | long | sumPageTotalMs | Sum of per-page total times (ms) |
OcrPage
OCR output for a single page.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
RawJson | string | rawJson | Raw OCR JSON payload when requested (optional) |
Markdown | string | markdown | Markdown rendering when requested (optional) |
Layout | OcrLayout | layout | Parsed layout output |
Timings | PageTimings | timings | Timing breakdown for the page |
Image | ImageInfo | image | Rendered image metadata |
RpcStatus
Status payload for per-page OCR errors.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
Code | int | code | gRPC status code as defined by google.rpc.Code |
Message | string | message | Human-readable error message (optional) |
OcrLayout
Parsed OCR layout output for a page.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
Cells | IReadOnlyList<OcrCell> | cells | Layout cells in reading order |
PageTimings
Per-page timing breakdown for OCR processing.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
QueueWaitMs | long | queueWaitMs | Time spent waiting in the render queue (ms) |
RenderMs | long | renderMs | Time spent rendering the page image (ms) |
OcrMs | long | ocrMs | Time spent running OCR (ms) |
TotalMs | long | totalMs | Total page processing time (ms) |
ImageInfo
Rendered image metadata for an OCR page.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
WidthPx | int | widthPx | Rendered image width in pixels |
HeightPx | int | heightPx | Rendered image height in pixels |
Dpi | int | dpi | Rendering DPI |
OcrCell
Single OCR layout element.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
Bbox | BoundingBox | bbox | Bounding box in page coordinates (optional) |
CategoryLabel | string | categoryLabel | Raw category label emitted by OCR |
Category | OcrCategory | category | Normalized OCR category |
Text | string | text | OCR text content |
BoundingBox
Bounding box coordinates in page space.
| Property | Type | JSON (wire) | Description |
|---|---|---|---|
X1 | double | x1 | Left coordinate |
Y1 | double | y1 | Top coordinate |
X2 | double | x2 | Right coordinate |
Y2 | double | y2 | Bottom coordinate |
OcrCategory
Normalized OCR layout category.
String enum: "UNSPECIFIED" · "CAPTION" · "FOOTNOTE" · "FORMULA" · "LIST_ITEM" · "PAGE_FOOTER" · "PAGE_HEADER" · "PICTURE" · "SECTION_HEADER" · "TABLE" · "TEXT" · "TITLE" · "OTHER" · "UNKNOWN"