LUT Transformation API

A FastAPI-based service for transforming .cube LUT files using AI-generated color adjustments and creating split preview images.

Features

LUT Transformation: Transform .cube files using JSON-based color adjustments
AI Integration: Generate color adjustments based on natural language prompts
Split Preview: Create side-by-side comparison images showing before/after effects
Base64 Support: Handle file uploads and image responses in base64 format

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Run the Server

uvicorn main:app --reload

The API will be available at http://localhost:8000

3. API Documentation

Visit http://localhost:8000/docs for interactive API documentation.

API Endpoints

POST /transform-lut

Transform a LUT file using a text prompt.

Request Body:

{
  "cube_file_base64": "base64_encoded_cube_file",
  "user_prompt": "Make this LUT more cinematic with cool shadows"
}

Response:

{
  "success": true,
  "message": "LUT transformation completed successfully",
  "adjustments_applied": {
    "shadows": {"r": 0.9, "g": 1.0, "b": 1.2},
    "midtones": {"r": 1.0, "g": 1.0, "b": 1.0},
    "highlights": {"r": 1.1, "g": 1.05, "b": 0.95},
    "global": {"r": 1.0, "g": 1.0, "b": 1.0}
  },
  "split_preview_base64": "base64_encoded_preview_image"
}

GET /health

Check API health and sample image availability.

Response:

{
  "status": "healthy",
  "sample_image_exists": true
}

How It Works

Upload: Send a .cube file as base64 and a text prompt
AI Processing: The generate_new_cube() function processes the prompt and returns JSON adjustments
LUT Transformation: Apply the adjustments to the original LUT using the LUTTransformer class
Image Processing: Apply both original and modified LUTs to the sample image
Split Preview: Create a side-by-side comparison with a vertical divider line
Response: Return the preview image as base64

LUT Adjustment Format

The AI generates adjustments in this JSON format:

{
  "shadows": {"r": 0.9, "g": 1.0, "b": 1.2},
  "midtones": {"r": 1.0, "g": 1.0, "b": 1.0},
  "highlights": {"r": 1.1, "g": 1.05, "b": 0.95},
  "global": {"r": 1.0, "g": 1.0, "b": 1.0}
}

shadows: Adjustments for darker regions (luminance < 0.33)
midtones: Adjustments for medium regions (0.33 ≤ luminance < 0.66)
highlights: Adjustments for brighter regions (luminance ≥ 0.66)
global: Overall adjustments applied to all regions

Testing

Use the provided test_main.http file to test the endpoints, or use curl:

curl -X POST "http://localhost:8000/transform-lut" \
  -H "Content-Type: application/json" \
  -d '{
    "cube_file_base64": "VElUTEUgIlRlc3QgTFVUIgpMVVRfM0RfU0laRSAyCg...",
    "user_prompt": "Make this LUT more cinematic with cool shadows"
  }'

Sample Image

The API uses sample.jpg as the standard test image for preview generation. Make sure this file exists in the project root.

AI Integration

Replace the placeholder generate_new_cube() function with your actual AI implementation that takes a user prompt and returns color adjustment JSON.

Error Handling

The API includes comprehensive error handling for:

Invalid cube file formats
Missing sample images
Base64 decoding errors
Image processing failures
File system operations