dsh-tool-read-tiff

dsh-tool-read-tiff — TIFF Reading Tool Plugin

English | 中文

Model-facing read_tiff tool: gives text-only models (DeepSeek V4 etc.) the ability to read
TIFF/TIF images — the format plain vision pipelines and browsers cannot touch. Each call loads one
TIFF (a local file path or an http(s) URL), decodes a page into a viewable PNG, and reports the
full header metadata (dimensions, page count, compression, photometric interpretation, per-channel
bit depths, byte order). When a vision endpoint is configured it also asks an OpenAI-compatible
vision model to describe the decoded page; only text and metadata enter the conversation, the
TIFF and PNG bytes never enter the session log.

Decoding is done by sharp (libvips + libtiff), so the common
real-world TIFF variants work out of the box: classic and BigTIFF, multi-page, LZW / Deflate /
PackBits / CCITT Group 3 & 4 / JPEG compression, bilevel (1-bit), 8/16-bit, and float samples.

Capabilities

Capability	Description
Two inputs	Local absolute path, or an http(s) URL (redirects refused)
Decode + convert	Decodes the requested page to a PNG written beside the source (or under outputDir / the OS temp dir for URLs); the path comes back in convertedPath so the conversation can preview it
Full header metadata	width / height / pages / page / channels / depth / space / density, plus the TIFF-specific facts: compression (lzw, deflate, ccitt-group4, jpeg, none, …), photometric (rgb, black-is-zero, cmyk, …), bitsPerSample, samplesPerPixel, byteOrder, variant (classic / bigtiff)
Multi-page	page is a zero-based page index; pages reports the total count, so the model can iterate a multi-page fax / scan
Optional vision	When baseURL + model are configured, the decoded PNG is sent to an OpenAI-compatible endpoint (Chat Completions) and the answer comes back as text; the prompt argument carries your precise instruction
Compose without config	With no endpoint configured the tool still decodes + converts + reports metadata and returns a note directing the model to call describe_image on convertedPath
Live config card	Settings → 插件配置 → "TIFF reading" card edits baseURL / model / API key / bounds; effective immediately, no restart

Security model

• Vision requests and URL downloads both refuse HTTP redirects (redirect: 'error'); bearer
  credentials and image bytes never reach a source other than the configured deployment.
• The vision request body carries the base64 PNG but no key; request headers and resolved
  credentials are not logged.
• Only http(s) URLs and local paths are accepted; every other URL scheme is rejected.
• Response bodies are capped before parsing; error excerpts are bounded (200 chars).
• The TIFF and PNG bytes are never returned into the conversation — only text and metadata.

Installation

The plugin is a standard cordis bundle. Install it into the web profile from GitHub (the prepare
script builds on install; allow sharp under allowBuilds in pnpm-workspace.yaml if prompted):

dsh plugin --profile web add git+https://github.com/fulander0301/dsh-tool-read-tiff.git

or from a local checkout:

dsh plugin --profile web add file:/path/to/dsh-tool-read-tiff

Then restart dsh web. The bundle declares sharp and schemastery as runtime
dependencies; @deepseek-ai/* peer services resolve from the dsh installation, exactly like the
other dsh-web-ui tool plugins.

Configuration

The tool works with zero configuration (decode + convert + metadata only). To enable the
one-shot visual description, configure the vision endpoint (Settings → 插件配置 → "TIFF reading",
or a composition entry):

Key	Default	Meaning
baseURL	—	OpenAI-compatible endpoint root (e.g. https://dashscope.aliyuncs.com/compatible-mode/v1); trailing slashes stripped
model	—	Vision model id
apiKey	—	Inline key; prefer apiKeyEnv
apiKeyEnv	VISION_API_KEY	Environment-variable name for the API key (shared convention with the describe-image tool)
defaultPrompt	see source	Instruction used when a call omits its prompt
maxBytes	67108864	TIFF byte bound (local files and downloads alike)
maxOutputTokens	1024	Output-token cap sent to the vision model
timeoutMs	60000	Per-call vision request timeout
outputDir	— (temp dir for URLs)	Where converted PNGs go when the source is not a local file

Configured mount example (cordis.patch.yml / composition file):

- id: read-tiff
  name: 'dsh-tool-read-tiff'
  config:
    baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen-vl-max
    apiKey: !!js process.env.VISION_API_KEY

Usage

Point the tool at a TIFF and (optionally) give the vision model a precise instruction:

• "transcribe all text in this scanned fax"
• "extract the table as CSV"
• "describe the map features and projection"
• "what does the label in the corner say"

For multi-page files, call again with page: 1, page: 2, and so on; pages tells you how many
there are. When no vision endpoint is configured, the tool still returns everything it decoded plus
a convertedPath you can hand to the already-installed describe_image tool.

Known limitations

• One page per call: multi-page TIFFs are read one page at a time via page.
• Very large or exotic TIFFs (complex float multi-band scientific rasters) may need pre-processing;
  the tool reports sharp's error with a clear message when a page cannot be decoded.
• The optional vision step speaks only the Chat Completions protocol.

License

MIT (the plugin itself); sharp and schemastery carry their own licenses.