golblick 0.8.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- golblick-0.8.1/.code-hygiene.toml +5 -0
- golblick-0.8.1/.github/ISSUE_TEMPLATE/photo-problem.yml +53 -0
- golblick-0.8.1/.github/ISSUE_TEMPLATE/untested-camera.yml +53 -0
- golblick-0.8.1/.github/ISSUE_TEMPLATE/video-problem.yml +53 -0
- golblick-0.8.1/.github/workflows/ci.yml +50 -0
- golblick-0.8.1/.github/workflows/release.yml +56 -0
- golblick-0.8.1/.gitignore +17 -0
- golblick-0.8.1/AGENTS.md +96 -0
- golblick-0.8.1/CONTRIBUTING.md +44 -0
- golblick-0.8.1/LICENSE +661 -0
- golblick-0.8.1/PKG-INFO +155 -0
- golblick-0.8.1/README.md +123 -0
- golblick-0.8.1/docs/accuracy.md +41 -0
- golblick-0.8.1/docs/development.md +71 -0
- golblick-0.8.1/docs/formats/insta360-agent-notes.md +1008 -0
- golblick-0.8.1/docs/formats/insta360.md +66 -0
- golblick-0.8.1/docs/usage.md +225 -0
- golblick-0.8.1/pyproject.toml +73 -0
- golblick-0.8.1/src/golblick/__init__.py +24 -0
- golblick-0.8.1/src/golblick/cli.py +1016 -0
- golblick-0.8.1/src/golblick/desktop.py +147 -0
- golblick-0.8.1/src/golblick/errors.py +31 -0
- golblick-0.8.1/src/golblick/exif.py +128 -0
- golblick-0.8.1/src/golblick/fling.py +95 -0
- golblick-0.8.1/src/golblick/golblick.svg +5 -0
- golblick-0.8.1/src/golblick/gpano.py +207 -0
- golblick-0.8.1/src/golblick/icons.py +27 -0
- golblick-0.8.1/src/golblick/imaging.py +89 -0
- golblick-0.8.1/src/golblick/playback.py +354 -0
- golblick-0.8.1/src/golblick/render.py +1316 -0
- golblick-0.8.1/src/golblick/scene.py +300 -0
- golblick-0.8.1/src/golblick/stabilise.py +575 -0
- golblick-0.8.1/src/golblick/triage.py +177 -0
- golblick-0.8.1/src/golblick/vendors/__init__.py +119 -0
- golblick-0.8.1/src/golblick/vendors/insta360/__init__.py +119 -0
- golblick-0.8.1/src/golblick/vendors/insta360/calibration.py +287 -0
- golblick-0.8.1/src/golblick/vendors/insta360/imu.py +546 -0
- golblick-0.8.1/src/golblick/vendors/insta360/keyframe.py +137 -0
- golblick-0.8.1/src/golblick/vendors/insta360/lens.py +118 -0
- golblick-0.8.1/src/golblick/vendors/insta360/metadata.py +237 -0
- golblick-0.8.1/src/golblick/vendors/insta360/naming.py +62 -0
- golblick-0.8.1/src/golblick/vendors/insta360/preview.py +128 -0
- golblick-0.8.1/src/golblick/vendors/insta360/share.py +111 -0
- golblick-0.8.1/src/golblick/vendors/insta360/source.py +92 -0
- golblick-0.8.1/src/golblick/vendors/insta360/thumbnail.py +110 -0
- golblick-0.8.1/src/golblick/vendors/insta360/trailer.py +230 -0
- golblick-0.8.1/src/golblick/video.py +897 -0
- golblick-0.8.1/src/golblick/viewer.py +1544 -0
- golblick-0.8.1/tests/conftest.py +65 -0
- golblick-0.8.1/tests/test_cli.py +149 -0
- golblick-0.8.1/tests/test_desktop.py +134 -0
- golblick-0.8.1/tests/test_fling.py +126 -0
- golblick-0.8.1/tests/test_gpano.py +218 -0
- golblick-0.8.1/tests/test_imaging.py +68 -0
- golblick-0.8.1/tests/test_insta360_calibration.py +242 -0
- golblick-0.8.1/tests/test_insta360_imu.py +521 -0
- golblick-0.8.1/tests/test_insta360_keyframe.py +104 -0
- golblick-0.8.1/tests/test_insta360_lens.py +138 -0
- golblick-0.8.1/tests/test_insta360_preview.py +74 -0
- golblick-0.8.1/tests/test_insta360_source.py +87 -0
- golblick-0.8.1/tests/test_insta360_thumbnail.py +29 -0
- golblick-0.8.1/tests/test_insta360_trailer.py +175 -0
- golblick-0.8.1/tests/test_playback.py +262 -0
- golblick-0.8.1/tests/test_render.py +938 -0
- golblick-0.8.1/tests/test_share.py +130 -0
- golblick-0.8.1/tests/test_stabilise.py +276 -0
- golblick-0.8.1/tests/test_triage.py +84 -0
- golblick-0.8.1/tests/test_vendors.py +42 -0
- golblick-0.8.1/tests/test_video.py +279 -0
- golblick-0.8.1/uv.lock +621 -0
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
# Settings for the code-hygiene scanner. The notes under .claude/ are a private
|
|
2
|
+
# repository, so public code must not cite them.
|
|
3
|
+
private = ['(?<![\w/-])history/\d\d_[\w-]+\.md', 'PLAN\.md', '\.claude/', 'prototypes/']
|
|
4
|
+
notes = ["AGENTS.md", "docs/formats/insta360-agent-notes.md", "nextcloud-app/AGENT-NOTES.md"]
|
|
5
|
+
exclude = ["nextcloud-app/js/*", "nextcloud-app/node_modules/*"]
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: A photo looks wrong or won't open
|
|
2
|
+
description: For the cameras golblick has been tested with (Insta360 OneR, X3 and X5)
|
|
3
|
+
title: "Photo problem: "
|
|
4
|
+
labels: ["bug"]
|
|
5
|
+
body:
|
|
6
|
+
- type: markdown
|
|
7
|
+
attributes:
|
|
8
|
+
value: |
|
|
9
|
+
For a camera golblick hasn't been tested with, use the "Trying a camera golblick hasn't been tested with" form instead.
|
|
10
|
+
|
|
11
|
+
The report from golblick leaves out the file's name, its folder and the camera's serial number, so it's safe to paste here. Please don't attach whole photos unless you're happy for them to be public; a crop showing the problem is usually enough.
|
|
12
|
+
- type: input
|
|
13
|
+
id: camera
|
|
14
|
+
attributes:
|
|
15
|
+
label: Camera model and firmware
|
|
16
|
+
placeholder: Insta360 OneR, v1.2.66_build1
|
|
17
|
+
validations:
|
|
18
|
+
required: true
|
|
19
|
+
- type: textarea
|
|
20
|
+
id: report
|
|
21
|
+
attributes:
|
|
22
|
+
label: Report from golblick
|
|
23
|
+
description: From `golblick report <file>`, or "Report to golblick" in a `.insp` file's actions menu in Nextcloud Files. Both fill this in for you if you use the link they give.
|
|
24
|
+
render: text
|
|
25
|
+
validations:
|
|
26
|
+
required: true
|
|
27
|
+
- type: textarea
|
|
28
|
+
id: what
|
|
29
|
+
attributes:
|
|
30
|
+
label: What's wrong
|
|
31
|
+
description: What you did, what you expected and what you got. For a panorama, say whether it's upside down, tilted, mirrored, or broken where the two lenses meet.
|
|
32
|
+
validations:
|
|
33
|
+
required: true
|
|
34
|
+
- type: dropdown
|
|
35
|
+
id: photos
|
|
36
|
+
attributes:
|
|
37
|
+
label: Can you share a few original photos privately?
|
|
38
|
+
description: Original files help most. **Don't attach them here or post links to them**, because issues are public. If you choose yes, you'll get a private upload link in a reply. First run `golblick share <files>` on them, which makes copies without the location, the dates or the camera's serial number. The pictures themselves are unchanged, so pick ones you're happy for the maintainer to see.
|
|
39
|
+
options:
|
|
40
|
+
- "No"
|
|
41
|
+
- "Yes"
|
|
42
|
+
validations:
|
|
43
|
+
required: true
|
|
44
|
+
- type: dropdown
|
|
45
|
+
id: where
|
|
46
|
+
attributes:
|
|
47
|
+
label: Where did you run golblick?
|
|
48
|
+
options:
|
|
49
|
+
- Command-line tool
|
|
50
|
+
- Nextcloud app
|
|
51
|
+
- Both
|
|
52
|
+
validations:
|
|
53
|
+
required: true
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: Trying a camera golblick hasn't been tested with
|
|
2
|
+
description: Any 360 camera other than the Insta360 OneR, X3 and X5. Reports are useful whether renders work as intended or not.
|
|
3
|
+
title: "Untested camera: "
|
|
4
|
+
labels: ["untested camera"]
|
|
5
|
+
body:
|
|
6
|
+
- type: markdown
|
|
7
|
+
attributes:
|
|
8
|
+
value: |
|
|
9
|
+
golblick has only been tested on the Insta360 OneR, X3 and X5. Other cameras may store things differently, so a report on any other model helps, even if everything looks right. The report shows whether golblick can read the camera's files; supporting the camera properly needs a few original photos as well, which you can send privately (see below). [CONTRIBUTING.md](https://github.com/AkshayRao27/golblick/blob/main/CONTRIBUTING.md#testing-a-camera-i-dont-have) lists what to try.
|
|
10
|
+
|
|
11
|
+
The report from golblick leaves out the file's name, its folder and the camera's serial number, so it's safe to paste here. Please don't attach whole photos unless you're happy for them to be public; a crop is usually enough.
|
|
12
|
+
- type: input
|
|
13
|
+
id: camera
|
|
14
|
+
attributes:
|
|
15
|
+
label: Camera model and firmware
|
|
16
|
+
placeholder: Insta360 X4, v1.0.0
|
|
17
|
+
validations:
|
|
18
|
+
required: true
|
|
19
|
+
- type: textarea
|
|
20
|
+
id: report
|
|
21
|
+
attributes:
|
|
22
|
+
label: Report from golblick
|
|
23
|
+
description: From `golblick report <file>`, or "Report to golblick" in a `.insp` or `.insv` file's actions menu in Nextcloud Files. Both fill this in for you if you use the link they give. Reports on a few photos are better than one.
|
|
24
|
+
render: text
|
|
25
|
+
validations:
|
|
26
|
+
required: true
|
|
27
|
+
- type: textarea
|
|
28
|
+
id: what
|
|
29
|
+
attributes:
|
|
30
|
+
label: How does it look?
|
|
31
|
+
description: Does the panorama look right? Check that it's upright and not mirrored, and that lines continue across the seam where the two lenses meet. If it didn't render at all, say what happened.
|
|
32
|
+
validations:
|
|
33
|
+
required: true
|
|
34
|
+
- type: dropdown
|
|
35
|
+
id: photos
|
|
36
|
+
attributes:
|
|
37
|
+
label: Can you share a few original photos privately?
|
|
38
|
+
description: Original files help most. **Don't attach them here or post links to them**, because issues are public. If you choose yes, you'll get a private upload link in a reply. First run `golblick share <files>` on them, which makes copies without the location, the dates or the camera's serial number. The pictures themselves are unchanged, so pick ones you're happy for the maintainer to see.
|
|
39
|
+
options:
|
|
40
|
+
- "No"
|
|
41
|
+
- "Yes"
|
|
42
|
+
validations:
|
|
43
|
+
required: true
|
|
44
|
+
- type: dropdown
|
|
45
|
+
id: where
|
|
46
|
+
attributes:
|
|
47
|
+
label: Where did you run golblick?
|
|
48
|
+
options:
|
|
49
|
+
- Command-line tool
|
|
50
|
+
- Nextcloud app
|
|
51
|
+
- Both
|
|
52
|
+
validations:
|
|
53
|
+
required: true
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
name: A video looks wrong or won't play
|
|
2
|
+
description: For the cameras golblick has been tested with (Insta360 OneR, X3 and X5)
|
|
3
|
+
title: "Video problem: "
|
|
4
|
+
labels: ["bug"]
|
|
5
|
+
body:
|
|
6
|
+
- type: markdown
|
|
7
|
+
attributes:
|
|
8
|
+
value: |
|
|
9
|
+
For a camera golblick hasn't been tested with, use the "Trying a camera golblick hasn't been tested with" form instead.
|
|
10
|
+
|
|
11
|
+
The report from golblick leaves out the file's name, its folder and the camera's serial number, so it's safe to paste here. Please don't attach the video itself unless you're happy for it to be public; a screenshot or a few seconds showing the problem is usually enough.
|
|
12
|
+
- type: input
|
|
13
|
+
id: camera
|
|
14
|
+
attributes:
|
|
15
|
+
label: Camera model and firmware
|
|
16
|
+
placeholder: Insta360 X3, v1.0.70
|
|
17
|
+
validations:
|
|
18
|
+
required: true
|
|
19
|
+
- type: textarea
|
|
20
|
+
id: report
|
|
21
|
+
attributes:
|
|
22
|
+
label: Report from golblick
|
|
23
|
+
description: From `golblick report <file>`, or "Report to golblick" in a `.insv` file's actions menu in Nextcloud Files. Both fill this in for you if you use the link they give. For a clip the camera saved as two files, report the one with `_00_` in its name.
|
|
24
|
+
render: text
|
|
25
|
+
validations:
|
|
26
|
+
required: true
|
|
27
|
+
- type: textarea
|
|
28
|
+
id: what
|
|
29
|
+
attributes:
|
|
30
|
+
label: What's wrong
|
|
31
|
+
description: What you did, what you expected and what you got. Say where it shows, such as where the two lenses meet, the horizon, the steadying (shaky, drifting, or snapping), or playback, and in which player (golblick's sphere player, Memories, or another app playing the stitched `.360.mp4` copy).
|
|
32
|
+
validations:
|
|
33
|
+
required: true
|
|
34
|
+
- type: dropdown
|
|
35
|
+
id: clips
|
|
36
|
+
attributes:
|
|
37
|
+
label: Can you share the original clip privately?
|
|
38
|
+
description: The original file helps most. **Don't attach it here or post a link to it**, because issues are public. If you choose yes, you'll get a private upload link in a reply. A video file carries the date and time, the camera's serial number and, if the camera recorded one, the location, and `golblick share` can't remove them from videos yet, so pick a clip you're happy for the maintainer to see.
|
|
39
|
+
options:
|
|
40
|
+
- "No"
|
|
41
|
+
- "Yes"
|
|
42
|
+
validations:
|
|
43
|
+
required: true
|
|
44
|
+
- type: dropdown
|
|
45
|
+
id: where
|
|
46
|
+
attributes:
|
|
47
|
+
label: Where did you run golblick?
|
|
48
|
+
options:
|
|
49
|
+
- Command-line tool
|
|
50
|
+
- Nextcloud app
|
|
51
|
+
- Both
|
|
52
|
+
validations:
|
|
53
|
+
required: true
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
python:
|
|
13
|
+
# Both ways: the core has to pass with numpy absent, and with numpy
|
|
14
|
+
# present a wrongly skipped test would be invisible.
|
|
15
|
+
name: Python ${{ matrix.python }}${{ matrix.extra && format(' + {0}', matrix.extra) || '' }}
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
strategy:
|
|
18
|
+
fail-fast: false
|
|
19
|
+
matrix:
|
|
20
|
+
python: ["3.10", "3.14"]
|
|
21
|
+
extra: ["", "render"]
|
|
22
|
+
steps:
|
|
23
|
+
- uses: actions/checkout@v7
|
|
24
|
+
- uses: astral-sh/setup-uv@v10.3.2
|
|
25
|
+
with:
|
|
26
|
+
python-version: ${{ matrix.python }}
|
|
27
|
+
- run: uv sync --group dev ${{ matrix.extra && format('--extra {0}', matrix.extra) || '' }}
|
|
28
|
+
- run: uv run --no-sync pytest -q
|
|
29
|
+
- run: uv run --no-sync ruff check src tests
|
|
30
|
+
|
|
31
|
+
nextcloud-app:
|
|
32
|
+
name: Nextcloud app
|
|
33
|
+
runs-on: ubuntu-latest
|
|
34
|
+
defaults:
|
|
35
|
+
run:
|
|
36
|
+
working-directory: nextcloud-app
|
|
37
|
+
steps:
|
|
38
|
+
- uses: actions/checkout@v7
|
|
39
|
+
- name: PHP lint
|
|
40
|
+
run: find lib -name '*.php' -print0 | xargs -0 -n1 php -l
|
|
41
|
+
- uses: actions/setup-node@v7
|
|
42
|
+
with:
|
|
43
|
+
node-version: 22
|
|
44
|
+
cache: npm
|
|
45
|
+
cache-dependency-path: nextcloud-app/package-lock.json
|
|
46
|
+
- run: npm ci
|
|
47
|
+
- run: npm run typecheck
|
|
48
|
+
- run: npm run build
|
|
49
|
+
- name: Built js/ matches the source
|
|
50
|
+
run: test -z "$(git status --porcelain -- js)" || { git status --short -- js; exit 1; }
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Publishing a GitHub release uploads the Python package to PyPI. PyPI trusts
|
|
4
|
+
# this workflow by name (a trusted publisher), so no token is stored anywhere.
|
|
5
|
+
on:
|
|
6
|
+
release:
|
|
7
|
+
types: [published]
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
build:
|
|
14
|
+
runs-on: ubuntu-latest
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v7
|
|
17
|
+
- uses: astral-sh/setup-uv@v10.3.2
|
|
18
|
+
- name: The tag names the version being built
|
|
19
|
+
run: |
|
|
20
|
+
version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
|
|
21
|
+
case "${GITHUB_REF_NAME#v}" in
|
|
22
|
+
"$version" | "$version"-*) ;;
|
|
23
|
+
*) echo "Tag $GITHUB_REF_NAME doesn't match version $version in pyproject.toml"; exit 1 ;;
|
|
24
|
+
esac
|
|
25
|
+
- name: Point the README's relative links at GitHub, for the PyPI page
|
|
26
|
+
run: |
|
|
27
|
+
python3 - "$GITHUB_REF_NAME" <<'EOF'
|
|
28
|
+
import pathlib, re, sys
|
|
29
|
+
tag = sys.argv[1]
|
|
30
|
+
repo = "https://github.com/AkshayRao27/golblick"
|
|
31
|
+
readme = pathlib.Path("README.md")
|
|
32
|
+
text = readme.read_text()
|
|
33
|
+
text = re.sub(r'src="(?!https?:)([^"]+)"', rf'src="https://raw.githubusercontent.com/AkshayRao27/golblick/{tag}/\1"', text)
|
|
34
|
+
text = re.sub(r"\]\((?!https?:|#|mailto:)([^)]+)\)", rf"]({repo}/blob/{tag}/\1)", text)
|
|
35
|
+
readme.write_text(text)
|
|
36
|
+
EOF
|
|
37
|
+
- run: uv build
|
|
38
|
+
- uses: actions/upload-artifact@v7
|
|
39
|
+
with:
|
|
40
|
+
name: dist
|
|
41
|
+
path: dist/
|
|
42
|
+
|
|
43
|
+
pypi:
|
|
44
|
+
needs: build
|
|
45
|
+
runs-on: ubuntu-latest
|
|
46
|
+
environment:
|
|
47
|
+
name: pypi
|
|
48
|
+
url: https://pypi.org/project/golblick/
|
|
49
|
+
permissions:
|
|
50
|
+
id-token: write
|
|
51
|
+
steps:
|
|
52
|
+
- uses: actions/download-artifact@v8
|
|
53
|
+
with:
|
|
54
|
+
name: dist
|
|
55
|
+
path: dist/
|
|
56
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
.venv/
|
|
4
|
+
dist/
|
|
5
|
+
build/
|
|
6
|
+
*.egg-info/
|
|
7
|
+
.pytest_cache/
|
|
8
|
+
|
|
9
|
+
# Never commit media: originals are large and are the user's own photographs.
|
|
10
|
+
*.insp
|
|
11
|
+
*.insv
|
|
12
|
+
*.lrv
|
|
13
|
+
*.thumb.jpg
|
|
14
|
+
|
|
15
|
+
# Agent working notes: private, own git repo (see .claude/README.md)
|
|
16
|
+
.claude/
|
|
17
|
+
/CLAUDE.md
|
golblick-0.8.1/AGENTS.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Notes for coding agents
|
|
2
|
+
|
|
3
|
+
This project was written almost entirely by LLM coding agents, and contributions made the same way are welcome. This file is the context an agent needs before changing anything. Humans may find [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/development.md](docs/development.md) more useful.
|
|
4
|
+
|
|
5
|
+
## What this is
|
|
6
|
+
|
|
7
|
+
A Python library and CLI that reads 360-camera container files on Linux (Insta360 `.insp`, `.insv`, `.lrv` so far), extracts what the camera stored, and projects the dual-fisheye pair into an equirectangular panorama with GPano metadata. `golblick open` shows a photo or plays a video in a Qt viewer window that projects the lenses on the GPU as it draws. `nextcloud-app/` is a separate PHP port that shows those files as panoramic previews in Nextcloud, with a browser-side sphere viewer; optionally it also stitches videos with ffmpeg and plays them steadied.
|
|
8
|
+
|
|
9
|
+
Read these first, in this order:
|
|
10
|
+
|
|
11
|
+
1. The vendor contract at the top of [`src/golblick/vendors/__init__.py`](src/golblick/vendors/__init__.py). Everything else follows from it.
|
|
12
|
+
2. [`docs/formats/insta360-agent-notes.md`](docs/formats/insta360-agent-notes.md), for what is known about the container, how each fact was measured, and which earlier conclusions were wrong.
|
|
13
|
+
3. [`nextcloud-app/AGENT-NOTES.md`](nextcloud-app/AGENT-NOTES.md), before touching the PHP app.
|
|
14
|
+
|
|
15
|
+
## Where things go
|
|
16
|
+
|
|
17
|
+
The docs are split by reader. Pages for people stay short and plain; the detail an agent needs lives in notes files. Keep each fact in one place and link to it rather than restating it.
|
|
18
|
+
|
|
19
|
+
| What | Where |
|
|
20
|
+
|---|---|
|
|
21
|
+
| Container layout, record ids, calibration, measurements and their method | `docs/formats/<vendor>-agent-notes.md` |
|
|
22
|
+
| The same, in a page a person will read to the end | `docs/formats/<vendor>.md` |
|
|
23
|
+
| What each check measures, for users | `docs/accuracy.md` |
|
|
24
|
+
| Every CLI command | `docs/usage.md` |
|
|
25
|
+
| Nextcloud app internals | `nextcloud-app/AGENT-NOTES.md` |
|
|
26
|
+
| The vendor contract | the docstring in `src/golblick/vendors/__init__.py` |
|
|
27
|
+
|
|
28
|
+
When a measurement overturns something in a notes file, record the correction next to it rather than quietly editing the old claim. Several sections of `insta360-agent-notes.md` exist because an earlier confident answer was wrong.
|
|
29
|
+
|
|
30
|
+
## Commands
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
uv sync --group dev && uv run pytest -q # without numpy
|
|
34
|
+
uv sync --group dev --extra render && uv run pytest -q # with the render extra
|
|
35
|
+
uv run ruff check src tests # lint
|
|
36
|
+
uv run golblick --help
|
|
37
|
+
find nextcloud-app/lib -name '*.php' -exec php -l {} \; # the PHP has no test suite; lint it
|
|
38
|
+
(cd nextcloud-app && npm ci && npm run typecheck && npm run build) # the sphere viewer; commit js/
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Run the tests both ways. The core must pass without numpy installed, and with numpy present a wrongly skipped test is invisible.
|
|
42
|
+
|
|
43
|
+
## Rules
|
|
44
|
+
|
|
45
|
+
- The library and CLI have no dependencies. numpy and Pillow are allowed only behind the `render` extra and PySide6 only behind the `desktop` extra, each imported only where it's needed, so every other command runs without them.
|
|
46
|
+
- Refuse rather than guess. Raise `FormatError` instead of returning a partial or inferred parse. A parser has to prove it understood the layout; the trailer reader's padding search is the model.
|
|
47
|
+
- Detect files by content, not extension. `triage` is the one intentional exception, and it is tested.
|
|
48
|
+
- Vendor-specific code lives in the vendor's module. Adding a vendor should need a new module and a `VENDORS` entry, nothing else.
|
|
49
|
+
- Do not name what has not been verified. Unconfirmed calibration models stay raw tuples. In `docs/formats/`, mark inferred claims as unverified and never upgrade one without a measurement.
|
|
50
|
+
- Per-camera values the file does not carry (field of view, lens correction) live in the vendor's lens profile, with how they were measured. The PHP app restates those tables; a test fails if they drift.
|
|
51
|
+
- A change to the projection goes into both `src/golblick/render.py` and `nextcloud-app/lib/Render/`, and the two outputs are compared on the same file afterwards.
|
|
52
|
+
- Never add real photos or videos, or camera serial numbers, to the repository, including in pasted `probe` output. Fixtures are synthesised in the tests.
|
|
53
|
+
- Never develop or test the Nextcloud app against an instance that holds someone's real photos. Use a throwaway one in Docker.
|
|
54
|
+
- Commit messages explain why: what was measured, what was rejected, what a decision costs. One line per paragraph, no hard wrapping, and nothing about the people or places in anyone's photos.
|
|
55
|
+
|
|
56
|
+
## Verification habits that earned their place
|
|
57
|
+
|
|
58
|
+
Each of these comes from a confident wrong answer in this project's history.
|
|
59
|
+
|
|
60
|
+
- A claim that something is absent needs the enumeration behind it. A failed HTTPS connection was once reported as "this domain serves no website"; it served one over HTTP.
|
|
61
|
+
- A claim that something is universal needs the whole corpus. Run the parser over every file available, not two, and sample across camera models, not just across files.
|
|
62
|
+
- Score against something the project did not produce: a camera's embedded stitch, or a vendor's exported panorama. A render scored only against itself proves self-consistency, and a wrong stitch can be self-consistent.
|
|
63
|
+
- State each metric's blind spot next to it, and when a number is being driven down, ask what the optimiser can do that the number does not measure.
|
|
64
|
+
- A symptom with a shape describes the defect. Print the two disagreeing things side by side before theorising; a sign error and a rotation look different in a table.
|
|
65
|
+
- A transformation that does almost nothing is probably not being applied. Make it huge and check it fires.
|
|
66
|
+
- Write the index sum out before coding a matrix convention. Rows-as-vectors (`rays @ R`) applies the transpose.
|
|
67
|
+
- Test fixtures should be lopsided. A symmetric test cannot catch an asymmetric error, and handedness is invisible to everything except text in the picture.
|
|
68
|
+
- When two implementations disagree, reproduce the second one's exact conditions in the first before looking for a bug in the port.
|
|
69
|
+
- Measuring the source is not testing the deployment. Nextcloud caches previews on the server and the browser caches them under a URL keyed on the file's etag, so a regenerated preview can sit behind an old one.
|
|
70
|
+
- Weight anything measured along the seam by area on the sphere. The seam passes through the poles, where equirectangular pixels crowd.
|
|
71
|
+
- When checking against a reference, put both sides through the same pipeline. A box filter on one side and Lanczos on the other was once measured as a regression in the thing under test.
|
|
72
|
+
- A metric validated on a large effect doesn't transfer to a fine ranking. Lens agreement separates a right projection from a wrong one well, and ranks scene texture, not seam quality.
|
|
73
|
+
- Self-consistency can't see an error both halves share. A lens-model error that moves both lenses alike leaves lens agreement unchanged; matching each lens against an outside reference, where it appears alone, is what found it.
|
|
74
|
+
- An estimator has to be able to decline, and the decline has to be reachable. Comparing an optimum against a feasible solution of the same problem never fires; a guard needs a margin and a floor, and a test that it can trigger.
|
|
75
|
+
- Ghosting is not blur, and a sharpness metric can't see it. The test that catches a 50/50 blend is painting one lens red and the other blue.
|
|
76
|
+
- A 2:1 image is not necessarily equirectangular. Two square fisheye cells side by side are also 2:1. Render it and look.
|
|
77
|
+
- "Not measured" is a valid answer. Say what was measured and what was assumed, separately, and decompose a number before reporting it (total tilt is mostly the known sensor mounting angle; the residual is what matters).
|
|
78
|
+
- A route that does less work cannot cost more. If it measures that way, the cause is outside the code, usually a cold cache.
|
|
79
|
+
- A claim about what a system stores is a claim about its write path. Follow the data to whatever filters it, and prefer testing it to reading it.
|
|
80
|
+
- A port inherits the original's I/O semantics, not just its arithmetic. Nextcloud's stream wrappers return one 8 KiB chunk per `fread`.
|
|
81
|
+
- Check a claim about code with a `grep` before writing it down, and check the reason a comment gives as well as the claim.
|
|
82
|
+
|
|
83
|
+
## Nextcloud traps
|
|
84
|
+
|
|
85
|
+
- Clear previews with `occ preview:cleanup`, never by deleting files: the `oc_previews` rows outlive them.
|
|
86
|
+
- After copying new PHP into a running container, run `apachectl graceful`. The official image sets `opcache.revalidate_freq=60`, and a newly registered middleware did nothing until Apache restarted.
|
|
87
|
+
- Check a setting on the instance you're testing before crediting a fix. Memories' per-user `high_res_cond: never` stops zoom loading the original at all, which makes a broken zoom look fixed.
|
|
88
|
+
- With `debug` set, Nextcloud drops the `?v=` cache-busting suffix from scripts, so a rebuilt script can stay cached in the browser indefinitely. Load the page in a headless browser to see what is actually served.
|
|
89
|
+
- `sudo -u www-data` strips the environment, so a `php.ini` that reads `memory_limit=${PHP_MEMORY_LIMIT}` silently falls back. Measure under the limit the code will run with.
|
|
90
|
+
- Running out of PHP memory is fatal, not catchable. Check dimensions before decoding, as `checkImageMemory()` does in core.
|
|
91
|
+
- Mapping a type is a promise about the bytes. Anything downstream that serves originals will now treat the file as that type.
|
|
92
|
+
- A standalone harness can't see the integration it was extracted from. Measure in isolation, then confirm on a running server.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Issues and pull requests are welcome. This is a hobby project that is almost entirely written by LLMs (see the disclaimer in the [README](README.md)), so I can't promise when, or whether, I'll get to something that doesn't affect the cameras I use. I'll most likely point my instance of Claude Code at new issues, and it will probably pick up reports with clear evidence first.
|
|
4
|
+
|
|
5
|
+
## Testing a camera I don't have
|
|
6
|
+
|
|
7
|
+
This is the most useful contribution right now. Everything has been tested on photos and videos from three cameras: the Insta360 OneR, X3 and X5. I can't test anything else, and other models may well store things differently: each of those three differs from the other two in some way the reader has to handle.
|
|
8
|
+
|
|
9
|
+
If you have a different 360 camera, please try this:
|
|
10
|
+
|
|
11
|
+
1. Install with rendering support. With Python 3.10 or newer and [uv](https://docs.astral.sh/uv/getting-started/installation/), run `uv tool install 'golblick[render]'`.
|
|
12
|
+
2. Run `golblick report <file>` on a few stills. It prints a summary that is safe to paste into an issue: it leaves out the file's name, its folder and the camera's serial number. If something fails, the report says where, and carries on. It also prints a link that opens the issue with the report filled in.
|
|
13
|
+
3. Run `golblick render <file> -o test.jpg` and look at the result in a 360 viewer, or as a flat image. Check that it is upright and not mirrored (text in the scene is the easiest tell), that horizons and straight lines continue across the seam where the two lenses meet, and what the *lens agreement* line says. Around +0.7 to +0.9 is a correct projection, and near +0.02 means the geometry is wrong.
|
|
14
|
+
4. If `golblick preview <file>` reports an equirectangular preview, your camera embeds its own stitch, and comparing the two is very helpful.
|
|
15
|
+
|
|
16
|
+
Then [open an untested-camera issue](https://github.com/AkshayRao27/golblick/issues/new?template=untested-camera.yml) with the reports and what you saw; the link `report` prints opens it already filled in. Please do this even if everything looks right.
|
|
17
|
+
|
|
18
|
+
The report shows whether golblick can read the camera's files. Supporting it properly (the lens's field of view and correction, and which way its motion sensor faces) is measured from a few original photos, so if you can, say in the issue that you can share some. You'll get a private upload link in a reply. Don't attach photos to the issue or post links to them: issues are public, and an original `.insp` holds where the photo was taken, when, and the camera's serial number. Run `golblick share <files>` first, which writes copies without those and changes nothing else. The pictures themselves are unchanged, so choose ones you're happy to send: outdoors with a level horizon and some text in view is ideal, because text is the easiest way to spot a mirrored render.
|
|
19
|
+
|
|
20
|
+
For a problem with a photo or a video from one of the three tested cameras, use the [photo problem](https://github.com/AkshayRao27/golblick/issues/new?template=photo-problem.yml) or [video problem](https://github.com/AkshayRao27/golblick/issues/new?template=video-problem.yml) form instead. `report` picks the right one for you.
|
|
21
|
+
|
|
22
|
+
`golblick probe -v` also prints the calibration values, which are specific to your camera body. They are very useful for working out how a new model stores its lenses, so share them if you're comfortable with that, but it's your call. `probe` prints the camera's serial number too, so delete that line before posting its output.
|
|
23
|
+
|
|
24
|
+
For videos, `golblick render` stitches a whole clip, steadied (it needs ffmpeg), and so does the [Nextcloud app](nextcloud-app/README.md#videos). `report` works on a video's `_00_` file too, and reports on videos are welcome.
|
|
25
|
+
|
|
26
|
+
## Code
|
|
27
|
+
|
|
28
|
+
[docs/development.md](docs/development.md) covers setup, running the tests (with and without the render extra, both are required), the layout and the conventions. In short:
|
|
29
|
+
|
|
30
|
+
- The library and CLI stay free of dependencies; rendering is the exception, behind the `render` extra.
|
|
31
|
+
- A reader refuses a file it can't prove it understood rather than guessing.
|
|
32
|
+
- No real photos, videos or serial numbers go into the repository. Test fixtures are synthesised.
|
|
33
|
+
- A change to the projection is made in both the Python library and the PHP Nextcloud app.
|
|
34
|
+
- Commit messages explain why, not just what. Write paragraphs as single lines.
|
|
35
|
+
|
|
36
|
+
LLM-assisted contributions are fine; this project is fully vibe-coded anyway. [AGENTS.md](AGENTS.md) is written for a coding agent, so point yours at it.
|
|
37
|
+
|
|
38
|
+
## Licence
|
|
39
|
+
|
|
40
|
+
By contributing, you agree that your contribution is licensed under AGPL-3.0-or-later, like the rest of the repository.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|