[← README](../../README.md) · [Docs index](../README.md) · [Search](README.md)

# Scans, pictures and older Office files

Some files have words only an installed program can get: screenshots, scans, scanned PDFs, and
older Office files such as `.doc` and `.ppt`. When the program is there, Coxswain uses it by itself,
and a search finds those words too.

![Programs that read more in Settings: ✗ tesseract, not installed, with the line Install it: sudo pacman -S tesseract tesseract-data-eng and a Copy button; ✓ pdftoppm and ✓ LibreOffice](../screenshots/search-scans-tools.png)

## Contents

- [How to use it](#how-to-use-it)
- [Installing what is missing](#installing-what-is-missing)
- [What you see](#what-you-see)
- [Settings and config.toml](#settings-and-configtoml)
- [In the terminal app](#in-the-terminal-app)
- [Questions](#questions)

## How to use it

1. Install the program (table below).
2. Wait for the [search helper](helper.md)'s next scan, within ten minutes, or click **Read
   now** under *Settings → Finding files*: the helper looks for the programs at every scan.
3. The files of that kind are then read again, by themselves. Search them as any
   [text](text.md): **Shift+F7**, your words.

| Program | Reads | Notes |
|---|---|---|
| `tesseract` (OCR) | The words in screenshots, scans and pictures: `.png` `.jpg` `.jpeg` `.jpe` `.tif` `.tiff` `.webp` `.bmp` | Photos from a camera (a JPEG whose EXIF names the camera maker) are skipped: they seldom have words and there are thousands. It reads English and your system's language, when tesseract has them |
| `pdftoppm` (with tesseract) | Scanned PDFs, which hold pictures of pages instead of text | Up to 30 pages, at 200 dpi, in grey. Only a PDF with no text of its own |
| LibreOffice (`soffice`) | Older Office files and others no reader here knows: `.doc` `.dot` `.wps` (Works) `.wpd` (WordPerfect) `.wri` (Windows Write) `.wk1` `.wks` `.123` (Lotus 1-2-3) `.lwp` (Lotus WordPro) `.pub` `.ppt` `.pps` `.pot` `.vsd` `.vsdx` `.odg` `.sxw` `.sxc` `.sxi` `.sxd` (StarOffice) `.abw` (AbiWord) `.cwk` (ClarisWorks) `.pages` `.key` `.numbers` | Made into a PDF in a work folder in Coxswain's cache (`scratch/`), read, and removed. It has its own profile, so a LibreOffice you have open is not disturbed |
| Ghostscript (`gs`, on Windows `gswin64c`) | The text of PostScript files: `.ps` `.eps` | Run with `-dSAFER`, as PostScript is a programming language. Without Ghostscript a PostScript file is read as the plain text it is, program and all |

Without LibreOffice, [Apache Tika](tika.md) reads the Word, PowerPoint, Publisher, Visio,
WordPerfect and StarOffice ones when you turn it on, in a container.

How to install each one on your system: [Installing what is missing](#installing-what-is-missing).
Coxswain shows the same line where a program is missing.

For other languages than English and yours, install tesseract's language data too
(`tesseract-ocr-deu`, `tesseract-data-deu` …).

## Installing what is missing

Where a program is missing, Coxswain shows the command that installs it on this system, with a
**Copy** button. It never runs the command: you paste it into a shell. The package manager is
the system's own: `pkg` on FreeBSD, `pkgin` on NetBSD, `pkg_add` on OpenBSD, `pkg` on illumos,
on Linux the first of `pacman`, `apt`, `dnf` and `zypper` that is installed, Homebrew on a Mac
and `winget` on Windows.

| System | tesseract | pdftoppm | LibreOffice | Ghostscript |
|---|---|---|---|---|
| FreeBSD | `pkg install tesseract` | `pkg install poppler-utils` | `pkg install libreoffice` | `pkg install ghostscript10` |
| NetBSD (`pkgin`) | `pkgin install tesseract` | `pkgin install poppler-utils` | `pkgin install libreoffice` | `pkgin install ghostscript-agpl` |
| OpenBSD (`pkg_add`) | `pkg_add tesseract` | `pkg_add poppler-utils` | `pkg_add libreoffice` | `pkg_add ghostscript` |
| illumos (`pkg`) | none in OmniOS | none | none | none |
| Arch (`pacman`) | `sudo pacman -S tesseract tesseract-data-eng` | `sudo pacman -S poppler` | `sudo pacman -S libreoffice-fresh` | `sudo pacman -S ghostscript` |
| Debian, Ubuntu (`apt`) | `sudo apt install tesseract-ocr` | `sudo apt install poppler-utils` | `sudo apt install libreoffice` | `sudo apt install ghostscript` |
| Fedora (`dnf`) | `sudo dnf install tesseract` | `sudo dnf install poppler-utils` | `sudo dnf install libreoffice` | `sudo dnf install ghostscript` |
| openSUSE (`zypper`) | `sudo zypper install tesseract-ocr` | `sudo zypper install poppler-tools` | `sudo zypper install libreoffice` | `sudo zypper install ghostscript` |
| macOS (Homebrew) | `brew install tesseract` | `brew install poppler` | `brew install --cask libreoffice` (`/Applications/LibreOffice.app` is looked in) | `brew install ghostscript` |
| Windows (`winget`) | `winget install --id UB-Mannheim.TesseractOCR -e` (`C:\Program Files\Tesseract-OCR` is looked in) | none: *pdftoppm has no package here: get it from its website and put it on PATH.* (poppler for Windows) | `winget install --id TheDocumentFoundation.LibreOffice -e` (`C:\Program Files\LibreOffice\program` is looked in) | `winget install --id ArtifexSoftware.GhostScript -e` |

Where it shows:

| Where | Desktop app | Terminal app |
|---|---|---|
| *Settings → Finding files → Details → What is read → Programs that read more* | Each missing program: *not installed*, then *Install it:* with the line and **Copy** (*Copied* beside it after the click) | *Settings → Finding files → Programs that read more*: the row shows `✓`, or the line. **Space** on it copies the line to the terminal's clipboard (OSC 52); the bottom says *Copied: …* |
| The tesseract [notice](../panels/notices.md) | *Install tesseract to search the words in scans, screenshots and pictures: sudo apt install tesseract-ocr*, under *Settings → Overview → What's new*, with **Copy** | The same text, once in the status line |

Without a package manager Coxswain knows (a Linux with none of the four), there is no line: the
notice says *Install tesseract to search the words in scans, screenshots and pictures* and the
row says *not installed*.

## What you see

*Settings → Finding files → Details → What is read → Programs that read more* lists the four, each with ✓ or ✗:

- *tesseract: words in screenshots, scans and pictures (not camera photos)*
- *pdftoppm: scanned PDFs, with tesseract*
- *LibreOffice: older Office files (.doc, .ppt, Works, Write, Lotus 1-2-3), Publisher, Visio*
- *Ghostscript: the text of PostScript files (.ps, .eps)*

A missing one adds *· not installed* and the line that installs it, with **Copy**
([above](#installing-what-is-missing)). While tesseract is missing and text search is on, both
apps show the [notice](../panels/notices.md) *Install tesseract to search the words in scans, screenshots
and pictures: …* with the line for this system: the desktop app under *Settings → Overview →
What's new* until dismissed, with **Copy**; the terminal app once in its status line.

A hit from a picture shows the words tesseract read, as any text hit does. OCR is not perfect:
a word may be read wrong, and then it is found only as it was read.

## Settings and config.toml

None of its own. The programs are found on `PATH` (and in the usual install folders on Windows and
macOS). They run at the lowest priority the system offers, with a time limit of two minutes a
file. At the limit the program is stopped with everything it started (LibreOffice's `soffice`
hands the work to a `soffice.bin` of its own, which goes too), and the file is kept as one that
took too long: it is not read again until it changes, and the preview of `search.db` lists it
among [its latest errors](../previews/data.md#coxswains-own-index-and-store). The usual limits apply: `text_max_size` (20 MB) and the [folders read](folders.md).

## In the terminal app

The same: the helper reads for both apps. **F12** (or *Settings* in **F9**) → *Finding files* lists the
programs under *Programs that read more*: `✓`, or `✗` with the line that installs it, which
**Space** copies to the terminal's clipboard (OSC 52, over ssh too). The tesseract notice shows
in its status line, with the line in it.

## Questions

#### How do I get the words in my screenshots found?

Install tesseract and, for scanned PDFs, poppler's `pdftoppm`. When the helper next starts it finds
them and reads the pictures again. **Read now** in Settings reads the backlog at full speed.

#### A notice says to install tesseract. How?

The notice ends with the command for your system, such as `sudo apt install tesseract-ocr`. In the
desktop app click **Copy** next to it (*Settings → Overview*), paste it into a terminal and run
it. In the terminal app, **F12** → *Finding files*, the cursor on tesseract under
*Programs that read more*, **Space** copies it. Then wait for the helper's next scan, or click
**Read now**. All the lines: [Installing what is missing](#installing-what-is-missing).

#### Why does Coxswain not install it for me?

Installing needs your password and changes the system; that is yours to decide. Coxswain only
writes the line and copies it when you ask.

#### There is no line, only "get it from its website". Why?

The package manager here has no package for it, such as poppler (`pdftoppm`) for `winget`, or
the system has none of the package managers Coxswain knows. Get the program from its own site
and put its folder on `PATH`.

#### I installed tesseract and nothing happened.

The helper looks for the programs once, when it starts. Close every Coxswain window and wait ten
minutes, or make any change under *Settings → Finding files*. With the helper started with
your session, untick and tick *Start with my session* under *Details → Background reading* (or run
`coxswain --index-service off` and `on`). The ✓ in Settings shows it was found.

#### I went back to an older Coxswain and forward again. Are files read again?

No. When a program comes (Ghostscript, LibreOffice, tesseract), the files it reads are read
again once, text and meaning. The helper keeps its own list of the programs it found in the
store, which older versions leave alone, so a kind an older version did not know is not taken
for a program that came, and going back and forth reads nothing again.

#### Why are my holiday photos not read?

A JPEG whose EXIF names the camera maker is a photo, and photos are skipped on purpose: they seldom
have words and there are thousands.

#### Does it read my scanned PDFs page by page?

The first 30 pages, turned into pictures at 200 dpi by `pdftoppm` and read by tesseract. Only a PDF
with no text of its own is handled so.

#### Can I get the words of a scan into the PDF itself?

Yes: **Alt+P** ([Make PDF searchable](../files/searchable-pdf.md)) writes a copy next to it with
the words in it, by OCRmyPDF, which any PDF reader can then search and select. Find reads that
copy as any PDF, all its pages, without tesseract. Nothing is read so in the background: only
when you ask.

#### Will reading pictures slow my machine?

The programs run at the lowest priority, one file at a time, with rests between batches, and not
on [battery](battery.md). The first pass over many pictures takes a while; Settings counts
them as *waiting* on the *Words* line.

#### Does LibreOffice need to be closed?

No. It runs with a profile of its own, so the LibreOffice you have open is not touched.

#### Is anything sent anywhere to be read?

No. The programs run on your machine, into a work folder in Coxswain's cache (`scratch/`) that is
removed afterwards.

---
[← Previous: Documents it reads](documents.md) · [Next: Other formats with Apache Tika →](tika.md)