Polymodal File Store Documentation

Complete guide to using the file store system for managing your Polymodal PRN assets.

🚀 Getting Started

The Polymodal File Store is a comprehensive asset management system designed for storing and organizing 3D assets, textures, skyboxes, meshes, audio files, and more.

📁 Categories

• Skybox - Environment maps, HDR images, cubemaps
• Mesh - 3D models, geometry files (OBJ, FBX, GLTF, etc.)
• Texture - Material textures, images, bump maps
• Audio - Sound effects, music, spatial audio
• Other - Miscellaneous assets

📤 Uploading Files

Web Interface

1. Click the "+ Upload" button in the header
2. Drag & drop a file or click to browse
3. Select a category and optionally add a custom name and description
4. Click "Upload"

CLI Upload

./upload.js /path/to/file.hdr \
  --category skybox \
  --description "Beautiful sunset skybox"

API Upload (JavaScript)

const formData = new FormData();
formData.append('file', fileBlob);
formData.append('category', 'skybox');
formData.append('description', 'Beautiful sunset skybox');
formData.append('custom_name', 'my-sunset-skybox'); // optional

const response = await fetch('http://localhost:3001/api/upload', {
  method: 'POST',
  body: formData
});
const data = await response.json();

🔍 Searching Files

Use the search bar at the top to find files by name and description. The search uses full-text indexing (FTS5) for fast results and can optionally filter by category type (skybox, texture, mesh, audio, other).

// API Search - all categories
fetch('http://localhost:3001/api/search?q=sunset')
  .then(r => r.json())
  .then(data => console.log(data.files));

// API Search - filtered by category
fetch('http://localhost:3001/api/search?q=mountain&category=texture')
  .then(r => r.json())
  .then(data => console.log(data.files));

🔗 API Reference

Complete API documentation for the Polymodal File Store.

curl "http://localhost:3001/api/files?category=skybox&limit=10"

{
  "files": [
    {
      "id": 1,
      "filename": "1762802859311-777c7e0e2244c1c2.hdr",
      "original_name": "sunset.hdr",
      "hash": "3a31ade447...",
      "size": 2048576,
      "mime_type": "application/octet-stream",
      "category": "skybox",
          "description": "Beautiful sunset skybox",
      "metadata": {},
      "upload_date": 1762802859314,
      "updated_date": 1762802859314
    }
  ],
  "count": 1
}

curl "http://localhost:3001/api/files/1"

{
  "id": 1,
  "filename": "1762802859311-777c7e0e2244c1c2.hdr",
  "original_name": "sunset.hdr",
  "hash": "3a31ade447...",
  "size": 2048576,
  "mime_type": "application/octet-stream",
  "category": "skybox",
  "description": "Beautiful sunset skybox",
  "metadata": {},
  "upload_date": 1762802859314,
  "updated_date": 1762802859314
}

# Search for "sunset" across all categories
curl "http://localhost:3001/api/search?q=sunset"

# Search for "sunset" in skybox category only
curl "http://localhost:3001/api/search?q=sunset&category=skybox"

# Search for "mountain" in textures with limit
curl "http://localhost:3001/api/search?q=mountain&category=texture&limit=10"

{
  "files": [...],
  "count": 5
}

curl -X POST "http://localhost:3001/api/upload" \
  -F "file=@./skybox.hdr" \
  -F "category=skybox" \
  -F "description=Beautiful sunset skybox"

{
  "message": "File uploaded successfully",
  "file": {
    "id": 1,
    "filename": "1762802859311-777c7e0e2244c1c2.hdr",
    "original_name": "skybox.hdr",
    ...
  },
  "duplicate": false
}

curl -X PUT "http://localhost:3001/api/files/1" \
  -H "Content-Type: application/json" \
  -d '{"category": "texture", "description": "Updated description"}'

{
  "message": "File updated successfully",
  "file": { ... }
}

curl -X DELETE "http://localhost:3001/api/files/1"

{
  "message": "File deleted successfully"
}

curl -o sunset.hdr "http://localhost:3001/api/download/1"

curl "http://localhost:3001/api/categories"

{
  "categories": [
    {
      "category": "skybox",
      "count": 10
    },
    {
      "category": "mesh",
      "count": 5
    }
  ]
}

curl "http://localhost:3001/api/stats"

{
  "total_files": 42,
  "total_size": 104857600,
  "by_category": [
    {
      "category": "skybox",
      "count": 10,
      "total_size": 20971520
    }
  ]
}

curl -X POST "http://localhost:3001/api/generate-image" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains, highly detailed, 4k",
    "negative_prompt": "blurry, low quality",
    "size": "512x512",
    "steps": 30,
    "tags": "ai-generated,landscape,sunset",
    "description": "AI-generated sunset landscape"
  }'

{
  "message": "Image generated successfully",
  "file": {
    "id": 15,
    "filename": "1762934567890-abc123def456.png",
    "original_name": "ai-generated-1762934567890.png",
    "size": 458752,
    "category": "texture",
    "tags": ["ai-generated", "landscape", "sunset"]
  },
  "duplicate": false,
  "url": "http://localhost:3001/uploads/1762934567890-abc123def456.png",
  "download_url": "http://localhost:3001/api/download/15"
}

curl -X POST "http://localhost:3001/api/generate-audio" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ambient electronic music with deep bass and ethereal synths",
    "duration": 30,
    "steps": 8,
    "cfg_scale": 1,
    "model": "stable-audio-2.5",
    "output_format": "mp3",
    "description": "AI-generated ambient background music"
  }'

{
  "message": "Audio generated successfully",
  "file": {
    "id": 42,
    "filename": "ambient-electronic-music-with-deep-bass-a1b2c3d4.mp3",
    "original_name": "ambient-electronic-music-with-deep-bass.mp3",
    "size": 1048576,
    "category": "audio",
    "mime_type": "audio/mpeg"
  },
  "duplicate": false,
  "url": "http://localhost:3001/uploads/ambient-electronic-music-with-deep-bass-a1b2c3d4.mp3",
  "download_url": "http://localhost:3001/api/download/42"
}

curl "http://localhost:3001/api/ai/status"

{
  "available": true,
  "provider": "Stability AI",
  "default_model": "flash",
  "models": {
    "flash": {"credits": 2.5, "description": "Fastest and cheapest - SD 3.5 Flash"},
    "core": {"credits": 3.0, "description": "Higher quality - Stable Image Core"},
    "ultra": {"credits": 8.0, "description": "Highest quality - Stable Image Ultra"}
  }
}

🎨🎵 AI Content Generation

The file store integrates with Stability AI to generate both images and audio from text prompts. Generated content is automatically saved to the file store with metadata for easy retrieval.

Setup

AI generation uses Stability AI's cloud API. No local installation required!

Configuration

Configure your API keys in keys.json:

{
  "stability_ai": {
    "api_key": "your-api-key-here",
    "image_api_url": "https://api.stability.ai/v2beta/stable-image/generate",
    "audio_api_url": "https://api.stability.ai/v2beta/audio/stable-audio-2/text-to-audio"
  }
}

Get your API key from platform.stability.ai. The keys.json file is ignored by git for security.

Available Models

Image Generation:

• SD 3.5 Flash (default) - 2.5 credits per image - Fastest and cheapest
• Stable Image Core - 3.0 credits per image - Higher quality
• Stable Image Ultra - 8.0 credits per image - Photorealistic, highest quality

Audio Generation:

• Stable Audio 2.5 (default) - Best quality, supports music and sound effects
• Stable Audio 2 - Previous version, still supported

Generate via Web Interface

Click the 🎨 Generate button in the header to open the AI generation modal:

1. Select Asset Category (Texture, Skybox, Audio, or Other/Image)
2. Enter your Prompt describing what to generate
3. For images: Add optional Negative Prompt, choose size and steps
4. For audio: Set Duration (1-190s), choose model (2.5 or 2), select format (MP3/WAV)
5. Add optional Custom Name and Description
6. Click Generate and wait for the AI to create your content

Generated files automatically appear in your file list with the correct category and prompt-based names.

Generate via API

Example 1: Generate a Texture

const response = await fetch('http://localhost:3001/api/generate-image', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        asset_type: 'texture',
        prompt: 'Seamless wood planks texture, high quality, 4k',
        negative_prompt: 'blurry, low quality',
        size: '1024x1024',
        steps: 40,
        tags: 'wood,planks,seamless'
    })
});

Example 2: Generate a Skybox Preview

const response = await fetch('http://localhost:3001/api/generate-image', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        asset_type: 'skybox',
        prompt: '360 panoramic sunset over ocean, equirectangular',
        negative_prompt: 'seam, distorted',
        size: '1280x720',
        steps: 30
    })
});

Example 3: Generate Concept Art

const response = await fetch('http://localhost:3001/api/generate-image', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        asset_type: 'concept',
        prompt: 'Futuristic cyberpunk city at night',
        negative_prompt: 'blurry, low quality',
        size: '768x512',
        steps: 40
    })
});

Find Generated Images

Generated images are automatically tagged based on their asset type and can be searched:

# Search for all AI-generated images
curl "http://localhost:3001/api/search?q=ai-generated"

# Search for AI-generated textures
curl "http://localhost:3001/api/search?q=ai-generated+texture"

# Search for AI-generated skyboxes
curl "http://localhost:3001/api/search?q=ai-generated+skybox"

💾 Database

Files are stored in a SQLite database with full-text search capabilities (FTS5). Each file has:

• ID - Unique identifier
• Filename - Stored filename (timestamped)
• Original Name - User's original filename or custom display name
• Hash - SHA-256 hash for deduplication
• Size - File size in bytes
• MIME Type - File content type
• Category - Asset category (skybox, texture, mesh, audio, other)
• Description - Text description (searchable)
• Metadata - Custom JSON data
• Upload Date - When file was uploaded
• Updated Date - Last modification
• Parent ID - For cubemap faces, references parent skybox
• Cubemap Face - Face name for cubemap images (front, back, left, right, up, down)

🔄 Integration Examples

Three.js - Load Skybox

// Fetch skybox from file store
const response = await fetch(
  'http://localhost:3001/api/search?q=sunset&category=skybox'
);
const { files } = await response.json();
const skybox = files[0];

// Load with RGBELoader
const loader = new THREE.RGBELoader();
const url = `http://localhost:3001/uploads/${skybox.filename}`;
const texture = await loader.loadAsync(url);
texture.mapping = THREE.EquirectangularReflectionMapping;

scene.background = texture;
scene.environment = texture;

Python - Upload File

import requests

with open('./skybox.hdr', 'rb') as f:
    files = {'file': f}
    data = {
        'category': 'skybox',
        'description': 'Sunset skybox'
    }
    response = requests.post(
        'http://localhost:3001/api/upload',
        files=files,
        data=data
    )
    print(response.json())

cURL - Download File

# Download file by ID
curl -o skybox.hdr http://localhost:3001/api/download/1

# Download with original filename
curl -OJ http://localhost:3001/api/download/1

⚙️ Advanced Features

• Duplicate Detection - Files are deduplicated by SHA-256 hash
• Direct URLs - Each file has a direct access URL
• Metadata Storage - Store custom JSON metadata with files
• CORS Enabled - Access from any origin (development mode)
• File Size Limit - 100MB per file

🛠️ CLI Commands

# Install dependencies
./install.sh

# Start server
./start.sh

# Stop server
./stop.sh

# Upload file
./upload.js file.hdr --category skybox --description "My skybox"

# View logs
tail -f server.log

📊 Response Format

All API responses are in JSON format:

{
  "files": [
    {
      "id": 1,
      "filename": "1762802859311-777c7e0e2244c1c2.hdr",
      "original_name": "sunset.hdr",
      "hash": "3a31ade447...",
      "size": 2048576,
      "mime_type": "application/octet-stream",
      "category": "skybox",
          "description": "Beautiful sunset skybox",
      "metadata": {},
      "upload_date": 1762802859314,
      "updated_date": 1762802859314
    }
  ],
  "count": 1
}

🔗 Quick Links

• Back to Files
• Polymodal PRN System