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.gitor from a local checkout:
dsh plugin --profile web add file:/path/to/dsh-tool-read-tiffThen 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_KEYUsage
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](./LICENSE) (the plugin itself); sharp and schemastery carry their own licenses.