Panoramax GoPro Downloader

This is a very simple utility script/tool I use for streamlining the process of preparing images taken by a GoPro camera for the upload to Panoramax, in particular for organizing the 360° timelapse images into folders that correspond to each time-series.

The problem

GoPro cameras (at least the GoPro Max I use), save images and videos in a DCIM folder with sub-folders as below:

.
├── DCIM
│   ├── 100GOPRO
│   ├── 101GOPRO
│   ├── 102GOPRO
│   ├── 103GOPRO
│   ├── 104GOPRO
│   ├── 105GOPRO
│   ├── 106GOPRO
│   ├── 107GOPRO
│   ├── 108GOPRO
│   ├── 109GOPRO
│   ├── 110GOPRO
│   ├── 111GOPRO
│   ├── 112GOPRO
│   ├── 113GOPRO
│   └── 114GOPRO
└── MISC

These sub-folders do not correspond to e.g. timelapse image series, but rather just save 999 files in each folder. For many use cases, this is fine, but when doing many timelapse series throughout the day, it becomes cumbersome to find in which sub-folder a time series starts/ends.

The prefix of each GoPro file name indicates the type of recording that created it: For example, GSXXXX.JPG (e.g. GSAA1234.JPG) denotes a picture that's part of a 360° timelapse series named AA, while GPXXXXXX.JPG (e.g. GPAA1234.JPG) denotes pictures that are part of a regular, non-360° timelapse.

When importing images into standard photography suites, this might not matter, but for uploading images to Panoramax, (at least) my workflow is different: Each time series/timelapse represents one sequence that I'd like to upload, from start to finish. And typically I'd like to clean up the start/end images a bit, as often I might have recorded a bit pre- and post-movement. This would be a lot easier if each time series was in its own folder.

The solution

This little tool can be used to split up all images found in the SD-cards DCIM folder into a folder structure that corresponds to the time series/sequences, converting the non-informative 1XXGOPRO above, into a structure like this:

.
├── GSAA
├── GSAB
├── GSAC
├── GSAD
├── GSAE
├── GSAF
└── GSAG

Where each folder represents one sequence of images that make up a timelapse that can be cleaned and uploaded easily.

Install

You can install it from PyPI, using pip install panoramax-gopro-downloader, which will give you the CLI tool.

Alternatively you can install from uv or pipx depending on your preferences:

• run pipx install panoramax-gopro-downloader, then it'll be available as panoramax-gopro-downloader as well, or…
• …run it directly via uvx panoramax-gopro-downloader if you use uv

Usage

The script has two main commands:

1. panoramax-gopro-downloader show-files to list the prefixes/sequences found. By default uses current working directory. You can specify the DCIM folder by using --input-folder
2. panoramax-gopro-downloader copy-files to copy files from either the current working directory (or --input-folder) to the destination specified by --output-folder.

If the output folder doesn't exist yet, it will be created

Development

To develop locally, use uv for managing dependencies etc locally, e.g.:

git clone ssh://git@codeberg.org/gedankenstuecke/panoramax-gopro-downloader.git
uv sync
uv run panoramax-gopro-downloader

## License

This repo is licensed under AGPLv3.