Feat support independent tile unmixing

INSTALL.md

@@ -0,0 +1,210 @@
+# SeeSpot Installation Guide
+
+This guide walks you through installing SeeSpot on your system.
+
+## Prerequisites
+
+- **Operating System**: Linux (Ubuntu 20.04+, CentOS 7+, or similar)
+- **Disk Space**: At least 10 GB free for cache directory (more recommended for large datasets)
+- **AWS Credentials**: Valid AWS credentials with read access to `s3://aind-open-data`
+
+The installer will automatically install `uv` (Python package manager) if not present. Python 3.11+ will be installed by `uv` during the installation process.
+
+## Quick Start (Recommended)
+
+Run the installer with default settings:
+
+```bash
+cd /home/matt.davis/code/see-spot
+./install.sh
+```
+
+The installer will:
+1. Check system requirements
+2. Install `uv` if needed
+3. Validate AWS credentials
+4. Use default configuration (cache directory, server port, etc.)
+5. Set up Python environment
+6. Install dependencies
+7. Create launcher script
+
+## Interactive Installation
+
+If you want to customize settings during installation, use the `--interactive` flag:
+
+```bash
+./install.sh --interactive
+```
+
+This will prompt you for configuration values.
+- Cache directory: `~/.seespot/cache`
+- Server host: `0.0.0.0`
+- Server port: `5555`
+
+Examples:
+
+```bash
+# Standard installation (non-interactive, default)
+./install.sh
+
+# Interactive installation with prompts
+./install.sh --interactive
+
+# Verbose installation
+./install.sh --verbose
+
+# Dry run to preview changes
+./install.sh --dry-run
+
+# Interactive with verbose output
+./install.sh --interactive --verbose
+```
+
+## Installation Options
+
+The `install.sh` script supports the following options:
+
+- `--interactive` or `-i`: Prompt for configuration values
+- `--yes` or `-y`: Explicitly use non-interactive mode (default behavior)
+- `--verbose` or `-v`: Show detailed output
+- `--dry-run`: Show what would be done without making changes
+- `--help` or `-h`: Display help message
+
+**Default values used in non-interactive mode:**
+
+## AWS Credentials Setup
+
+SeeSpot requires AWS credentials to access data. The installer checks for credentials in this order:
+
+1. **Environment Variables**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
+2. **AWS CLI Config**: `~/.aws/credentials` (default profile)
+3. **IAM Role**: For EC2 instances with attached IAM roles
+
+### Setting up AWS CLI credentials:
+
+```bash
+# Install AWS CLI if not present
+curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
+unzip awscliv2.zip
+sudo ./aws/install
+
+# Configure credentials
+aws configure
+```
+
+You'll be prompted for:
+- AWS Access Key ID
+- AWS Secret Access Key
+- Default region (e.g., `us-west-2`)
+- Output format (e.g., `json`)
+
+### Using environment variables:
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export AWS_SESSION_TOKEN="your-session-token"  # Optional
+```
+
+## Configuration
+
+After installation, SeeSpot's configuration is stored in `~/.seespot/config.yaml`.
+
+### Configuration Options
+
+```yaml
+# Cache directory for downloaded S3 data
+cache_dir: /path/to/cache
+
+# Server settings
+server:
+  host: 0.0.0.0  # Listen on all interfaces
+  port: 5555     # Server port
+
+# AWS settings (optional overrides)
+aws:
+  profile: default
+  region: us-west-2
+  bucket: aind-open-data
+```
+
+### Configuration Precedence
+
+Configuration values are resolved in this order (highest to lowest priority):
+
+1. **Environment Variables**: `SEESPOT_CACHE_DIR`, `SEESPOT_HOST`, `SEESPOT_PORT`, `SEESPOT_BUCKET`
+2. **Command-Line Arguments**: Passed to the `seespot` launcher
+3. **Config File**: `~/.seespot/config.yaml` (user config) or `/etc/seespot/config.yaml` (system config)
+4. **Defaults**: Built-in fallback values
+
+### Example: Override port via environment variable
+
+```bash
+SEESPOT_PORT=8080 seespot start
+```
+
+## Using SeeSpot
+
+After installation, use the `seespot` command to manage the server:
+
+```bash
+# Start the server
+seespot start
+
+# Stop the server
+seespot stop
+
+# Check server status
+seespot status
+
+# View logs
+seespot logs
+```
+
+The server will be available at `http://localhost:5555` (or your configured port).
+
+## Accessing the Web Interface
+
+Once the server is running:
+
+1. Open a web browser
+2. Navigate to `http://localhost:5555`
+3. You'll see the SeeSpot visualization interface
+
+### First-Time Setup
+
+On first use:
+1. Click "Manage Datasets" in the sidebar
+2. Download a dataset from the list
+3. Set it as active
+4. The visualization will load automatically
+
+
+## Uninstallation
+
+To remove SeeSpot:
+
+```bash
+cd /home/matt.davis/code/see-spot
+./uninstall.sh
+```
+
+The uninstaller will:
+1. Stop any running servers
+2. Remove the launcher script
+3. Optionally remove cache directory
+4. Remove configuration directory
+
+
+## What Gets Installed
+
+After installation, you'll have:
+
+- **Python Environment**: `.venv/` in the repository
+- **Launcher Script**: `~/.local/bin/seespot`
+- **Config Directory**: `~/.seespot/`
+  - `config.yaml` - Configuration file
+  - `seespot.pid` - Server process ID
+  - `seespot.log` - Server logs
+- **Cache Directory**: `~/.seespot/cache/` (or your configured location)
+  - Downloads from S3 are cached here

README.md

@@ -7,18 +7,80 @@
 ![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?logo=codecov)
 ![Python](https://img.shields.io/badge/python->=3.10-blue?logo=python)
 
+## Quick Start
+
+### Installation
+```bash
+# Clone repository
+git clone https://github.com/AllenNeuralDynamics/see-spot.git
+cd see-spot
+
+# Run installer (uses defaults: port 5555, cache at ~/.seespot/cache)
+./install.sh
+
+# Or customize settings interactively
+./install.sh --interactive
+```
+
+### Launch
+```bash
+# Start the server
+seespot start
+
+# Access at http://localhost:5555
+```
+
+For detailed installation instructions, AWS credentials setup, and troubleshooting, see [INSTALL.md](INSTALL.md).
+
 ## App UI
 ![Spot Visualization](img/seespot-app-v.png)
 *Interactive dashboard showing spot channel analysis with Sankey flow diagram, scatter plot, and summary statistics*
 
-## start-up (local)
+## Development Setup
 + Install
   + `uv sync`
-+ Launch: 
++ Launch with auto-reload: 
 ```bash
 cd /home/matt.davis/code/see-spot && source .venv/bin/activate && cd src && uvicorn see_spot.app:app --host 0.0.0.0 --port 9999 --reload
 ```
 
+## Dataset Types
+
+### Regular (Fused) Datasets
+Standard datasets with fused image data at the top level:
+```
+dataset_name/
+  image_spot_spectral_unmixing/
+    mixed_spots_*.pkl
+    unmixed_spots_*.pkl
+  image_tile_fusing/fused/
+    channel_*.zarr
+```
+
+### Tiled (Non-Fused) Datasets
+Datasets with independent tile processing, where each tile has separate spot data:
+```
+dataset_name/
+  image_spot_spectral_unmixing/
+    Tile_X_0001_Y_0000_Z_0000/
+      mixed_spots_*_tile_*.pkl
+      unmixed_spots_*_tile_*.pkl
+    Tile_X_0002_Y_0000_Z_0000/
+      ...
+```
+
+When downloading a tiled dataset, the system automatically:
+- Detects tile subfolders (beginning with "Tile")
+- Creates virtual dataset entries for each tile
+- Names them as: `{dataset_name}_X_####_Y_####_Z_####`
+
+Example: Downloading `HCR_799211_2025-10-02_15-10-00_processed_2025-11-06_22-50-54` with tiles creates:
+- `HCR_799211_2025-10-02_15-10-00_processed_2025-11-06_22-50-54_X_0001_Y_0000_Z_0000`
+- `HCR_799211_2025-10-02_15-10-00_processed_2025-11-06_22-50-54_X_0002_Y_0000_Z_0000`
+- etc.
+
+Each virtual tile dataset appears as a separate entry in the dataset management table and can be loaded independently.
+
 ## Changelog
 + v0.5.0 (09-19-2025)
   + backend downloads mixed + unmixed tables, merges and saves as .parquet (massive compression)

config.yaml.example

@@ -0,0 +1,35 @@
+# SeeSpot Configuration Example
+# Copy this to ~/.seespot/config.yaml and customize as needed
+
+# Directory where S3 data will be cached locally
+# This should have at least 50GB of free space
+cache_dir: ~/.seespot/cache
+
+# Server configuration
+server:
+  # Host address to bind to
+  # Use 0.0.0.0 to allow external connections
+  # Use 127.0.0.1 for localhost only
+  host: 0.0.0.0
+
+  # Port number for the web server
+  port: 5555
+
+# AWS configuration (optional)
+aws:
+  # AWS profile name from ~/.aws/credentials
+  # If not specified, uses default profile or environment variables
+  # profile: default
+
+  # AWS region
+  # If not specified, uses AWS_DEFAULT_REGION or us-west-2
+  # region: us-west-2
+
+  # S3 bucket containing the data
+  # Default: aind-open-data
+  # bucket: aind-open-data
+
+# Logging configuration (optional)
+# logging:
+#   level: INFO  # Options: DEBUG, INFO, WARNING, ERROR
+#   file: ~/.seespot/seespot.log

dye-lines-clipping.md

@@ -0,0 +1,41 @@
+Looking at the images, I can see the problem clearly. When you zoom in or change the axis limits, the dye lines disappear because one or both endpoints fall outside the visible range, and ECharts stops rendering the entire line.
+
+Analysis of the Problem
+Current implementation:
+
+Dye lines are drawn from origin (0, 0) to endpoint (x1, y1)
+When axis limits change (e.g., x starts at 10 instead of 0), the origin point is outside the visible area
+ECharts doesn't render lines with endpoints outside the axis range
+Potential Solutions
+Option 1: Clip lines to axis boundaries (Most robust)
+Calculate the intersection of the dye line with the current axis boundaries
+Always provide two points that are within or on the edge of the visible area
+This requires line-rectangle intersection math
+Pros: Lines always visible, mathematically correct
+Cons: More complex calculation
+Option 2: Extend lines beyond axis limits
+Instead of calculating endpoints based on axis limits, always use very large coordinates
+Make lines extend from (-1000, -1000) to (10000, 10000) or similar
+Let ECharts clip the rendering
+Pros: Simple, no recalculation needed
+Cons: May have rendering issues, less precise
+Option 3: Use visualMap or dataZoom with clip: false
+Try setting clip: false on the line series
+This tells ECharts to render even if points are outside axis range
+Pros: Simplest - just one property change
+Cons: May not work reliably, depends on ECharts version
+Option 4: Use graphic elements instead of series
+Add dye lines as graphic elements (like the "Mixed/Unmixed" text)
+Graphic elements use pixel coordinates relative to the grid
+Would require converting data coordinates to pixel coordinates
+Pros: Full control over rendering
+Cons: More complex, harder to maintain
+Recommendation
+I'd suggest trying Option 3 first (adding clip: false) - it's the simplest and might just work.
+
+If that doesn't work, go with Option 1 - calculate the intersection of the dye line (which extends infinitely in both directions from origin along the dye direction) with the current axis boundaries. The math would be:
+
+Dye line equation: points along direction (dx, dy) are t * (dx, dy) for any scalar t
+Find t values where this line intersects the four axis boundaries (xMin, xMax, yMin, yMax)
+Use the two intersection points that are within the visible rectangle
+This way the line always extends across the visible chart area regardless of zoom level.