Virtual Try-On (vtryon)

Smart, multi-slot AI virtual fitting room for WooCommerce. Enables customers to upload full-body photos and virtually try on clothing combinations across configured slots (tops, bottoms, footwear, accessories, etc.) powered by modern multimodal AI models.

Features

• Multi-Slot Outfit Engine:
  • Configurable dynamic slots (up to 8 slots: Upper, Bottom, Shoes, Outerwear, Accessories, etc.).
  • WooCommerce category & child-taxonomy mapping with automatic tree cache.
  • Client-side Auto-Replace logic (ensuring the latest selection per slot is retained).
• Multi-Provider AI Integration:
  • Google Gemini: default gemini-2.5-flash-image (and compatible Imagen models).
  • OpenAI: default gpt-image-1 / DALL-E endpoints.
  • Alibaba Qwen: default qwen-image-edit.
  • Mistral: default pixtral-12b-2409.
  • Custom API: fully configurable OpenAI/Gemini-compatible base URL and model.
• Client-Side Optimization:
  • In-browser canvas image compression before upload to reduce payload and network latency.
  • LocalStorage persistence for user photos and selected wardrobe slots across pages.
  • Product variant selector with live image switching and out-of-stock filtering.
• Enterprise Security & Performance:
  • Nonce verification & origin checking.
  • Real MIME sniffing (magic byte inspection) preventing spoofed uploads.
  • HMAC-signed temporary image URLs with expiration.
  • SHA-256 combination-based disk caching to eliminate redundant AI calls.
  • Built-in per-IP rate limiting.

Directory Structure

vtryon/
├── vtryon.php                 # Plugin bootstrap & lifecycle hooks
├── uninstall.php              # Clean removal handler
├── README.md                  # Project documentation
├── LICENSE                    # GNU General Public License v2
├── includes/
│   ├── requires.php           # Class loader & mbstring fallback
│   ├── class-vt-plugin.php    # Lifecycle & core bootstrapping
│   ├── class-vt-rest.php      # REST API route controllers
│   ├── class-vt-slots.php     # Dynamic slot engine & taxonomy resolver
│   ├── class-vt-frontend.php  # Shortcodes, drawer injection, script enqueues
│   ├── class-vt-settings.php  # WooCommerce admin settings page
│   ├── class-vt-security.php  # Nonces, rate limiting, HMAC URL signing, validation
│   ├── class-vt-cache.php     # SHA-256 combo caching & disk persistence
│   ├── class-vt-prompt.php    # Structured multi-garment AI prompt builder
│   ├── class-vt-providers.php # Provider factory & management
│   ├── abstract-class-vt-provider.php # Base provider abstract class
│   └── providers/             # Dedicated AI drivers
│       ├── class-vt-provider-google.php
│       ├── class-vt-provider-openai.php
│       ├── class-vt-provider-qwen.php
│       ├── class-vt-provider-mistral.php
│       └── class-vt-provider-custom.php
├── assets/
│   ├── js/
│   │   ├── tryon.js           # Client drawer, compression, slot state, variation handler
│   │   └── admin-slots.js     # Admin dynamic slot configuration UI
│   └── css/
│       └── tryon.css          # Floating drawer & fitting button UI styles
└── tests/
    └── smoke-test.php         # Standalone PHP smoke test suite (35 assertions)

Installation

1. Copy or clone the vtryon directory into your WordPress plugins folder:

   wp-content/plugins/vtryon

2. Activate the plugin via WordPress Admin → Plugins or via WP-CLI:

   wp plugin activate vtryon

3. Navigate to WooCommerce → Settings → Virtual Try-On (admin.php?page=wc-settings&tab=vtryon):
   • Choose your preferred AI Provider.
   • Enter your API Key / Endpoint.
   • Configure your outfit slots and map them to WooCommerce product categories.

Shortcodes

• [vtryon_drawer]: Embeds the virtual try-on drawer modal anywhere in your theme (by default, automatically injected into wp_footer).
• [vtryon_button product_id="123"]: Renders a "Try On" button for a specific product, opening the drawer and loading the product into its designated slot.

REST API Endpoints

Namespace: /wp-json/vtryon/v1

1. Status Check

GET /wp-json/vtryon/v1/tryon/status

Returns system readiness, configured slots, and the active AI provider status.

2. Generate Try-On Image

POST /wp-json/vtryon/v1/tryon/generate
Content-Type: application/json
X-VT-Nonce: <nonce>

Payload:

{
  "user_image": {
    "data": "data:image/jpeg;base64,..."
  },
  "slots": [
    {
      "category": "upper",
      "product_title": "Classic Linen Shirt",
      "variant_label": "White / L",
      "garment_image": { "data": "data:image/png;base64,..." }
    },
    {
      "category": "bottom",
      "product_title": "Slim Fit Chinos",
      "variant_label": "Navy",
      "garment_image": { "data": "data:image/png;base64,..." }
    }
  ],
  "options": {
    "prompt_extra": "studio lighting, clean background"
  }
}

Response:

{
  "success": true,
  "image_url": "https://example.com/wp-json/vtryon/v1/tryon/image/a1b2c3...?e=1730000000&s=hmac_signature",
  "cached": false,
  "provider": "google",
  "model": "gemini-2.5-flash-image"
}

3. Retrieve Product Data

GET /wp-json/vtryon/v1/tryon/product/{id}

Fetches product title, images, mapped slot category, and in-stock variations.

4. Add Full Outfit to WooCommerce Cart

POST /wp-json/vtryon/v1/tryon/cart/add-set
Content-Type: application/json
X-VT-Nonce: <nonce>

Payload:

{
  "items": [
    { "product_id": 123, "variation_id": 456, "quantity": 1 },
    { "product_id": 789, "variation_id": 0, "quantity": 1 }
  ]
}

5. Fetch Cached Output Image

GET /wp-json/vtryon/v1/tryon/image/{hash}?e={timestamp}&s={signature}

Securely serves the cached result with HMAC validation and expiry check.

Running Tests

Run the standalone smoke test suite without requiring a full WordPress database boot:

php tests/smoke-test.php

All 35 unit/integration tests verify:

• AI Provider instantiation & resolution
• Prompt building & sanitization
• SHA-256 combination hashing
• Disk cache read/write & expiry
• HMAC URL signature tampering checks
• Payload validation & magic-byte MIME inspection

License

This project is licensed under the GNU General Public License v2.0 (GPL-2.0-or-later).