Ephemeris

<img src="assets/logo.svg" alt="Ephemeris Icon" width="170" align="right">

Your daily path through time.

Ephemeris is a Python-based tool that generates clean, daily schedules using ICS calendar data. Designed with e-ink tablets like reMarkable and Kindle Scribe in mind.

Features

• Automated Schedule Generation: Seamlessly convert ICS calendar data into organized daily planners.
• Customizable Layout: Adjust your daily schedule's layout, timeframe, and appearance via environment variables.
• Elegant PDF Output: Clean PDFs designed specifically for e-ink devices.
• Links to Days: Mini-Calendar days are clickable links.

Screenshots

These screenshots broadly show the layout options that are possible. See Customization for more information.

<p float="left"> <a href="assets/example-default.png"> <img src="assets/example-default.png" alt="Default Layout" width="200px"/> </a> <a href="assets/example-grid-only.png"> <img src="assets/example-grid-only.png" alt="Time Grid Only" width="200px"/> </a> <a href="assets/example-grid-allday.png"> <img src="assets/example-grid-allday.png" alt="All Day Full Width" width="200px"/> </a> <a href="assets/example-centercal.png"> <img src="assets/example-centercal.png" alt="Single Month Mini-Calendar" width="200px"/> </a> </a> <a href="assets/example-allday-ingrid.png"> <img src="assets/example-allday-ingrid.png" alt="All Day In-Grid" width="200px"/> </a> </p>

Getting Started

If using with a reMarkable tablet, I ship an image that bundles the rmapi binary. Check out the wiki for more info.

Calendar Configuration

The program uses a YAML configuration file to set up the calendars:

calendars:
  # ics file
  - name: Personal
    source: calendars/personal.ics
    color: gray8

  # directory containing ics files
  - name: Work
    source: calendars/work
    color: gray6

  # web ics file
  - name: US Holidays
    source: https://www.opm.gov/policy-data-oversight/pay-leave/federal-holidays/holidays.ics
    color: gray4

Supported values for colors are CSS names, hex colors, as well as a series of grays (gray1 through gray14) that correspond to each step of 4-bit grayscale.

Docker Compose

services:
  ephemeris:
    image: ghcr.io/rmitchellscott/ephemeris
    volumes:
      - ./calendars:/app/calendars
      - ./output:/app/output
      - ./config.yaml:/app/config.yaml
      - ./feeds_meta.yaml:/app/feeds_meta.yaml  # Used for change detection
    environment:
      - TZ=America/Denver
      - TIME_DATE_RANGE=week

Docker

# Standard version (default)
docker run --rm \
  -v "$(pwd)/calendars:/app/calendars" \
  -v "$(pwd)/output:/app/output" \
  -v "$(pwd)/config.yaml:/app/config.yaml" \
  -v "$(pwd)/feeds_meta.yaml:/app/feeds_meta.yaml" \
  -e TZ=America/Denver \
  -e TIME_DATE_RANGE=week \
  ghcr.io/rmitchellscott/ephemeris

# Version with rmapi bundled
docker run --rm \
  -v "$(pwd)/calendars:/app/calendars" \
  -v "$(pwd)/output:/app/output" \
  -v "$(pwd)/config.yaml:/app/config.yaml" \
  -v "$(pwd)/feeds_meta.yaml:/app/feeds_meta.yaml" \
  -e TZ=America/Denver \
  -e TIME_DATE_RANGE=week \
  ghcr.io/rmitchellscott/ephemeris:main-rmapi0.0.30

# Build locally
# Standard version (without rmapi)
docker build --target ephemeris -t ephemeris .

# Version with rmapi (default build)
docker build -t ephemeris-rmapi .

Python

Setup

• Python 3.8+
• Dependencies: cairosvg, icalendar, loguru, pypdf, pytz, pyyaml, reportlab, requests, webcolors

Install dependencies with:

pip install -r requirements.txt

Run the script:

python ephemeris.py

For guidence on sending to your device, see the project's wiki.

Common Device Parameters

reMarkable 1

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=226

reMarkable 2

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=226

reMarkable Paper Pro

DOC_PAGE_DIMENSIONS=1620x2160
DOC_PAGE_DPI=229

reMarkable Paper Pro Move

DOC_PAGE_DIMENSIONS=954x1696
DOC_PAGE_DPI=264

Kindle Scribe*

DOC_PAGE_DIMENSIONS=1860x2480
DOC_PAGE_DPI=300

Boox Note Air2 Plus

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=227

Boox Tab Ultra

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=227

Kobo Elipsa 2E

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=227

Supernote A5 X

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=226

Supernote A5 X2 Manta

DOC_PAGE_DIMENSIONS=1920×2560
DOC_PAGE_DPI=300

Supernote A6 X

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=300

Supernote A6 X2 Nomad

DOC_PAGE_DIMENSIONS=1404x1872
DOC_PAGE_DPI=300

TRMNL**

DOC_PAGE_DIMENSIONS=480x800
DOC_PAGE_DPI=125
# Choose one of these for clearer text rendering:
DOC_MONOCHROME=true
DOC_ANTIALIAS=false

_{*Information seems hard to find for the Kindle Scribe. If any of these values need correction, please open a GitHub Issue.}
_{**Have a look at my trmnl-png-processor project.}

Customization & Supported Environment Variables

Time Configuration

| Variable | Default | Example | Description | |:--------------------|:---------------|:---------------------------------|:-------------------------------------------------------------------------------------| | TIME_DATE_RANGE | today | today, week, month, tomorrow, 2025-04-14:2025-04-18 | Date range to create schedules for. Each day will be a single page. A single multi-page PDF will be rendered. | | TIME_DISPLAY_END | 21 | 21 | Defines the ending hour of the displayed daily schedule. | | TIME_FILTER_MIN_HOUR| 0 | 4 | Excludes events with start times before this hour from the generated schedule. | | TIME_DISPLAY_START | 6 | 6 | Defines the starting hour of the displayed daily schedule. | | TZ | UTC | America/New_York | Sets the timezone used for interpreting event times. | | TIME_FORMAT | 24 | 12, 24 | Specifies time formatting in 12-hour or 24-hour formats. |

Application Configuration

| Variable | Default | Example | Description | |:--------------------|:--------------------------|:----------------------|:--------------------------------------------------------------------| | APP_CONFIG_PATH | {BASE_DIR}/config.yaml | /path/to/config.yaml | Path to the configuration file. | | APP_META_FILE_PATH | {BASE_DIR}/feeds_meta.yaml| /path/to/meta.yaml | Path to the feeds metadata file. | | APP_OUTPUT_FORMAT | pdf | pdf, png, both | Output format for the generated schedule. | | APP_OUTPUT_PDF_PATH | output/ephemeris.pdf | reports/schedule.pdf | Path and name for rendered output file. | | APP_OUTPUT_PNG_DIR | output/png | reports/images | Directory for rendered output PNG files, one per day. | | APP_OUTPUT_BG_PNG_DIR | output/png_background | reports/bg_images | Directory for background-only PNG files when DOC_SEPARATE_TEXT is enabled. | | APP_OUTPUT_TEXT_PNG_DIR | output/png_text | reports/text_images | Directory for text-only PNG files when DOC_SEPARATE_TEXT is enabled. | | APP_FORCE_REFRESH | false | true, false | Skip the changed events check and always render a document for each run. | | APP_FILTER_LIST | cancelled,canceled | canceled,removed | Comma-separated list of substrings which, if found in an event's title or status, will drop that event. | | APP_FILTER_DECLINED_EMAILS | (not set) | user@example.com,alias@example.com | Comma-separated list of email addresses. Events where any of these addresses have declined the invitation will be excluded from the schedule. | | APP_POST_HOOK | (not set) | rsync output/ user@server:/path/ | Command to execute after successful document generation. | | APP_LOG_LEVEL | INFO | VISUAL, EVENTS, DEBUG, INFO, WARNING | Minimum log level to output to console. EVENTS is useful for troubleshooting why events are appearing or not. VISUAL shows detailed drawing information for developer debugging. | | APP_LOG_COLORIZE | true | true, false | Whether to use ANSI colors in console log output. | | APP_LOG_FORMAT | (see description) | custom format string | Loguru format string for console output. Default includes timestamp, level, and message. |

Document Rendering

| V