1.1 Introduction

Built with large media collections in mind, Orbit provides a way to view your entire media collection in a unified grid. Even with 100k+ photo's and video's.

1.2 App Structure

The app contains the following parts:

• Menu Bar: Shows the app logo and name. It also features buttons to minimize and close the application.
• Side Bar: Allows you to navigate between the many views. May contain additional buttons at the bottom (like filtering).
• Views: Filling the space not taken up by the other parts, this displays the currently active view.
• Bottom Bar: Show the total media count, alongside additional information (like Explorer scale).

2.1 Explorer View

The Explorer View consists of a grid, allowing you to browse all your content in a single unified place.

To support large datasets, the grid is an infinite scrolling virtualized grid. 200 items are loaded as you scroll, but the experience remains smooth.

Next to the grid, you will find the Preview Panel. This shows a preview of the selected media and its properties (metadata).

Clicking on the preview photo opens it in full screen. When opened fullscreen, the image may also be zoomed.

The preview panels shows all indexed metadata for that media. If a photo has GPS data, the coordinates will be displayed alongside a small leaflet map.

If you configured your birth date in Settings, the properties will also show your age at the time of taking the photo/video.

You can interact with the grid in the following ways:

• CTRL + SCROLL: Change the grid scale (makes items smaller/bigger).
• Single Left Mouse Click: Select item (will be displayed in the Preview Panel).
• Double Left Mouse Click: Open item in fullscreen directly.
• CTRL + Left Mouse Click: Open file in your PC's default viewer for that filetype.
• SCROLL or ARROW KEYS: Navigate.
• T: Assign last used tag to selected item.

Hovering over a grid item will show its filename and date.

2.2 Map View

Shows your photos on an interactive world map. The lower part of the sidebar shows the following buttons:

• Cluster Mode (default): Uses leaflet.markercluster to show all locations as clustered circles. Zooming in will narrow down the locations. Clicking on a cluster while fully zoomed in will reveal all it's locations. Clicking on a red dot (a single photo location) will display it's filename, taken date, device, country (if detected) and altitude (if indexed).
• Heatmap Mode: Shows a heatmap of all locations. Zooming in will adjust the heatmap to whatever is in view.
• Line Mode: Connects all locations with red lines. This creates a path of everywhere you have been. Items that have no altitude, an altitude higher than 1500 meters or have no nearby points are excluded (to avoid flight paths).
• Country Overview: Opens a popup showing all countries you have taken pictures in. Follows the same exclusions as Line Mode to avoid counting countries which were only flown over. Countries will also be highlighted on the map.
• Map Filters: Opens the Action Panel to allow you to filter the effective map data.

2.3 Stats View

See interesting statistics about your entire collection.

Overview

• Total Files
• Total Size
• Total Media Per Year
• Total Media Per Month
• Total Media Per Age
• Top 10 Days by Media Count
• By File Type
• By Device
• By Country

Calendar

• Calendar Heatmap
• Longest Streaks

Sources

• First Date, Last Date and Count per device
• First Date, Last Date and Count per source

Charts

• Total Media Per Year
• Total Media Per Month
• Total Media Per Age
• By Device
• By Country

2.4 Shuffle View

Watch an automatic slideshow of your collection.

Shuffle shows random photos from your library. Via the sidebar you can filter the set of candidates. You may also configure settings about the shuffle (Shuffle interval & Hide metadata).

Images up next are preloaded so you don't have to wait for the image to appear.

The small metadata box in the bottom-right corner, if enabled, shows the filename and date.

2.5 Memories View

Browse automatically curated highlights from your library, or create your own.

Memory types

• All
• Custom
• Years
• Months
• Vacations
• Trips

Custom shows memories created by you. To create a memory, click on the + on the sidebar. You may also edit custom memories using the edit icon on the sidebar.

Each custom memory may have:

• Title
• Description
• Color

You can add media to custom memories in two ways:

• When creating the memory, use the Quick Add form in the 'Add New Memory' popup. This automatically adds files matching your parameters.
• To add to an existing memory, edit the memory and click on the 'Select Media' button. This will take you to the Explorer where you can select items to add or remove.

Orbit automatically generates memories based on your collection. Years and Months are grouped per year/month. Vacations show all your big trips (periods spent outside your home country (based on which country occurs most in your collection), atleast 500 photos). Trips show all trips (same logic as Vacations, but only 10 required photos). Both Vacations and Trips also check which countries were the main focus of the trip.

The All tab shows all memories in a single list. Vacations are not included, as these are a stricter form of Trips.

2.6 Tags View

Manage and create tags for optimal organisation.

You can create tags using the + button on the sidebar. Each tag allows you to set a name, description and color.

All tags are shown in a table, sorted by last used. The table shows the tag (visualized, text = name and background = color), description, amount of files tagged with it, and action buttons.

The following actions are available for a tag:

• View (in Explorer). You may also view tags in Shuffle or Map by simply filtering on them.
• Add Media. Brings you to Explorer to add or remove items.
• Edit. Allows you to edit the name, description and color of the tag.
• Delete. Permanently deletes the tag.

2.7 Settings View

This view allows you to manage your Orbit settings. These are saved in data/config.json.

User

• Username (Text input)
• Birth date (Date input, used for age calculation in photo properties and stats)

Media

• List of indexed sources
• Action buttons (Add Source, Remove All, Tools)
• Smart Search status and progress

Explorer

• Adjust HEIC colors (Checkbox, applies 1.2x saturation on HEIC photo's to adjust for HEIC->JPEG color loss)
• Preload HEIC on hover (Checkbox, pre-decodes HEIC's when hovering over items in the grid for faster loading times)
• Default sort (Selection, options 'ID (default)', 'Name', 'Date Taken', 'Date Created', 'File Size', 'Random')
• Explorer layout (Selection, options 'Grid (default)', 'Justified (collage)')
• Item text (Selection, options 'Filename (default)', 'Date', 'None'. Controls what is shown below item thumbnails)
• No gutters (Checkbox, disables the spacing between grid items)
• Show timeline overlay (Checkbox, toggles the month-year scrubber overlay)

Memories

• Open memories in (Selection, options 'Explorer (default)', 'Shuffle', 'Map'. Controls what happens when clicking on a memory)

Storage

• Overview of storage usage

Controls

Shows all keyboard shortcuts.

General Shortcuts

• Show preview: ~ or `

Explorer Shortcuts

• Show preview: Left Mouse Button
• Open fullscreen: Double Left Mouse Button
• Open in default viewer: CTRL + Left Mouse Button
• Navigate: SCROLL or ARROW KEYS
• Scale grid: CTRL + SCROLL
• Assign last used tag to selected item: T

App

• App version
• Button to open app directory in file explorer
• Button to open user data directory in file explorer
• Button to toggle fullscreen

3.1 Welcome Popup

Shown on first startup (or if you haven't completed it yet). This popup allows you to select folders to index.

3.2 Action Panel

The Action Panel is a control panel that helps you explore, organize, and find your media. It provides different tools for sorting, filtering, searching, and shuffle mode.

Sorting

The sorting options let you control the order in which media is displayed. You can sort by:

• ID: the default internal order.
• Name: alphabetical order.
• Date Taken: when the photo or video was captured.
• Date Created: when the file was created.
• File Size: from smallest to largest (or vice versa).
• Random: a shuffled order.

You can switch between ascending and descending order at any time.

Filtering

Filters help you narrow down your media based on specific properties. Available filters include:

• Year: quickly show media from a specific year.
• Date: select an exact date.
• Date From / To: filter within a date range.
• Device: show media taken on a specific device.
• Filetype: filter by file format (e.g. JPG, PNG, MP4).
• Media Type: separate images and videos.
• Source: filter by folder or location on disk.
• Tag: show media with a specific tag.
• Country: filter by location where media was captured.
• Age: filter based on age at the time the media was taken (if configured).

Some filters automatically adjust others to keep results accurate. For example, selecting a year will set the corresponding date range.

Search

The search feature allows you to quickly find specific media:

• Name: search by filename.
• ID: search using the media ID.
• Smart: search using Smart Search, find media via natural language (e.g. “beach sunset” or “dog in snow”).

When using Smart Search, you can fine-tune the results with:

• Min score: controls how closely results must match your search (higher = more precise, fewer results).
• Max results: limits how many results are returned.

Shuffle Settings

When using shuffle mode, you can customize how media is displayed:

• Shuffle Interval: how long each item is shown (in seconds).
• Hide Metadata: toggle visibility of file details.
• Smooth Transition: enable softer transitions between items.
• Chronological: optionally follow a time-based order instead of random.

All changes in the Action Panel are applied instantly, so you can immediately see the effect. Each section also includes a reset button to quickly return to the default settings.

To keep things clear and consistent, starting a new action (like searching) will automatically reset other settings such as active filters or sorting.

4.1 Application Initialization

The application uses Electron to bootstrap Orbit. On startup, a splash screen is shown while the main window is prepared. Once the main window is ready, it replaces the splash screen.

• Windows: Splash screen (400x400) and Main Window (full size, resizable)
• DevTools: Toggleable with Ctrl/Command + Shift + I

4.2 Custom Protocol Handling

Orbit registers a custom protocol orbit:// to serve thumbnails. The handler resolves files from the data directory and returns them with appropriate MIME types.

4.3 Local File Server

An Express.js server is started on port 54055 to serve files. Special conversions are applied:

• .heic → JPEG (via heic-decode)
• .tif/.tiff → JPEG (via sharp)
• .avi/.wmv/.3gp → MP4 (via ffmpeg)
• RAW photos → JPEG (via dcraw)

All other file types are served directly.

4.4 Data Directory and Config

The app maintains a data directory with:

• orbit-index.db (SQLite database)
• config.json (application settings)
• thumbnails/ (generated thumbnails)

Default configuration includes user preferences such as sort order and HEIC color adjustments.

The data directory is located at C:\Users\[username]\AppData\Roaming.

4.5 Database Schema

Orbit uses better-sqlite3 for storage. The schema includes:

• files - Stores metadata such as filename, size, timestamps, EXIF info, geolocation, and technical camera data.
• folders - Tracks indexed folders.
• memories - Stores custom memories created by the user.
• tags - Stores tags created by the user.
• embeddings - Stores embeddings generated by CLIP to power Smart Search.
• removed_files - Stores which files were removed from the index, so they are not reindexed again.

Indexes are created for efficient querying on create_date_local, create_date, filename, size and created.

4.6 File Indexing

Orbit recursively indexes files inside user-selected folders. For each file:

• Metadata is extracted via exiftool.
• Country lookup performed using GPS coordinates.
• Thumbnails are generated for images (sharp) and videos (ffmpeg).

Concurrency is managed with p-limit to balance performance and system load.

4.7 IPC Handlers

The renderer communicates with the main process using IPC. Handlers include:

• fetch-files - Query paginated files with filters.
• get-settings / save-settings - Manage config file.
• index-files - Trigger indexing for selected folders.
• fix-media-ids - Reassign sequential media_id values.
• open-in-default-viewer, select-folders, minimize-app, etc.

4.8 HEIC Thumbnail Workflow

Missing HEIC thumbnails are handled with a cleanup + script generation system:

• Cleanup: Removes old temporary data.
• Generate script: Produces generate_heic_thumbs.py which uses Pillow + pillow-heif to process files in parallel.

4.9 Metadata Extraction

Orbit extracts technical and photographic metadata using exiftool. All collected metadata fields include:

• File type (image, video, other)
• Device model
• Camera make
• Camera model
• Image width and height
• Orientation
• GPS latitude, longitude, altitude
• Country (derived from GPS coordinates)
• Creation date (DateTimeOriginal / CreateDate)
• Local creation date (Introduced in v1.1, preferred date as it is guaranteed to be the actual media datetime, not affected by timezone differences)
• Lens model
• ISO
• Software used
• Offset time original
• Megapixels (calculated from width × height)
• Exposure time
• Color space
• Flash used
• Aperture (FNumber)
• Focal length
• Focal length in 35mm equivalent
• Filename
• File path
• File size
• File extension
• Folder path
• Creation timestamp (from filesystem)
• Modification timestamp (from filesystem)
• Thumbnail path
• Media ID (unique sequential ID)

4.10 Smart Search

Introduced in v1.2, Smart Search allows you to search for photos based on a description. This semantic search allows you to find photos simply by describing them (e.g. Sunset at the beach).

Orbit uses CLIP to generate embeddings for your photos. These are stored as BLOBs in the embeddings table.

The Smart Search service runs in the background via a worker. This way, the app's performance will not be affected and you can use the app while it is generating.

The service starts when you open the app. It will first retry any previously failed files, before moving on to photos that have yet to be processed.

You can view the status and progress of the Smart Search indexing in Settings > Media > Smart Search

You can use Smart Search even when it has not yet indexed all photos. The query will simply be run on all photos it already has.

In order to not be dependant on any downloads, Orbit is packaged with a copy of the clip-vit-base-patch32 CLIP AI model.

5.1 Supported filetypes

All files can be indexed, but only the following file types can be viewed:

Images

• .jpg / .jpeg
• .png
• .gif
• .bmp
• .tiff / .tif
• .webp
• .heic
• .dng
• .raw
• Many other RAW photo formats



Videos

• .mp4
• .mov
• .avi
• .mkv
• .webm
• .wmv
• .flv
• .3gp

5.2 Colors/Theme

This is an overview of all colors used in Orbit.

Core Backgrounds

Borders & Dividers

Accent & Highlights

Storage Legends

Text & Typography

States & Feedback

Special UI Elements

5.3 Version Overview

This is an overview of all released versions of Orbit.

Logo	Version	Release Date
	v1.1	24/02/2026
	v1.0	02/10/2025

5.4 Changelog

Below is a detailed changelog for all released versions of Orbit.

v1.1

• Tags: create, edit, assign, and filter by tags with custom name and color
• Memories View: create custom memories with title, description, and color; quickly select photos upon creation
• Memories View: click a memory to open it in Explorer with the relevant photos filtered
• Memories View: edit mode with add/remove photo support, including drag-to-select like Windows Explorer
• Memories View: reorderable memories via drag-and-drop, persisted to database
• Memories View: setting to open memories in Explorer, Shuffle, or Map
• Heatmap Calendar: GitHub-style contributions view showing photo count per day
• Longest Streaks: highlights periods where photos were taken every day
• Shuffle View with smooth transition setting and chronological playback option; spacebar toggles video playback
• Revamped Stats View with Charts tab: line graphs for media per year/month/age, bar graphs for by-device and by-country; date range per folder breakdown; devices listed under Sources
• Map: Countries mode highlights visited countries; map buttons moved to sidebar; improved loading times
• Explorer: item name display options (filename, date, or none); no-gutters option for edge-to-edge grid; remembers scroll position and scale when switching views
• Context menu: add tag, remove item from index (with confirmation), view item in full unfiltered Explorer view
• Added create_date_local field for timezone-accurate datetime handling, fixing issues with media taken while traveling or after changing system timezone
• Age filter and year filter now correctly reset when manually adjusting date range
• Improved fallback logic for date fields: uses earliest of created and modified when create_date is unavailable
• Fix Media IDs now uses create_date with created/modified fallback; two-phase handler prevents unique constraint conflicts
• Tags and memories filters now use IDs instead of names to prevent conflicts with duplicate names
• Entering tag/memory add mode auto-selects already-assigned items and overwrites on confirm, enabling removal as well
• CTRL+A selects all items in current filter while in add mode
• Removing items also removes them from associated tag and memory collections
• Removing a source also clears its items from the removed files list
• Unavailable items can be selected to view metadata, showing a clear unavailability message instead of a broken image
• Manual drive letter override per source: changes apply on-the-fly without touching the database
• Faster HEIC viewing via heic-decode; optional HEIC preload on hover
• Thumbnail cleanup tool: removes orphaned thumbnails not referenced in the database
• Changed location of user data to Appdata/Roaming
• Changed the app logo
• Various UI improvements: tooltip on sidebar items, active Settings tab indicator, focus handling, sidebar scaling on small windows, ActionPanel/Explorer filter sync, quick minimize shortcut (~), fullscreen toggle in Settings

v1.0

• Dark purple themed Electron + React app with sidebar navigation (Explorer, Map, Stats, Settings)
• First-run prompt to select folder paths with indexing progress and thumbnail previews
• Metadata indexer: scans selected folders, extracts EXIF data (date, GPS, device, resolution), stores in local SQLite database with incremental indexing on startup
• Thumbnail generator: async generation with local caching at 256×256px
• Infinite scroll thumbnail grid with scaling/zoom support
• Sorting by name, date, and size
• Filtering by date range, device, folder/source, and file type
• Search functionality
• Hover overlay showing filename and date
• Preview Panel: large preview, metadata block, open fullscreen / open in default viewer buttons
• Fullscreen viewer with zoom/pan, arrow key navigation, and HEIC support
• Video thumbnail generation and playback support
• Map View: displays geotagged photos on an interactive map
• Stats View: photo counts and heatmaps
• Folder availability indicator — app remains functional when a source is unavailable
• Bottom bar showing filtered count alongside total when search/filtering is active
• Settings: folder management, thumbnail options, storage usage indicator, re-index option
• Fix IDs and Fix Thumbnails utilities with progress indicators
• Minimize button in menu bar