pdfsmart

type Options struct {
	// ImagePagesNeedEngine sends a page with an embedded image to the engine even when its text layer
	// is fine, which is what Convert does. A reader that lets the caller look at the page itself
	// leaves it false: the text is read natively and the image is only reported.
	ImagePagesNeedEngine bool

	// MaxEnginePages bounds how many pages one call sends to the document reader (zero means no
	// bound). Pages past it are returned with Deferred set. Each engine call is slow, so a caller
	// that wants an answer in bounded time sets it and reads the rest in a later call.
	MaxEnginePages int

	// Password opens a PDF that is protected by a user password. A PDF whose user password is empty needs none.
	Password string

	// ModelBudget bounds the time one call spends asking the layout models about tables. A model looks at one page
	// in seconds on a CPU, and many pages of a long document look as if they might hold a table, so without a bound
	// a book takes minutes for the sake of the few pages that have one. Zero means DefaultModelBudget; a negative
	// value means no bound. Once it is spent the remaining pages are read without the models.
	ModelBudget time.Duration
}

type PageRenderer interface {
	// RenderPage renders 1-indexed page pageNum of the PDF in data,
	// returning PNG-encoded image bytes.
	RenderPage(ctx context.Context, data []byte, pageNum int) ([]byte, error)
}

type PageResult struct {
	Page             int
	Text             string
	Source           PageSource
	HasEmbeddedImage bool
	// Pictures are the pictures of the page the text does not say anything about, numbered from 1 on the page. A page read
	// natively has one marker in Text for each of them (see ImageMarker); a page read by an engine has none, since the
	// engine read the pictures.
	Pictures []Picture
	// Deferred is set on a page that needed the engine but was left unread because Options.MaxEnginePages
	// had been used up. It is not a failure: reading the page again later will read it.
	Deferred bool
}

type PageSource string

type Picture struct {
	// Number counts the pictures of the page from 1, in the order the file lists them (which is not always the order on the
	// page). With the page number it names the picture for good, whatever pages were read.
	Number int
	// Title is the caption found in the text of the page ("Figure 2. ..."), or empty when there is none to attach.
	Title string
}

type Result struct {
	Markdown string
	Pages    []PageResult
	// ModelPagesSkipped counts the pages whose tables the layout models were not asked about because the time
	// budget (Options.ModelBudget) was spent. Their text is read as usual, and so are the tables the rulings show.
	ModelPagesSkipped int
}

type TableFinder interface {
	FindTables(ctx context.Context, pdfData []byte, pageIndex int) ([]pdftext.TableStructure, error)
}

type VisionFallback struct {
	Renderer    PageRenderer
	Transcriber VisionTranscriber
}

type VisionTranscriber interface {
	IsAvailable(ctx context.Context) bool
	// TranscribePage returns the page's transcribed text/markdown given its
	// PNG-encoded image bytes.
	TranscribePage(ctx context.Context, pngImage []byte) (string, error)
}