This repository contains tools for transforming a 360-degree panoramic image into planar images, allowing extraction of specific views from the panorama. The converter generates multiple planar images with specified yaw angles, multiple pitch angles, field of view, and resolution, providing a way to visualize different perspectives from a single panorama image.
This implementation is based on the Medium blog post by Coding Ballad: Unwrapping the View: Transforming 360° Panoramas into Intuitive Videos with Python
- Panorama to Plane Projection Converter
- Yaw and Pitch Angle Illustrations
- GUI
The Panorama to Plane Projection Converter is a tool designed to transform panoramic images into plane (rectilinear) projections. This conversion is essential for applications in virtual reality, gaming, photography, and more, where standard perspective views are required from a 360-degree panorama.
By adjusting parameters such as Field of View (FOV), multiple pitch and yaw angles, resolution, users can generate various perspective views from a single panoramic image, facilitating versatile usage across different platforms and mediums.
The converter transforms panoramic (spherical) images into plane (rectilinear) projections using mathematical transformations. Here's a high-level overview of the process:
-
Coordinate Mapping:
- The tool maps Cartesian coordinates from the output plane to spherical coordinates based on specified yaw and multiple pitch angles.
- Rotation matrices are applied to accurately adjust the view direction.
-
Color Interpolation:
- For each pixel in the output image, corresponding coordinates in the panorama are determined.
- Efficient interpolation ensures high-quality projections.
-
Parallel Processing:
- Utilizing optimized processing techniques, the tool processes multiple images, yaw angles, and pitch angles concurrently, significantly reducing processing time for large batches.
-
Output Generation:
- The projected images are saved with descriptive filenames indicating the applied parameters and resolution, facilitating easy identification and organization.
You can use the Panorama to Plane Projection Converter in two ways:
-
Option 1: Using the Compiled Executable
For users who prefer a straightforward approach without setting up a Python environment.
-
Option 2: Running the Python Script
For users who want to run the code directly or modify it.
We provide a compiled executable panorama_to_plane-pitch.exe
for Windows users, available in the latest GitHub release. This option allows you to use the converter without installing Python or any dependencies.
Steps to Use the Executable:
-
Download the Executable:
- Visit the latest release page and download
panorama_to_plane-pitch.exe
.
- Visit the latest release page and download
-
Prepare Your Images:
- Place your panoramic images in a folder, e.g.,
input_images
.
- Place your panoramic images in a folder, e.g.,
-
Open Command Prompt:
- Navigate to the directory containing
panorama_to_plane-pitch.exe
.
- Navigate to the directory containing
-
Run the Executable with Desired Options:
panorama_to_plane-pitch.exe --input_path <INPUT_PATH> [OPTIONS]
Replace
<INPUT_PATH>
with the path to your input images folder, and include any optional arguments as needed.
Example Command:
panorama_to_plane-pitch.exe --input_path ./input_images --output_path ./output_images --FOV 120 --output_width 1920 --output_height 1080 --pitch_angles 30 60 90 --yaw_angles 0 90 180 270
Notes:
- Ensure that you have the necessary permissions to execute the file.
- The executable supports the same command-line arguments as the Python script.
Adding the Executable to Windows PATH (Optional):
To run panorama_to_plane-pitch.exe
from any directory in the terminal, you can add its folder to the Windows system PATH.
- Locate the Folder containing
panorama_to_plane-pitch.exe
. - Copy the Path:
- Right-click the folder, then select Properties. Copy the folder path shown in the Location field.
- Edit System Environment Variables:
- Open the Start Menu, search for "Environment Variables", and select Edit the system environment variables.
- Update the PATH:
- In the System Properties window, click on Environment Variables.
- In the System variables section, scroll down and select Path, then click Edit.
- Click New, paste the folder path, and click OK to save.
- Verify:
- Open a new command prompt and type
panorama_to_plane-pitch.exe
. If it runs, you've successfully added it to PATH.
- Open a new command prompt and type
This option is for users who want to run the script directly or make modifications.
- Python Version: Python 3.7 or higher is required.
- Operating System: Cross-platform (Windows, macOS, Linux).
-
Clone the Repository
git clone https://github.com/Maxiviper117/360-to-planer-images.git cd 360-to-planer-images
-
Create a Virtual Environment (Recommended)
Creating a virtual environment ensures that project dependencies are isolated.
python -m venv venv
Activate the virtual environment:
-
On Windows:
venv\Scripts\activate
-
On macOS and Linux:
source venv/bin/activate
-
-
Install Dependencies
Install the required Python libraries using
pip
:pip install -r requirements.txt
If a
requirements.txt
file is not provided, install dependencies individually:pip install pillow numpy scipy opencv-python tqdm
The script is executed via the command line using app/panorama_to_plane-pitch.py
. It supports both single and batch processing of panoramic images with multiple pitch and yaw angles.
Use the following command:
python app/panorama_to_plane-pitch.py --input_path <INPUT_PATH> [OPTIONS]
Replace <INPUT_PATH>
with the path to your input images folder, and include any optional arguments as needed.
These arguments are used for both app/panorama_to_plane-pitch.py
and the compiled panorama_to_plane-pitch.exe
(Option 1 and Option 2).
--input_path
:- Description: Path to the directory containing input panorama images or a single panorama image.
- Type:
str
- Example:
--input_path ./input_images
-
--output_path
:- Description: Directory to save the output plane-projected images.
- Type:
str
- Default:
output_images
- Example:
--output_path ./output_images
-
--output_format
:- Description: Format of the output images.
- Choices:
png
,jpg
,jpeg
- Default:
png
- Example:
--output_format png
-
--FOV
:- Description: Field of View in degrees.
- Type:
int
- Default:
90
- Example:
--FOV 120
-
--output_width
:- Description: Width of the output image in pixels.
- Type:
int
- Default:
800
- Example:
--output_width 1920
-
--output_height
:- Description: Height of the output image in pixels.
- Type:
int
- Default:
800
- Example:
--output_height 1080
-
--pitch_angles
:- Description: List of pitch angles in degrees (1-179).
- Type:
int
(list) - Default:
30 60 90 120 150
- Example:
--pitch_angles 30 60 90
-
--yaw_angles
:- Description: List of yaw angles in degrees (0-360).
- Type:
int
(list) - Default:
0 90 180 270
- Example:
--yaw_angles 0 90 180 270
-
--num_workers
:- Description: Number of worker threads for parallel yaw processing. If not specified, uses ~90% of CPU cores.
- Type:
int
- Default:
~90% of CPU cores
- Example:
--num_workers 4
-
--enable_file_logging
:- Description: Enable logging to a file.
- Type:
flag
- Default: Disabled
- Example:
--enable_file_logging
-
Basic Usage:
Convert all panorama images in
input_images
with default settings.python app/panorama_to_plane-pitch.py --input_path ./input_images
-
Specify Output Directory and Format:
Save output images in
converted_images
directory withpng
format.python app/panorama_to_plane-pitch.py --input_path ./input_images --output_path ./converted_images --output_format png
-
Customize FOV, Output Size, Multiple Pitch and Yaw Angles:
Convert images with a 120-degree FOV, output size of 1920x1080 pixels, pitch angles at 30, 60, and 90 degrees, and yaw angles at 0, 90, 180, and 270 degrees.
python app/panorama_to_plane-pitch.py --input_path ./input_images --FOV 120 --output_width 1920 --output_height 1080 --pitch_angles 30 60 90 --yaw_angles 0 90 180 270
-
Enable File Logging:
python app/panorama_to_plane-pitch.py --input_path ./input_images --enable_file_logging
-
Basic Usage:
panorama_to_plane-pitch.exe --input_path ./input_images
-
Specify Output Directory and Format:
panorama_to_plane-pitch.exe --input_path ./input_images --output_path ./converted_images --output_format png
-
Complete Example with Multiple Yaw and Pitch Angles:
panorama_to_plane-pitch.exe --input_path ./input_images --output_path ./output_images --output_format jpg --FOV 100 --output_width 1280 --output_height 720 --pitch_angles 30 60 90 120 150 --yaw_angles 0 45 90 135 180 225 270 315
Note: Use backslash (\
) for line continuation in Linux/macOS. For Windows Command Prompt, write the command in a single line.
Each output image will be named following this pattern:
<original_filename>_<output_width>x<output_height>_yaw_<yaw>_pitch_<pitch>.<format>
Example:
For an input file named panorama1.jpg
with an output resolution of 1920x1080
, yaw of 90
, pitch of 60
, and output format jpg
, the output file will be:
panorama1_1920x1080_yaw_90_pitch_60.jpg
This naming convention helps in identifying the projection parameters and resolution used for each output image.
-
Executable Won't Run
Error Message:
This app can't run on your PC.
Solution:
- Ensure that you're running the executable on a compatible Windows system (e.g., 64-bit Windows 10 or higher).
- If you have antivirus software, it might block the executable; check your antivirus logs and whitelist the app if necessary.
-
Module Not Found Error (Python Script)
Error Message:
ModuleNotFoundError: No module named 'cv2'
Solution:
Ensure all dependencies are installed within your virtual environment.
pip install opencv-python
-
Permission Denied Error
Error Message:
PermissionError: [Errno 13] Permission denied: 'output_images'
Solution:
- Verify that you have write permissions for the output directory.
- If the directory exists, ensure it's not read-only.
- Run the terminal or command prompt with appropriate permissions.
-
No Images Found Warning
Warning Message:
[WARNING] No images found in ./input_images with extensions ['*.jpg', '*.jpeg', '*.png'].
Solution:
- Check that the
input_images
directory contains images with supported extensions. - Ensure that the path provided to
--input_path
is correct. - Verify that file extensions are in lowercase or adjust the script to handle case-insensitive extensions.
- Check that the
-
High Memory Usage or Slow Performance
Potential Causes:
- Processing very large images.
- Running too many parallel processes.
Solutions:
- Reduce the
output_width
andoutput_height
to lower values. - Limit the number of parallel workers by adjusting the
--num_workers
parameter. - Ensure that your system has sufficient RAM and CPU resources.
-
Output Images Are Blank or Incorrectly Mapped
Potential Causes:
- Incorrect yaw or pitch values.
- Issues in coordinate transformations.
Solutions:
- Double-check the yaw and pitch values for correctness.
- Review the rotation matrix implementation if you're modifying the code.
- Test the tool with a single image and known parameters to isolate issues.
-
Invalid Pitch Angle Error
Error Message:
argparse.ArgumentTypeError: Pitch angle must be between 1 and 179 degrees, got 0.
Solution:
- Ensure that all pitch angles provided are within the valid range (1-179 degrees).
- Adjust your command to exclude invalid pitch angles.
This project is licensed under the MIT License. See the LICENSE file for details.