lidavidsh/ml-sharp

1# Detailed Setup Guide for SHARP - Beginner's Edition2 3Welcome! 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.4 5## What is SHARP?6 7SHARP 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.8 9## Table of Contents10 111. [Prerequisites - What You Need](#prerequisites---what-you-need)122. [Step 1: Install Conda](#step-1-install-conda)133. [Step 2: Download the Project](#step-2-download-the-project)144. [Step 3: Set Up the Project](#step-3-set-up-the-project)155. [Step 4: Start the Web Interface](#step-4-start-the-web-interface)166. [Troubleshooting](#troubleshooting)177. [Alternative Setup Methods](#alternative-setup-methods)18 19---20 21## Prerequisites - What You Need22 23Before we begin, here's what you'll need:24 25### Hardware Requirements26- A computer running **macOS** (for Windows or Linux, see [Alternative Setup Methods](#alternative-setup-methods))27- At least **8 GB of RAM** (16 GB or more recommended)28- At least **5 GB of free disk space**29- **Internet connection** for downloading software and dependencies30 31### What You Don't Need32- You don't need to know how to code33- You don't need prior experience with Python or machine learning34- You don't need to understand how the AI works (but you can learn if you want!)35 36---37 38## Step 1: Install Conda39 40Conda is a package manager that helps organize Python and its libraries. Think of it as an app store for Python tools.41 42### What is Conda?43 44Conda 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.45 46### Download and Install Miniconda47 481. **Go to the Miniconda download page:**49   - Open your web browser and visit: https://docs.conda.io/en/latest/miniconda.html50 512. **Download the macOS installer:**52   - Look for the **macOS** section53   - Download the **latest Python 3.x** installer for your Mac:54     - If you have an **M1/M2/M3 Mac** (Apple Silicon): Choose the `Apple M1` or `arm64` version55     - If you have an **Intel Mac**: Choose the `Intel x86_64` version56   - The file will be named something like `Miniconda3-latest-MacOSX-arm64.pkg` or `Miniconda3-latest-MacOSX-x86_64.pkg`57 583. **Install Miniconda:**59   - Double-click the downloaded `.pkg` file60   - Follow the installation wizard:61     - Click "Continue" through the introduction screens62     - Accept the license agreement63     - Choose "Install for me only" (recommended)64     - Click "Install" and enter your password when prompted65   - When installation completes, click "Close"66 674. **Verify the installation:**68   - Open **Terminal** (you can find it in Applications → Utilities → Terminal)69   - Type the following command and press Enter:70     ```bash71     conda --version72     ```73   - You should see something like `conda X.X.X` (the exact version number may vary)74   - **If you get an error** saying "conda: command not found":75     - Close Terminal completely and open it again76     - Try the command again77     - If it still doesn't work, see [Troubleshooting](#troubleshooting)78 79---80 81## Step 2: Download the Project82 83Now we need to download the SHARP project files to your computer.84 85### Option A: Download via GitHub (Easiest for Beginners)86 871. **Go to the GitHub repository:**88   - Visit the repository URL where this project is hosted (check the address bar or the project README for the correct URL)89 902. **Download the ZIP file:**91   - Click the green **"Code"** button92   - Click **"Download ZIP"**93   - The file will be saved to your Downloads folder94 953. **Extract the ZIP file:**96   - Go to your Downloads folder97   - Double-click the `ml-sharp-main.zip` (or similar name) file98   - macOS will automatically extract the folder99 1004. **Move to a convenient location (optional but recommended):**101   - Create a folder in your Documents called `Projects`102   - Drag the extracted `ml-sharp-main` folder into `Projects`103   - Rename it to just `ml-sharp` to make it simpler104 105### Option B: Using Git (If You Have It Installed)106 107If you're comfortable with Git or have it installed:108 109```bash110cd ~/Documents111git clone <repository-url>112cd ml-sharp113```114 115(Replace `<repository-url>` with the actual Git URL from the GitHub repository)116 117---118 119## Step 3: Set Up the Project120 121Now we'll set up the Python environment and install all the required libraries.122 123### Using Terminal124 1251. **Open Terminal** (Applications → Utilities → Terminal)126 1272. **Navigate to the project folder:**128   - Type `cd` followed by a space129   - Drag the `ml-sharp` folder from Finder onto the Terminal window130   - Press Enter131   - Your command should look something like: `cd /Users/YourName/Documents/Projects/ml-sharp`132 1333. **Initialize conda in your terminal:**134   ```bash135   conda init bash136   ```137   - Close Terminal and open it again138 1394. **Create the Python environment:**140   ```bash141   conda create -n sharp python=3.13 -y142   ```143   - This creates a special environment named "sharp" with Python 3.13144   - The process may take a few minutes145   - Wait for it to complete146 1475. **Activate the environment:**148   ```bash149   conda activate sharp150   ```151   - You should see `(sharp)` appear at the beginning of your command prompt152 1536. **Install the main project dependencies:**154   ```bash155   pip install -r requirements.txt156   ```157   - This installs all the machine learning libraries SHARP needs158   - **This will take 5-15 minutes** depending on your internet speed159   - You'll see a lot of text scrolling by—this is normal160   - Be patient and let it finish161 1627. **Install the web interface dependencies:**163   ```bash164   pip install -r src/sharp/web/requirements.txt165   ```166   - This installs the web server components167   - This should be faster, taking about 1-2 minutes168 1698. **Verify the installation:**170   ```bash171   sharp --help172   ```173   - If successful, you'll see the SHARP help menu174   - This means everything is installed correctly!175 176---177 178## Step 4: Start the Web Interface179 180Now for the exciting part—starting the web interface!181 182### If start.command Works (Try This First)183 1841. **In Finder, navigate to the ml-sharp folder**185 1862. **Double-click the `start.command` file**187 1883. **If macOS blocks it with a security warning:**189   - Right-click (or Control-click) on `start.command`190   - Select **"Open"** from the menu191   - Click **"Open"** in the dialog that appears192   - macOS will remember your choice for this file193   194   OR195   196   - Go to **System Settings → Privacy & Security**197   - Scroll down to find a message about `start.command` being blocked198   - Click **"Open Anyway"**199   - Right-click on `start.command` again and choose **"Open"**200 2014. **A Terminal window will open** with the SHARP logo202 2035. **The script will automatically:**204   - Check your conda installation205   - Create or activate the environment206   - Install any missing dependencies207   - Start the web server208 2096. **When you see "Starting Sharp Web Interface":**210   - Open your web browser (Safari, Chrome, Firefox, etc.)211   - Go to: **http://localhost:8000**212   - You should see the SHARP web interface!213 214### If start.command Doesn't Work (Manual Method)215 216If the automatic script doesn't work, don't worry! Here's how to start it manually:217 2181. **Open Terminal**219 2202. **Navigate to the project folder:**221   ```bash222   cd /path/to/ml-sharp223   ```224   (Replace with your actual path, or drag the folder onto Terminal)225 2263. **Activate the conda environment:**227   ```bash228   conda activate sharp229   ```230 2314. **Start the web server:**232   ```bash233   python src/sharp/web/app.py234   ```235 2365. **Open your web browser and go to:**237   - **http://localhost:8000**238 2396. **To stop the server:**240   - Press **Control + C** in the Terminal window241 242---243 244## Troubleshooting245 246### "conda: command not found"247 248**Problem:** Terminal doesn't recognize the `conda` command.249 250**Solutions:**251 2521. **Initialize conda:**253   ```bash254   ~/miniconda3/bin/conda init bash255   ```256   Then close and reopen Terminal.257 2582. **Add conda to your PATH manually:**259   ```bash260   echo 'export PATH="$HOME/miniconda3/bin:$PATH"' >> ~/.bash_profile261   source ~/.bash_profile262   ```263 2643. **If you installed Anaconda instead of Miniconda:**265   ```bash266   echo 'export PATH="$HOME/anaconda3/bin:$PATH"' >> ~/.bash_profile267   source ~/.bash_profile268   ```269 270### "Permission denied" when running start.command271 272**Problem:** The script doesn't have permission to run.273 274**Solution:**275 2761. Open Terminal2772. Navigate to the project folder2783. Make the script executable:279   ```bash280   chmod +x start.command281   ```2824. Try double-clicking it again283 284### "Failed to create conda environment"285 286**Problem:** Error creating the Python environment.287 288**Solutions:**289 2901. **Make sure you have enough disk space** (at least 5 GB free)291 2922. **Update conda:**293   ```bash294   conda update conda295   ```296 2973. **Try creating the environment with a different Python version:**298   ```bash299   conda create -n sharp python=3.11 -y300   ```301 302### Installation is Taking Forever / Stuck303 304**Problem:** `pip install` seems frozen or very slow.305 306**Solutions:**307 3081. **Be patient:** The first installation can take 10-20 minutes, especially for PyTorch3092. **Check your internet connection**3103. **If truly stuck (no progress for 30+ minutes):**311   - Press Control + C to cancel312   - Try again:313     ```bash314     pip install -r requirements.txt --no-cache-dir315     ```316 317### "Port 8000 is already in use"318 319**Problem:** Another application is using port 8000.320 321**Solution:**322 3231. **Find and stop the process using port 8000:**324   ```bash325   lsof -ti:8000 | xargs kill -9326   ```327 3282. **Or modify the port in the app.py file:**329   - Open `src/sharp/web/app.py` in a text editor330   - Look for the line near the end: `uvicorn.run(app, host="0.0.0.0", port=8000)`331     (Tip: Search for `port=` to find it quickly)332   - Change `port=8000` to `port=8080` (or another available port number)333   - Save the file and start the server again334   - Then access it at: http://localhost:8080 (or your chosen port)335 336### The Web Interface Won't Load337 338**Problem:** Browser shows an error when accessing http://localhost:8000339 340**Solutions:**341 3421. **Make sure the server is actually running** (check Terminal for errors)3432. **Try a different browser**3443. **Clear your browser cache**3454. **Check if you're using the correct URL:** http://localhost:8000 (not https)3465. **Look for error messages in the Terminal** and search for them online or see below347 348### "ModuleNotFoundError: No module named 'sharp'"349 350**Problem:** Python can't find the SHARP module.351 352**Solution:**353 3541. Make sure you're in the correct directory3552. Make sure the conda environment is activated (you should see `(sharp)` in the prompt)3563. Try installing again:357   ```bash358   pip install -r requirements.txt359   ```360 361### Out of Memory Errors362 363**Problem:** Your computer runs out of RAM.364 365**Solutions:**366 3671. **Close other applications** to free up memory3682. **Restart your computer** and try again3693. **Consider using the CLI** instead of the web interface for large batches of images370 371---372 373## Alternative Setup Methods374 375### For Windows Users376 377The `start.command` script is macOS-specific, but you can follow these steps on Windows:378 3791. **Install Miniconda for Windows:**380   - Download from: https://docs.conda.io/en/latest/miniconda.html381   - Choose the Windows installer382 3832. **Open Anaconda Prompt** (search for it in the Start menu)384 3853. **Follow steps 3 and 4** from above, using the same commands386 387### For Linux Users388 389The setup is very similar to macOS:390 3911. **Install Miniconda for Linux:**392   ```bash393   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh394   bash Miniconda3-latest-Linux-x86_64.sh395   ```396 3972. **Follow the macOS instructions** using Terminal398 399### Using the Command Line Interface (CLI)400 401If you prefer not to use the web interface, you can use SHARP directly from the command line:402 4031. **Activate the environment:**404   ```bash405   conda activate sharp406   ```407 4082. **Run a prediction:**409   ```bash410   sharp predict -i /path/to/input/images -o /path/to/output/gaussians411   ```412 4133. **See all options:**414   ```bash415   sharp --help416   ```417 418---419 420## What's Next?421 422Once you have the web interface running:423 4241. **Upload an image** using the web interface4252. **Wait for processing** (usually takes a few seconds per image)4263. **Download the 3D Gaussian file** (.ply format)4274. **View it** using a 3D Gaussian viewer (the web interface may include a viewer)428 429For more advanced usage, check out the [README.md](README.md) file in the project folder.430 431---432 433## Getting Help434 435If you're still stuck after trying these solutions:436 4371. **Check the project's GitHub Issues page** to see if others have had similar problems4382. **Read the main [README.md](README.md)** for additional technical details4393. **Create a new GitHub Issue** describing your problem:440   - Include your operating system version441   - Include any error messages you see442   - Describe what you've already tried443 444---445 446## Tips for Success447 448- **Be patient:** The first setup takes time, but subsequent runs will be much faster449- **Read error messages:** They often tell you exactly what's wrong450- **Google is your friend:** Copy error messages and search for them451- **Keep your terminal open:** Don't close Terminal while the server is running452- **Save your work:** The web interface processes images but doesn't permanently store them453 454---455 456## Summary of Commands457 458Here's a quick reference of the key commands:459 460```bash461# Navigate to project462cd /path/to/ml-sharp463 464# Activate environment465conda activate sharp466 467# Start web interface (manual method)468python src/sharp/web/app.py469 470# Use CLI471sharp predict -i /path/to/images -o /path/to/output472 473# Deactivate environment when done474conda deactivate475```476 477---478 479**Congratulations!** 🎉 You now have SHARP set up and running. Enjoy creating 3D representations from your photos!480