Skip to main content

VR180 image converter

CI Status Documentation Status Test coverage percentage

uv Ruff prek

PyPI Version Supported Python versions License


Documentation: https://vr180-convert.readthedocs.io

Source Code: https://github.com/34j/vr180-convert


Simple VR180 image converter on top of OpenCV and NumPy.

Installation

Install this via pip (or your favourite package manager):

pipx install vr180-convert

Usage

Simply run the following command to convert 2 fisheye images to a SBS equirectangular VR180 image:

v1c lr left.jpg right.jpg
left.jpg right.jpg Output
left right output

If left and right image paths are the same, the image is divided into two halves (left and right, SBS) and processed as if they were separate images.

Advanced usage

If one of left or right image path is a directory, the program will search for the closest image (in terms of creation time) in the other directory.

v1c lr left.jpg right_dir
v1c lr left_dir right.jpg

Since clocks on cameras may not be very accurate in some cases, it is recommended to check how quickly the clocks of the two cameras shift, and synchronize the clocks before shooting. However, it can be adjusted by specifying --time-calib option.

v1c lr left.jpg right_dir --time-calib 1 # the clock of the right camera is 1 second faster / ahead
v1c lr left_dir right.jpg --time-calib 1 # the clock of the right camera is 1 second faster / ahead

Radius estimation

The radius of the non-black area of the input image is assumed by counting black pixels by default, but it would be better to specify it manually to get stable results:

v1c lr left.jpg right.jpg --radius 1000
v1c lr left.jpg right.jpg --radius max # min(width, height) / 2

Calibration

Rotation matching using the least-squares method can be performed by clicking corresponding points that can be regarded as infinitely far away from the camera.

  • Using AKAZE as a feature matcher:
v1c lr left.jpg right.jpg --automatch fm

Since matching by AKAZE involves false detections, matching points with high loss are considered outliers, and the least-squares method is repeated multiple times to remove them. Checking if the image should be swapped using feature matching might be theoretically possible but not implemented.

See Also

v1c lr left.jpg right.jpg --automatch gui
  • Manually specifying the corresponding points using the CLI:
v1c lr left.jpg right.jpg --automatch "0,0;0,0;1,1;1,1" # left_x1,left_y1;right_x1,right_y1;...

$$ a_k, b_k \in \mathbb{R}^3, \min_{R \in SO(3)} \sum_k |R a_k - b_k|^2 $$

Please also refer to the Documentation for mathematical details.

Anaglyph

--merge option (which exports as anaglyph image) can be used to check if the calibration is successful by checking if the infinitely far points are overlapped.

v1c lr left.jpg right.jpg --automatch gui --merge

Swap

If the camera is mounted upside down, you can simply use the --swap option without changing the transformer or other parameters:

v1c lr left.jpg right.jpg --swap

Or the image can be simply swapped using the swap command:

v1c swap rl.jpg

in case one notices that the left and right images are swapped after the conversion.

Saving match visualization

When using --automatch fm, the match visualization can be saved by specifying --savematch. The match image is saved alongside the output with a .match suffix.

v1c lr left.jpg right.jpg --automatch fm --savematch

Custom conversion model

You can also specify the conversion model by adding Python code directly to the --transformer option:

v1c lr left.jpg right.jpg --transformer 'EquirectangularEncoder() * Euclidean3DRotator(from_rotation_vector([0, np.pi / 4, 0])) * FisheyeDecoder("equidistant")'

The expression is evaluated and used as the remapper chain, overriding the default pipeline. Please refer to the API documentation for the available transformers and their parameters. For from_rotation_vector, please refer to the numpy-quaternion documentation.

Single image conversion

To convert a single image, use v1c s instead.

Running commands for all images in a directory

find left_dir -type f -name '*.jpg' -exec v1c lr {} right_dir --automatch fm --radius max --time-calib 0 --out-path out \;

Help

For more information, please refer to the help or API documentation:

v1c --help

Usage as a library

For more complex transformations, it is recommended to create your own Remapper.

Note that the transformation is applied in inverse order (new[(x, y)] = old[transform(x, y)], e.g. to decode orthographic fisheye images, transform_polar should be arcsin(theta), not sin(theta).)

from typing import Any

from array_api.latest import Array
from vr180_convert.remapper.polar_roll import PolarRollRemapper
from vr180_convert.remapper.equidistant import EquirectangularEncoder
from vr180_convert.remapper.fisheye import FisheyeDecoder


class MyRemapper(PolarRollRemapper):
    def transform_polar(
        self, theta: Array, roll: Array, **kwargs: Any
    ) -> tuple[Array, Array]:
        return theta**0.98 + theta**1.01, roll


transformer = EquirectangularEncoder() * MyRemapper() * FisheyeDecoder("equidistant")

Tips

How to determine which image is left or right

Left Right
Subject Orientation Right Left
Film Color ${\color{red}\text{Red}}$ ${\color{blue}\text{Blue}}$
Anaglyph Color ${\color{blue}\text{Blue}}$ ${\color{red}\text{Red}}$
  • In a SBS image, the subject is oriented toward the center.

How to edit images

This program cannot read RAW files. To deal with white-outs, etc., it is required to process each image with a program such as Photoshop, Lightroom, RawTherapee, Darktable, etc.

However, this is so exhaustive, so it is recommended to take the images with JPEG format with care to avoid overexposure and to match the settings of the two cameras, then convert them with this program and edit the converted images.

Example of editing in RawTherapee (Light editing)
  1. Rank the left images in RawTherapee.
  2. Use this program to convert the images.
  3. Edit the converted images in RawTherapee.
Example of editing in Photoshop (Exquisite editing)
  1. Rank the left images in RawTherapee or Lightroom.
  2. Open left image as a Smart Object LRaw.
  3. Add right image as a Smart Object RRaw.
  4. Make minimal corrections just to match the exposure using Camera Raw Filter.
  5. Make each Smart Object into Smart Objects (L, R) again and do any image-dependent processing, such as removing the background.
  6. Make both images into a single Smart Object (P) and process them as a whole.
  7. Export as a PNG file.
  8. Hide the other Smart Object (L or R) (created in step 3) in the Smart Object P (created in step 4) and save the Smart Object P, then export as a PNG file.
  9. Use this program to convert the images.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Credits

Copier

This package was created with Copier and the browniebroke/pypackage-template project template.

Metadata

Release files for vr180-convert 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vr180-convert 1.0.0
File Size Uploaded Provenance Actions
vr180_convert-1.0.0.tar.gz 29.9 kB With provenance Details for vr180_convert-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vr180-convert 1.0.0
File Interpreter ABI Platform Actions
vr180_convert-1.0.0-py3-none-any.whl Python 3 none any Details for vr180_convert-1.0.0-py3-none-any.whl

Total release size: 61.7 kB

Release files / vr180_convert-1.0.0.tar.gz

Download URL vr180_convert-1.0.0.tar.gz
Size 29.9 kB
Tags Source
SHA-256 checksum
How to use checksums
dccf43ab555371aeebaef386a1b1baee5fdb4a0dbcc21c7edf4a4cfa66ec6f69
BLAKE2b-256 checksum
How to use checksums
72345654ae57b04d18586641bb0dfd67aaa7ad519d52bad96e695d907bafdc47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / vr180_convert-1.0.0-py3-none-any.whl

Download URL vr180_convert-1.0.0-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
01a214b06be62fb6681c7280931ed09a45cc83a8a53ff9f493ccc2452231dae8
BLAKE2b-256 checksum
How to use checksums
99b77bd7bc93765d3dd9e415cf98704a8560a5032ddd0bdb3384420b7a47e85f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for vr180-convert 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vr180_convert-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page