| # 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! | |