G21-2024

> h2. [[Team Members]] | [[Meeting Documentation]] | [[The Wiki]] | [[User Manual]] | [[Functional & Non-Functional Requirements]] | [[Math Document]] | [[UML Diagrams]] | [[Results]]

h1. Project Setup Guide

------------------------------------------------------------

h1. 1. Setting Up the Project

h2. Prerequisites

*Operating System:*

* Recommended: Mac OS.

* The code should generally run on Windows or Linux as well, provided Python 3.x is installed.

*Python Version:*

* You need Python 3.x (e.g., 3.8 or newer).

*Dependencies:*

* NumPy (version 2.2.0)

* OpenCV-Python (version 4.10.0.84)

* Python-Dotenv (version 1.0.1)

* You can install them via:

<pre>

pip install numpy==2.2.0 opencv-python==4.10.0.84 python-dotenv==1.0.1

</pre>

h2. Project Folder Structure

A typical folder layout:

<pre>

.

├── run.sh

├── main.py

├── image_configuration.py

├── image.py

├── image_configuration.env

└── lib/

    └── ...

</pre>

* *main.py:* The main entry point; orchestrates loading configs, applying masks, and displaying the image.

* *image_configuration.py:* Retrieves environment variables (e.g., file paths, projector distances).

* *image.py:* Reads the image and applies the overlap mask.

* *image_configuration.env:* Stores environment variables (SIDE, DISTANCE_BETWEEN_PROJECTOR_CM, etc.).

* *run.sh:* Shell script to run the project (optional but convenient).

h1. 2. Step-by-Step Installation & Configuration

h2. Clone or Download the Repository

# Clone the repository (if using Git):

<pre>

git clone https://github.com/your-username/your-project.git

</pre>

Or download the project folder from your source (ZIP download, etc.) and unzip it locally.

# Navigate into the project directory:

<pre>

cd your-project

</pre>

h2. Install Dependencies

Ensure Python 3.x is available, then install the required libraries:

<pre>

pip install numpy==2.2.0 opencv-python==4.10.0.84 python-dotenv==1.0.1

</pre>

(If you have a virtual environment, make sure it’s activated before installing.)

h2. Prepare the Configuration File

# Locate or create the file named image_configuration.env.

# Set the following environment variables:

<pre>

SIDE=left

IMAGE_FILE_PATH=/path/to/your/image.jpg

DISTANCE_BETWEEN_PROJECTOR_CM=100

PROJECTION_WIDTH_CM=200

# SIDE: which side of the image you are projecting (left or right).

# IMAGE_FILE_PATH: path to the .jpeg or .png image.

# DISTANCE_BETWEEN_PROJECTOR_CM: distance between your two projectors, in centimeters (x).

# PROJECTION_WIDTH_CM: total width of the final projection, in centimeters (y).

</pre>

# Save the file in the same directory as main.py.

h2. Make the Shell Script Executable (Optional)

If you intend to use the provided run.sh script:

<pre>

chmod +x run.sh

</pre>

h1. 3. Accessing Required Resources

* Repositories:

# Ensure you have access to the main Git repository (or the code you’ve downloaded).

# If there are any submodules or additional repos, update/clone them as documented.

* APIs:

# This project does not use external APIs by default. If you integrate external APIs (e.g., for image storage or retrieval), ensure you have valid credentials/config.

* Libraries:

# The only libraries required are already listed in Dependencies.

# If your environment blocks direct internet access, you may need to manually download .whl files or source distributions for NumPy, OpenCV, and python-dotenv, then install them.

h1. 4. Running the Project

You can run the project two ways:

h2. Via run.sh

# Make sure run.sh is executable.

# In a terminal, run:

<pre>

./run.sh

</pre>

# The script will call main.py, load the configuration, apply the mask, and display the image.

h2. Directly with Python

# In a terminal, run:

<pre>

python main.py

</pre>

# This directly executes the main file and does the same steps.

When launched, an OpenCV window will appear displaying your processed (masked) image. Press any key in the OpenCV window to close it.

h1. 5. Common Troubleshooting Steps

* Black/Blank Image

# Check that IMAGE_FILE_PATH in image_configuration.env is correct.

# Verify that the image is a valid .jpg or .png.

* Overlap Not Visible or Inverted

# Confirm that DISTANCE_BETWEEN_PROJECTOR_CM < PROJECTION_WIDTH_CM.

# Verify you have the correct SIDE set. For instance, if you’re physically on the right side but your .env says SIDE=left, the overlap may look reversed.

* Import Errors

# “No module named X”: check you installed all the required libraries:

<pre>

pip install numpy==2.2.0 opencv-python==4.10.0.84 python-dotenv==1.0.1

</pre>

# Confirm you’re using Python 3.x (type python --version or python3 --version).

* Permission Denied on run.sh

# Run chmod +x run.sh and then re-run ./run.sh.

* Env File Not Found

# Ensure image_configuration.env is in the same directory as your Python scripts.

# Make sure you are loading the correct file path in ImageConfiguration("image_configuration.env").

h1. 6. Frequently Asked Questions (FAQ)

* Does this only work on Mac OS?

# While tested on Mac OS, it should run on Windows or Linux if you can install the same Python dependencies.

* Can I project a video instead of an image?

# Currently, it’s set up for static images. You could adapt the code with OpenCV’s video capture methods, but that requires more advanced masking.

* Why does the overlap region look washed out or darker?

# The code applies a simple exponential fade (**0.4) for blending. If you want a different blending curve, adjust the exponent or other interpolation logic in Image.mask().

* What if I have more than two projectors?

# The logic would need to be expanded to handle multiple overlap regions, which is beyond this project’s current scope.