Metadata-Version: 2.5
Name: golblick
Version: 0.8.1
Summary: Read, inspect and render 360 camera files on Linux
Project-URL: Homepage, https://github.com/AkshayRao27/golblick
Project-URL: Issues, https://github.com/AkshayRao27/golblick/issues
Project-URL: Releases, https://github.com/AkshayRao27/golblick/releases
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: 360,equirectangular,fisheye,insta360,nextcloud,panorama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Provides-Extra: desktop
Requires-Dist: numpy>=1.24; extra == 'desktop'
Requires-Dist: pillow>=10.0; extra == 'desktop'
Requires-Dist: pyside6>=6.6; extra == 'desktop'
Provides-Extra: render
Requires-Dist: numpy>=1.24; extra == 'render'
Requires-Dist: pillow>=10.0; extra == 'render'
Description-Content-Type: text/markdown

# <img src="https://raw.githubusercontent.com/AkshayRao27/golblick/v0.8.1-alpha/src/golblick/golblick.svg" alt="" width="44" align="right"> Golblick

**Read, inspect and render 360-camera files on Linux.**

<dl>
<dt><b>gol</b> &nbsp;/ɡol/ &nbsp;<i>adjective</i></dt>
<dd>Marathi गोल, borrowed from Sanskrit गोल (<i>gola</i>). Round, circular; in geometry, cylindrical or spherical.</dd>
<dt><b>blick</b> &nbsp;/blɪk/ &nbsp;<i>verb</i></dt>
<dd>German, the singular imperative of <i>blicken</i>: to look, usually in a certain direction or toward something.</dd>
</dl>

---

## Why?

I've been into photospheres since 2014-ish. My first 360 camera was a Nikon KeyMission (yes, yes... I know...) which saved images in standard formats. Then, along came Insta360 with their `.insp` and `.insv` shenanigans. It didn't bother me till earlier this year when two things happened:

1. I got sick and tired of Windows 11 and just how hard Macro$lop was enshittifying it and finally migrated to Linux.
2. I decided I'd rather pay once for hardware upfront, cancelled all my cloud subscriptions, and built a little Proxmox-based home server and fully migrated to Nextcloud.

Then I realised that Insta360 has no desktop app for Linux, and there was no way for me to view all my Photospheres on my PC or on Nextcloud. I didn't want to run Insta360 Studio in an emulator and I couldn't find any other solution for Linux & Nextcloud.

But Slopinators exist now, so I asked one to help me.

An Insta360 `.insp` opens in any image viewer on Linux, but as two fisheye circles side by side. Turns out that everything you need to turn those circles into a panorama is in a trailer at the end of the file, in plain ASCII and protobuf, readable without any of the vendor's code.

Golblick reads that trailer and renders a levelled panorama that any 360 viewer will open as a sphere. A companion Nextcloud app shows them as panoramas in Nextcloud Files, Photos and Memories, with a button to look around each one as a sphere.


https://github.com/user-attachments/assets/60cfc859-e7f0-4d17-9321-0f0ac0c8ee87

---

## 🚩 Please read this before you proceed

**All of the code and much of the text here was generated by Claude Code**, mostly with Opus 5, then Fable 5 and Opus 5.5; each commit names the model that made it. I directed it and tested its functionality, but I know just barely enough programming scraps to know how much I truly don't know and understand. There is absolutely no way in hell I could have built this kind of an app or written this kind of code myself. I cannot conceivably fully bug-test or security-audit it, nor can I find optimisations, issues, etc.

What I can say, however, is that

- Of the 1,438 stills from three cameras (Insta360 OneR, X3 and X5) in my photo library, 1,432 render as level panoramas (the rest are empty, or had the camera's data stripped), both from the command line and as previews in Memories on throwaway Nextcloud 33 and 35 instances in Docker, running locally, **and on my prod Nextcloud AIO v14.2.0 server** without anything breaking.
    - The Nextcloud app only reads files and generates previews, but it needs a line in Nextcloud's config, and that line has side effects worth reading about in [the app's README](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/nextcloud-app/README.md) before you add it.
- The code has not borked anything on my desktop running Kubuntu 26.04
    - `probe`, `triage`, `report` and `vendors` only read files.
    - `thumb`, `preview`, `render` and `stabilise` write one new file, next to the original unless you pass `-o`. They will overwrite an existing file with that name, but refuse to write over the file they are reading.
    - `share` writes copies into a new folder, `golblick-share` unless you pass `-o`, and won't overwrite a copy that's already there.
- The Nextcloud app's video support (stitching, steadying, Memories, and baking the steadying in on a GPU) ran first on test instances (the official Nextcloud Docker image and a copy of AIO v14.2.0), and since 0.5.0 on my prod server too, with an NVIDIA T1000 for the baking.

### ⚠️ YMMV

> [!WARNING]
> This is barely-alpha, fully-vibe-coded "software" built to solve a specific problem that I couldn't find a better solution for. It works with data from the three cameras I have had access to, is optimised specifically for those files, for my use case and on my system. There is no support, no warranty, no promise that any of this will be maintained, and no assurance that it won't cause your system to commit sudoku.

- **Try it somewhere disposable first**, like a throwaway system or a test instance. Don't point it at originals until it does what you want.
- **Keep backups** of anything you care about (which for photos you should be doing anyway).

<i>It might work for you.<br>It might not.<br>I do not claim to know.</i>

---

## What it does

| | |
|---|---|
| 🧭 **Triage** | Pairs each video with its low-resolution copy (`.lrv`) and lists the clips whose full-quality video is gone, so you know what exists only in low resolution before you delete anything. Goes by filename, so it takes seconds on a whole library |
| 🔍 **Probe** | Shows what the camera stored in a file: model, firmware, lens calibration, and which data blocks are present |
| 🔒 **Share** | Copies photos for sending to someone else, without the location, the dates or the camera's serial number, and otherwise unchanged |
| 📝 **Report** | Summarises a file for an issue on GitHub, without its name, folder or the camera's serial number, and links to the right form: a problem with a photo or a video, or a camera golblick hasn't been tested with |
| 🖼️ **Previews** | Extracts the camera's own preview, if available (e.g. the Insta360 X5 already has a stitched pano) |
| 🎯 **Stabilise** | Works out, from the camera's motion sensor, the rotation that steadies each frame of a 360 video, and writes it as JSON |
| 🌐 **Render** | Projects the lens pair into an equirectangular panorama with GPano metadata, levelled against the camera's own stitch where the file has one (X5), otherwise from its motion sensor where possible. The seam between the lenses is placed per photo, where the two lenses agree best. A video is stitched whole into a 360 MP4, steadied |
| 🖥️ **Desktop** | Double-click a `.insp` photo or `.insv` video in your file manager to look around in it, in golblick's own viewer window. The graphics card projects it as it's drawn, so a photo is on screen in about a second and a video plays steadied with nothing stitched first |
| ☁️ **Nextcloud** | A preview app, so `.insp` stills show up as panoramas in Files, Photos and Memories, zoom included, and open as a sphere from a button. No extra server dependencies for photos. Optionally, `.insv` videos too: the server stitches them in the background with ffmpeg into ordinary 360° MP4s, which play as a steadied sphere from Files and can show up in Memories' timeline. Works alongside [files_photospheres](https://apps.nextcloud.com/apps/files_photospheres) |

## Cameras

| Camera | Status |
|---|---|
| Insta360 OneR, X3, X5, stills (`.insp`) | ✅ Read, rendered and levelled. The lens shape is measured per camera on the OneR and X3, and read from each file's own calibration on the X5 |
| Insta360 video (`.insv`, `.lrv`) | 🟨 All three cameras. `render` stitches a whole clip into a steadied 360 MP4 (it needs ffmpeg), `open` plays one in the viewer window, and the Nextcloud app stitches clips in the background and plays them as a sphere, steadied from the camera's motion sensor as they play; `stabilise` writes the steadying rotation for every frame. People and things close to the camera can still break up where the two lenses meet |
| Other Insta360 models | ❓ Untested. Other models may store things differently - if you have one [please consider contributing](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/CONTRIBUTING.md#testing-a-camera-i-dont-have) |
| Other vendors | ❌ None yet - if you have a camera I do not, [please consider contributing](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/CONTRIBUTING.md#testing-a-camera-i-dont-have)  |

## Quick start

You need Python 3.10 or newer and [uv](https://docs.astral.sh/uv/getting-started/installation/):

```sh
uv tool install 'golblick[render]'
golblick render IMG_20260314_090809_00_007.insp -o pano.jpg
golblick triage ~/Photos
```

`uv tool upgrade golblick` updates it later. Without `[render]` everything except rendering still works, with no dependencies at all. `pip install 'golblick[render]'` works too. Each [release](https://github.com/AkshayRao27/golblick/releases) also has the Nextcloud app, and `uv tool install 'golblick[render] @ git+https://github.com/AkshayRao27/golblick'` installs the latest code from GitHub instead of the last release.

To open photos and videos by double-clicking them, install `[desktop]` instead, which adds the viewer window (Qt, about 100 MB), and register it once:

```sh
uv tool install 'golblick[desktop]'
golblick desktop install
```

## More

- [docs/usage.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/docs/usage.md): every command, with example output
- [nextcloud-app/README.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/nextcloud-app/README.md): installing the Nextcloud app, what it changes, and setting up videos
- [docs/formats/insta360.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/docs/formats/insta360.md): what is known about the Insta360 container, and how everything was measured
- [docs/accuracy.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/docs/accuracy.md): how renders are checked, and the blind spot of each check
- [CONTRIBUTING.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/CONTRIBUTING.md): reporting issues, and testing a camera I don't have
- [docs/development.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/docs/development.md) and [AGENTS.md](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/AGENTS.md): working on the code, by hand or with coding agents

Files named `*agent-notes*` hold the detailed working notes behind the docs: every measurement, how it was made, and the conclusions that turned out wrong. They're written mainly for coding agents, but anyone curious is welcome to read them.

## Prior art

[insv-stitch](https://github.com/BenjaminHenriksson/insv-stitch) (MIT) is a video-only Insta360 X5 stitching pipeline and was a useful reference for the projection maths. It is not vendored here.

[raw360-formats](https://github.com/freeKC/raw360-formats) (MIT) and [GyroView](https://github.com/bubo-squared/GyroView) (MIT) read the X5's richer lens calibration as a unified camera model, and GyroView measured how far its scale is from the vendor's stitch. golblick's X5 lens curve follows that reading, measured again here against the camera's own panorama.

## Licence

AGPL-3.0-or-later, for the whole repository. You can use, change and share it, including commercially, but if you distribute a modified version, or let people use one over a network, you have to publish your changes under the same licence. The full text is in [LICENSE](https://github.com/AkshayRao27/golblick/blob/v0.8.1-alpha/LICENSE).

Not affiliated with, endorsed by, or connected to any camera manufacturer. Vendor names are used only to identify the file formats this software reads.
