Merge pull request #2 from cjgaspari/copilot/add-detailed-setup-guide

detailed-setup.md

@@ -0,0 +1,479 @@
+# Detailed Setup Guide for SHARP - Beginner's Edition
+
+Welcome! This guide will walk you through setting up the SHARP 3D Prediction project on your computer, step by step. Don't worry if you're new to programming or command-line tools—we'll explain everything you need to know.
+
+## What is SHARP?
+
+SHARP is a tool that can take a single photograph and create a 3D representation of it, allowing you to view it from different angles. This project includes a user-friendly web interface where you can upload images and download the 3D results.
+
+## Table of Contents
+
+1. [Prerequisites - What You Need](#prerequisites---what-you-need)
+2. [Step 1: Install Conda](#step-1-install-conda)
+3. [Step 2: Download the Project](#step-2-download-the-project)
+4. [Step 3: Set Up the Project](#step-3-set-up-the-project)
+5. [Step 4: Start the Web Interface](#step-4-start-the-web-interface)
+6. [Troubleshooting](#troubleshooting)
+7. [Alternative Setup Methods](#alternative-setup-methods)
+
+---
+
+## Prerequisites - What You Need
+
+Before we begin, here's what you'll need:
+
+### Hardware Requirements
+- A computer running **macOS** (for Windows or Linux, see [Alternative Setup Methods](#alternative-setup-methods))
+- At least **8 GB of RAM** (16 GB or more recommended)
+- At least **5 GB of free disk space**
+- **Internet connection** for downloading software and dependencies
+
+### What You Don't Need
+- You don't need to know how to code
+- You don't need prior experience with Python or machine learning
+- You don't need to understand how the AI works (but you can learn if you want!)
+
+---
+
+## Step 1: Install Conda
+
+Conda is a package manager that helps organize Python and its libraries. Think of it as an app store for Python tools.
+
+### What is Conda?
+
+Conda creates isolated "environments" for different projects, so they don't interfere with each other. We'll use it to install Python and all the tools SHARP needs.
+
+### Download and Install Miniconda
+
+1. **Go to the Miniconda download page:**
+   - Open your web browser and visit: https://docs.conda.io/en/latest/miniconda.html
+
+2. **Download the macOS installer:**
+   - Look for the **macOS** section
+   - Download the **latest Python 3.x** installer for your Mac:
+     - If you have an **M1/M2/M3 Mac** (Apple Silicon): Choose the `Apple M1` or `arm64` version
+     - If you have an **Intel Mac**: Choose the `Intel x86_64` version
+   - The file will be named something like `Miniconda3-latest-MacOSX-arm64.pkg` or `Miniconda3-latest-MacOSX-x86_64.pkg`
+
+3. **Install Miniconda:**
+   - Double-click the downloaded `.pkg` file
+   - Follow the installation wizard:
+     - Click "Continue" through the introduction screens
+     - Accept the license agreement
+     - Choose "Install for me only" (recommended)
+     - Click "Install" and enter your password when prompted
+   - When installation completes, click "Close"
+
+4. **Verify the installation:**
+   - Open **Terminal** (you can find it in Applications → Utilities → Terminal)
+   - Type the following command and press Enter:
+     ```bash
+     conda --version
+     ```
+   - You should see something like `conda X.X.X` (the exact version number may vary)
+   - **If you get an error** saying "conda: command not found":
+     - Close Terminal completely and open it again
+     - Try the command again
+     - If it still doesn't work, see [Troubleshooting](#troubleshooting)
+
+---
+
+## Step 2: Download the Project
+
+Now we need to download the SHARP project files to your computer.
+
+### Option A: Download via GitHub (Easiest for Beginners)
+
+1. **Go to the GitHub repository:**
+   - Visit the repository URL where this project is hosted (check the address bar or the project README for the correct URL)
+
+2. **Download the ZIP file:**
+   - Click the green **"Code"** button
+   - Click **"Download ZIP"**
+   - The file will be saved to your Downloads folder
+
+3. **Extract the ZIP file:**
+   - Go to your Downloads folder
+   - Double-click the `ml-sharp-main.zip` (or similar name) file
+   - macOS will automatically extract the folder
+
+4. **Move to a convenient location (optional but recommended):**
+   - Create a folder in your Documents called `Projects`
+   - Drag the extracted `ml-sharp-main` folder into `Projects`
+   - Rename it to just `ml-sharp` to make it simpler
+
+### Option B: Using Git (If You Have It Installed)
+
+If you're comfortable with Git or have it installed:
+
+```bash
+cd ~/Documents
+git clone <repository-url>
+cd ml-sharp
+```
+
+(Replace `<repository-url>` with the actual Git URL from the GitHub repository)
+
+---
+
+## Step 3: Set Up the Project
+
+Now we'll set up the Python environment and install all the required libraries.
+
+### Using Terminal
+
+1. **Open Terminal** (Applications → Utilities → Terminal)
+
+2. **Navigate to the project folder:**
+   - Type `cd` followed by a space
+   - Drag the `ml-sharp` folder from Finder onto the Terminal window
+   - Press Enter
+   - Your command should look something like: `cd /Users/YourName/Documents/Projects/ml-sharp`
+
+3. **Initialize conda in your terminal:**
+   ```bash
+   conda init bash
+   ```
+   - Close Terminal and open it again
+
+4. **Create the Python environment:**
+   ```bash
+   conda create -n sharp python=3.13 -y
+   ```
+   - This creates a special environment named "sharp" with Python 3.13
+   - The process may take a few minutes
+   - Wait for it to complete
+
+5. **Activate the environment:**
+   ```bash
+   conda activate sharp
+   ```
+   - You should see `(sharp)` appear at the beginning of your command prompt
+
+6. **Install the main project dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+   - This installs all the machine learning libraries SHARP needs
+   - **This will take 5-15 minutes** depending on your internet speed
+   - You'll see a lot of text scrolling by—this is normal
+   - Be patient and let it finish
+
+7. **Install the web interface dependencies:**
+   ```bash
+   pip install -r src/sharp/web/requirements.txt
+   ```
+   - This installs the web server components
+   - This should be faster, taking about 1-2 minutes
+
+8. **Verify the installation:**
+   ```bash
+   sharp --help
+   ```
+   - If successful, you'll see the SHARP help menu
+   - This means everything is installed correctly!
+
+---
+
+## Step 4: Start the Web Interface
+
+Now for the exciting part—starting the web interface!
+
+### If start.command Works (Try This First)
+
+1. **In Finder, navigate to the ml-sharp folder**
+
+2. **Double-click the `start.command` file**
+
+3. **If macOS blocks it with a security warning:**
+   - Right-click (or Control-click) on `start.command`
+   - Select **"Open"** from the menu
+   - Click **"Open"** in the dialog that appears
+   - macOS will remember your choice for this file
+   
+   OR
+   
+   - Go to **System Settings → Privacy & Security**
+   - Scroll down to find a message about `start.command` being blocked
+   - Click **"Open Anyway"**
+   - Right-click on `start.command` again and choose **"Open"**
+
+4. **A Terminal window will open** with the SHARP logo
+
+5. **The script will automatically:**
+   - Check your conda installation
+   - Create or activate the environment
+   - Install any missing dependencies
+   - Start the web server
+
+6. **When you see "Starting Sharp Web Interface":**
+   - Open your web browser (Safari, Chrome, Firefox, etc.)
+   - Go to: **http://localhost:8000**
+   - You should see the SHARP web interface!
+
+### If start.command Doesn't Work (Manual Method)
+
+If the automatic script doesn't work, don't worry! Here's how to start it manually:
+
+1. **Open Terminal**
+
+2. **Navigate to the project folder:**
+   ```bash
+   cd /path/to/ml-sharp
+   ```
+   (Replace with your actual path, or drag the folder onto Terminal)
+
+3. **Activate the conda environment:**
+   ```bash
+   conda activate sharp
+   ```
+
+4. **Start the web server:**
+   ```bash
+   python src/sharp/web/app.py
+   ```
+
+5. **Open your web browser and go to:**
+   - **http://localhost:8000**
+
+6. **To stop the server:**
+   - Press **Control + C** in the Terminal window
+
+---
+
+## Troubleshooting
+
+### "conda: command not found"
+
+**Problem:** Terminal doesn't recognize the `conda` command.
+
+**Solutions:**
+
+1. **Initialize conda:**
+   ```bash
+   ~/miniconda3/bin/conda init bash
+   ```
+   Then close and reopen Terminal.
+
+2. **Add conda to your PATH manually:**
+   ```bash
+   echo 'export PATH="$HOME/miniconda3/bin:$PATH"' >> ~/.bash_profile
+   source ~/.bash_profile
+   ```
+
+3. **If you installed Anaconda instead of Miniconda:**
+   ```bash
+   echo 'export PATH="$HOME/anaconda3/bin:$PATH"' >> ~/.bash_profile
+   source ~/.bash_profile
+   ```
+
+### "Permission denied" when running start.command
+
+**Problem:** The script doesn't have permission to run.
+
+**Solution:**
+
+1. Open Terminal
+2. Navigate to the project folder
+3. Make the script executable:
+   ```bash
+   chmod +x start.command
+   ```
+4. Try double-clicking it again
+
+### "Failed to create conda environment"
+
+**Problem:** Error creating the Python environment.
+
+**Solutions:**
+
+1. **Make sure you have enough disk space** (at least 5 GB free)
+
+2. **Update conda:**
+   ```bash
+   conda update conda
+   ```
+
+3. **Try creating the environment with a different Python version:**
+   ```bash
+   conda create -n sharp python=3.11 -y
+   ```
+
+### Installation is Taking Forever / Stuck
+
+**Problem:** `pip install` seems frozen or very slow.
+
+**Solutions:**
+
+1. **Be patient:** The first installation can take 10-20 minutes, especially for PyTorch
+2. **Check your internet connection**
+3. **If truly stuck (no progress for 30+ minutes):**
+   - Press Control + C to cancel
+   - Try again:
+     ```bash
+     pip install -r requirements.txt --no-cache-dir
+     ```
+
+### "Port 8000 is already in use"
+
+**Problem:** Another application is using port 8000.
+
+**Solution:**
+
+1. **Find and stop the process using port 8000:**
+   ```bash
+   lsof -ti:8000 | xargs kill -9
+   ```
+
+2. **Or modify the port in the app.py file:**
+   - Open `src/sharp/web/app.py` in a text editor
+   - Look for the line near the end: `uvicorn.run(app, host="0.0.0.0", port=8000)`
+     (Tip: Search for `port=` to find it quickly)
+   - Change `port=8000` to `port=8080` (or another available port number)
+   - Save the file and start the server again
+   - Then access it at: http://localhost:8080 (or your chosen port)
+
+### The Web Interface Won't Load
+
+**Problem:** Browser shows an error when accessing http://localhost:8000
+
+**Solutions:**
+
+1. **Make sure the server is actually running** (check Terminal for errors)
+2. **Try a different browser**
+3. **Clear your browser cache**
+4. **Check if you're using the correct URL:** http://localhost:8000 (not https)
+5. **Look for error messages in the Terminal** and search for them online or see below
+
+### "ModuleNotFoundError: No module named 'sharp'"
+
+**Problem:** Python can't find the SHARP module.
+
+**Solution:**
+
+1. Make sure you're in the correct directory
+2. Make sure the conda environment is activated (you should see `(sharp)` in the prompt)
+3. Try installing again:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Out of Memory Errors
+
+**Problem:** Your computer runs out of RAM.
+
+**Solutions:**
+
+1. **Close other applications** to free up memory
+2. **Restart your computer** and try again
+3. **Consider using the CLI** instead of the web interface for large batches of images
+
+---
+
+## Alternative Setup Methods
+
+### For Windows Users
+
+The `start.command` script is macOS-specific, but you can follow these steps on Windows:
+
+1. **Install Miniconda for Windows:**
+   - Download from: https://docs.conda.io/en/latest/miniconda.html
+   - Choose the Windows installer
+
+2. **Open Anaconda Prompt** (search for it in the Start menu)
+
+3. **Follow steps 3 and 4** from above, using the same commands
+
+### For Linux Users
+
+The setup is very similar to macOS:
+
+1. **Install Miniconda for Linux:**
+   ```bash
+   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
+   bash Miniconda3-latest-Linux-x86_64.sh
+   ```
+
+2. **Follow the macOS instructions** using Terminal
+
+### Using the Command Line Interface (CLI)
+
+If you prefer not to use the web interface, you can use SHARP directly from the command line:
+
+1. **Activate the environment:**
+   ```bash
+   conda activate sharp
+   ```
+
+2. **Run a prediction:**
+   ```bash
+   sharp predict -i /path/to/input/images -o /path/to/output/gaussians
+   ```
+
+3. **See all options:**
+   ```bash
+   sharp --help
+   ```
+
+---
+
+## What's Next?
+
+Once you have the web interface running:
+
+1. **Upload an image** using the web interface
+2. **Wait for processing** (usually takes a few seconds per image)
+3. **Download the 3D Gaussian file** (.ply format)
+4. **View it** using a 3D Gaussian viewer (the web interface may include a viewer)
+
+For more advanced usage, check out the [README.md](README.md) file in the project folder.
+
+---
+
+## Getting Help
+
+If you're still stuck after trying these solutions:
+
+1. **Check the project's GitHub Issues page** to see if others have had similar problems
+2. **Read the main [README.md](README.md)** for additional technical details
+3. **Create a new GitHub Issue** describing your problem:
+   - Include your operating system version
+   - Include any error messages you see
+   - Describe what you've already tried
+
+---
+
+## Tips for Success
+
+- **Be patient:** The first setup takes time, but subsequent runs will be much faster
+- **Read error messages:** They often tell you exactly what's wrong
+- **Google is your friend:** Copy error messages and search for them
+- **Keep your terminal open:** Don't close Terminal while the server is running
+- **Save your work:** The web interface processes images but doesn't permanently store them
+
+---
+
+## Summary of Commands
+
+Here's a quick reference of the key commands:
+
+```bash
+# Navigate to project
+cd /path/to/ml-sharp
+
+# Activate environment
+conda activate sharp
+
+# Start web interface (manual method)
+python src/sharp/web/app.py
+
+# Use CLI
+sharp predict -i /path/to/images -o /path/to/output
+
+# Deactivate environment when done
+conda deactivate
+```
+
+---
+
+**Congratulations!** 🎉 You now have SHARP set up and running. Enjoy creating 3D representations from your photos!