Metadata-Version: 2.4
Name: remarkable-tools
Version: 0.5.2
Summary: A set of tools to interact with reMarkable tablets
Keywords: remarkable,pdf
Author: Gustaf Hendeby
Author-email: Gustaf Hendeby <hendeby@gmail.com>
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Requires-Dist: pikepdf>=10.5.1
Requires-Dist: requests>=2.32.5
Requires-Dist: textual>=8.0.0
Requires-Dist: textual-fspicker>=1.0.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# remarkable

Utilities for interacting with a reMarkable tablet and post-processing exported PDFs.

This project installs two command-line scripts:

- `remarkable`: terminal UI and automation commands for browsing, downloading, and uploading documents.
- `remarkable-hlfix`: PDF post-processing tool that reduces highlight opacity.

## Installation

Install from PyPI:

```bash
pip install remarkable-tools
```

or with uv:

```bash
uv add remarkable-tools
```

To install as a standalone tool (makes `remarkable` and `remarkable-hlfix` available globally without a project):

```bash
uv tool install remarkable-tools
```

For development, install the package in your current environment:

```bash
uv sync
```

Then run scripts with `uv run`:

```bash
uv run remarkable --help
uv run remarkable-hlfix --help
```

If installed as a tool or package entry point, you can call `remarkable` and `remarkable-hlfix` directly.

## Script: remarkable

`remarkable` connects to the tablet over the reMarkable local interface (`http://10.11.99.1`) and supports both interactive and one-shot modes.

### Usage

Start the interactive browser:

```bash
remarkable
```

Start in a specific folder title path:

```bash
remarkable "Work/Meetings"
```

Download newest document and exit:

```bash
remarkable --get-newest
```

Download newest document matching a tag suffix:

```bash
remarkable --get-newest --tag _notes
```

Upload a file and exit:

```bash
remarkable --upload-file ./document.pdf
```

Disable highlight fixing for downloaded PDFs:

```bash
remarkable --no-hl-fix
```

Show installed/runtime version:

```bash
remarkable --version
```

Show where config files are searched (in load order):

```bash
remarkable --show-config-paths
```

### Interactive keys

Global:

- `q`: quit
- `F5`: refresh listing
- `h`: toggle highlight fix for PDF downloads
- `H`: toggle snap-to-text → `/Highlight` annotation conversion for PDF downloads
- `t`: set a tag filter used by downloads (Enter confirms, Esc cancels)
- `/`: filter the current view (type to narrow, Enter to apply, Esc to clear)
- `←` / `→` or `Tab` / `Shift+Tab`: move between the folder and document panes
- `Backspace`: go up one folder

Selecting a folder (`Enter` or click) opens it. With a document selected:

- `d`: download as PDF (honours the HL Fix toggle)
- `D`: download as `.rmdoc`
- `u`: upload a file from disk (opens a file picker)

The status bar above the panes shows the current location (`/ Books / Papers`),
the active filter as a `filter: /…/` chip (only visible while filtering), the
highlight-fix state, and the active tag. Pane titles show item counts, and
switch to `matched/total` while a filter is active.

Downloads and uploads run in the background; a toast notification reports
success or failure so the UI stays responsive.
you can always confirm active settings before downloading.

## Script: remarkable-hlfix

`remarkable-hlfix` rewrites a PDF so reMarkable-style highlights are no longer fully opaque.

Default behavior:

- Targets known reMarkable highlight colors.
- Reduces fully opaque highlight fill and stroke opacity from `1.0` to `0.4`.
- Preserves graphics-state scoping (`q`/`Q`) so opacity changes do not leak between sibling drawing blocks.
- Detects snap-to-text highlights (clean axis-aligned rectangles of approximately one line height) and converts them into native PDF `/Highlight` annotations. The original drawing is removed for the converted lines, so PDF readers render them as real text-markup highlights that can be selected and copied with the underlying text. Freehand (non-snapped) highlights fall back to the transparency pass. See [docs/snap-to-annotations.md](docs/snap-to-annotations.md) for the heuristic's design rationale and ideas for future improvement.

### Usage

Basic conversion:

```bash
remarkable-hlfix input.pdf output.pdf
```

Run with default filenames (`input.pdf` -> `output.pdf`):

```bash
remarkable-hlfix
```

Apply to all fully opaque filled shapes instead of only known highlight colors:

```bash
remarkable-hlfix input.pdf output.pdf --all-colors
```

Tune minimum stroke width required before applying stroke transparency:

```bash
remarkable-hlfix input.pdf output.pdf --min-stroke-width 4.0
```

Disable snap-to-text annotation conversion (keeps all highlights as drawn rectangles and only applies the transparency pass):

```bash
remarkable-hlfix input.pdf output.pdf --no-snap-annotations
```

Detect highlight palette from one page and print a paste-ready color block:

```bash
remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
```

Show installed/runtime version:

```bash
remarkable-hlfix --version
```

Show where config files are searched (in load order):

```bash
remarkable-hlfix --show-config-paths
```

## Configuration

Both scripts load defaults from the same config files (later files override earlier ones).

To see the exact search order on your machine, run:

```bash
remarkable --show-config-paths
```

or:

```bash
remarkable-hlfix --show-config-paths
```

This works both in project environments (`uv run ...`) and for globally installed tools (`uv tool install ...`).

Expected format:

```toml
[general]
hl_fix = true
tag = ""
url = "http://10.11.99.1"

[highlight]
alpha = 0.4
alpha_threshold = 0.999
min_stroke_width = 0.1
color_tolerance = 0.1
snap_to_annotations = false
snap_line_height_min = 4.0
snap_line_height_max = 32.0
snap_min_aspect = 0.5
snap_annotation_alpha = 1.0
snap_merge_path = false
```

All fields are optional and fall back to the defaults shown above. Command-line arguments override config values.

### [general] options

| Option | Default | Description |
|---|---|---|
| `hl_fix` | `true` | Whether to apply highlight fixing when downloading PDFs via `remarkable`. |
| `tag` | `""` | Tag suffix filter used by `--get-newest`. |
| `url` | `"http://10.11.99.1"` | URL of reMarkable (do not change unless reMarkable changes standard endpoint). |

### [highlight] options

These control `remarkable-hlfix` behavior. Command-line flags (where available) override config values.

| Option | Default | Description |
|---|---|---|
| `alpha` | `0.4` | Target opacity applied to highlight fill and stroke. |
| `alpha_threshold` | `0.999` | Minimum opacity for a shape to be considered fully opaque and eligible for reduction. |
| `min_stroke_width` | `0.1` | Minimum stroke width (in PDF units) required before stroke opacity is reduced. Raise this to leave thin lines untouched. |
| `color_tolerance` | `0.1` | Per-channel tolerance when matching fill colors against the known highlight palette. |
| `snap_to_annotations` | `false` | Convert snap-to-text highlight rectangles into native PDF `/Highlight` annotations. Disabled by default because the detector is heuristic; enable it when the source PDF reliably uses snap-to-text highlights. Detection is per-subpath, so a path containing both a snap rectangle and other shapes only converts the rectangle. Combined fill+stroke paint operators (`B`, `b`, `B*`, `b*`) are never converted, to avoid silently dropping the stroke. |
| `snap_line_height_min` | `4.0` | Minimum rectangle height (PDF user-space units, 1/72") that qualifies as a single text line. |
| `snap_line_height_max` | `32.0` | Maximum rectangle height that qualifies as a single text line. |
| `snap_min_aspect` | `0.5` | Minimum width/height ratio required to treat a rectangle as text-line shaped. |
| `snap_annotation_alpha` | `1.0` | Opacity (`/CA`) written into the generated `/Highlight` annotation. |
| `snap_merge_path` | `false` | When a single snap-to-text path produces several rectangles (a multi-line highlight), emit them as a single `/Highlight` annotation with one `/QuadPoints` quad per line. Disabled by default so each line remains its own annotation, matching what earlier versions produced; enable it to get one annotation per user-intent highlight. |

## Troubleshooting

### remarkable cannot connect to device

Symptoms:

- Requests fail or time out.
- You see connection errors when listing folders or downloading files.

Checks:

1. Ensure the tablet is connected over USB and USB web interface access is enabled.
2. Verify the endpoint is reachable:

```bash
curl -I http://10.11.99.1/documents/
```

3. If needed, retry after reconnecting the cable and restarting the tablet's USB web interface.

### config-related startup failure

Ensure the config file uses the correct TOML structure (see [Configuration](#configuration) above).

If you are testing quickly, run with explicit flags to avoid relying on config values.

### downloaded PDF highlights look unchanged

Try one of these:

1. Make sure highlight fixing is enabled (`--hl-fix` or toggle `h` in the UI).
2. Run a direct pass with `remarkable-hlfix`.
3. If your document uses non-standard colors, run calibration first:

```bash
remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
```

4. If highlights are very thin, lower the stroke threshold:

```bash
remarkable-hlfix input.pdf output.pdf --min-stroke-width 1.0
```

### remarkable-hlfix input errors

Common causes:

- Input path is wrong.
- File is encrypted or malformed.
- Calibration page number does not exist in the PDF.

Checks:

1. Confirm file paths are correct.
2. Start with the basic command:

```bash
remarkable-hlfix input.pdf output.pdf
```

3. If that fails, try opening and re-saving the PDF with another tool, then run again.
