Home

Awesome

remarks

⚠️ remarks does NOT work with annotations created by reMarkable sofware >= 3.0 yet. Follow issue #58 for updates ⚠️

Extract annotations (text highlights and scribbles) and convert them to Markdown, PDF, PNG, and SVG.

remarks works with documents annotated on reMarkable™ paper tablets — both 1st and 2nd generation — up to software version 2.15.0.1067.

Note that remarks not only is highly experimental, it is very likely to break after you update the software of your tablet. I might find some spare time to continue to maintain it, but I make no promises.

remarks code is fairly straightforward but not elegant at all. It has been put together in a couple of hours. You are free to fork and run with it though ;)

Most of the actual heavy lifting has been done by the open source community and PyMuPDF. See Credits and Acknowledgements.

Some use cases

A visual example

Highlight and annotate PDFs with your Marker on your reMarkable tablet:

<!-- How to host images on GitHub but outside your repository? Open an issue, upload your images, and voila! Trick learned from http://felixhayashi.github.io/ReadmeGalleryCreatorForGitHub/ --> <img width="300" alt="IMG_0642-low.jpg" src="https://user-images.githubusercontent.com/1920195/88480247-3d776680-cf2b-11ea-9c30-061ec0e5cc60.jpg">

And then use remarks to export annotated pages to Markdown, PDF, PNG, or SVG on your computer:

<img width="300" alt="demo-remarks-png.png" src="https://user-images.githubusercontent.com/1920195/88480249-410aed80-cf2b-11ea-919b-22fb550ed9d7.png">

<mark>WHAT IS LIFE?</mark>

Based on lectures delivered under the auspices of the <mark>Dublin Institute for</mark> <mark>Advanced Studies at Trinity College,</mark> Dublin, in February 1943

<mark>To</mark> <mark>the memory of My</mark> <mark>Parents</mark>

Compatibility and dependencies

Because remarks depends only on PyMuPDF and Shapely, there is no need to install imagemagick, opencv, or any additional image library. Both PyMuPDF and Shapely have pre-built wheels for several platforms (macOS, Linux, Windows) and recent Python 3 versions, so installing them should be smooth and easy for most people.

I currently use remarks with reMarkable 1 and reMarkable 2 tablets running software versions 2.14.3.1047 and 2.15.0.1067 on macOS Ventura (13.2.1) with CPython 3.10.9. I don't have other equipment to test it thoroughly, but I expect remarks to work just fine in all common setups.

Incidentally, help the community keeping track of remarks compatibility across different setups:

If OCRmyPDF is available on your computer, remarks may (optionally) use it to OCR PDFs before extracting their highlighted text.

Setup

To get remarks up and running on your local machine, follow the instructions below:

1. Copy reMarkable's "raw" document files to your computer

In order to reconstruct your highlights and annotations, remarks relies on specific files that are created by the reMarkable device as you use it. Because these specific files are internal to the reMarkable device, first we need to transfer them to your computer.

There are several options for getting them to your computer. Find below some suggestions. Choose whatever fits you:

2. Clone this repository and install the dependencies

### 2.1 Clone
git clone https://github.com/lucasrla/remarks.git && cd remarks


### 2.2 Create and activate a virtual environment

# If you're using poetry, a new virtual env should be created automatically (as set forth in our `poetry.toml`)
# But feel free to manage your virtual env needs with any of the alternatives (e.g. virtualenv, virtualenvwrapper, etc)


### 2.3 Install the dependencies

# Install dependencies with:
poetry install

Usage and Demo

Run remarks and check out what arguments are available:

python -m remarks --help

Next, for a quick hands-on experience of remarks, run the demo:

# Alan Turing's 1936 foundational paper (with a few highlights and scribbles)

# Original PDF file downloaded from:
# "On Computable Numbers, with an Application to the Entscheidungsproblem"
# https://londmathsoc.onlinelibrary.wiley.com/doi/abs/10.1112/plms/s2-42.1.230

python -m remarks demo/on-computable-numbers/xochitl remarks-example/ --per_page_targets png md pdf --modified_pdf

A few other examples:

# Assuming your `xochitl` files are at `~/backups/remarkable/xochitl/`

python -m remarks ~/backups/remarkable/xochitl/ example_1/ --ann_type highlights --per_page_targets md

python -m remarks ~/backups/remarkable/xochitl/ example_2/ --per_page_targets png

Tests

Run pytest in the root directory of the project after installing the dependencies using poetry. This will create files in the tests/out directory. The contents of this directory can safely be deleted.

Example:

python -m pytest -q remarks/test_initial.py
..                                         [100%]
2 passed in 2.51s

ls tests/out
  1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _highlights.md  
  Gosper _remarks.pdf
  1936 On Computable Numbers, with an Application to the Entscheidungsproblem - A. M. Turing _remarks.pdf

Credits and Acknowledgements

For more reMarkable resources, check out awesome-reMarkable and remarkablewiki.com.

License

remarks is Free Software distributed under the GNU General Public License v3.0.

Disclaimers

This is a hobby project of an enthusiastic reMarkable user. There is no warranty whatsoever. Use it at your own risk.

The author(s) and contributor(s) are not associated with reMarkable AS, Norway. reMarkable is a registered trademark of reMarkable AS in some countries. Please see https://remarkable.com for their products.