Skip to content

Mask Tuner - Visual Aim Assist Configuration Tool

📖 Overview

The Mask Tuner is a real-time visual debugging utility designed to help you fine-tune color mask parameters for aim assist or computer vision pipelines. Instead of guessing slider values, you can visually verify how your settings perform against a dynamic test pattern containing target variants, brightness gradients, and random distractors.

✨ Features

  • Real-time Preview: Side-by-side view of Original → Masked Result → Binary Mask
  • 7×5 HSV Test Grid: Covers Hue (±45°), Saturation (±60), and Value (25–255) variations
  • Dark Target Testing: Ultra-low brightness squares (V=50, 25) with red borders for low-light tuning
  • Smart Distractors: 150+ random noise squares with 20% "trap" colors that match your target
  • Multiple Color Spaces: Switch between HSV, BGR, and RGB masking modes
  • One-Click Config Export: Save tuned values directly to config.json or export a new file

📦 Requirements

  • Python 3.8+
  • opencv-python
  • numpy
  • Pillow
  • tkinter (usually bundled with Python)

🚀 Installation & Setup

  1. Clone or download the repository: 
    git clone https://github.com/Frank1o3/Aimbot
cd <repo-directory>
  2. Install dependencies: 
    pip install opencv-python numpy Pillow
  3. Run the tuner: 
    python mask_tuner.py
  4. On first launch, the app will search for config.json. If not found, click Yes to manually select your config file.

⚙️ How It Works

The application generates a synthetic test image in real-time at ~30 FPS:

  1. Background Gradient: A subtle vertical gradient simulates environmental noise & lighting shifts
  2. Target Grid (7×5): A moving matrix tests your mask against:
  3. Columns (Hue): ±45 deviation from your base target color
  4. Rows (Value/Brightness): From full brightness (255) down to near-black (25)
  5. Saturation: Varies diagonally across the grid to simulate material/weathering
  6. Distractors: Randomly placed colored squares test false-positive rates. 20% share your exact target color ("traps") to verify mask sensitivity.
  7. Mask Processing: Applies your current slider settings using cv2.inRange() and displays the result instantly across three panels.

🎮 Usage Guide

Step 1: Select Color Space

Use the dropdown to switch between hsv, bgr, or rgb. HSV is highly recommended as it separates brightness (V) from color (H/S), making aim assist tuning much more stable across lighting conditions.

Step 2: Understand the Panels

Panel What You See
Left (Original) Moving target grid + 150 random distractors
Middle (Masked) Only pixels matching your tolerance remain visible (others go black)
Right (Binary Mask) White = Detected ✅ | Black = Ignored ❌

Step 3: Tuning Workflow

  1. Start with Value (V): Increase the Value Tolerance slider until all 5 brightness rows turn white in the right panel
  2. Adjust Hue (H): Expand Hue Tolerance until the full ±45 range is detected
  3. Fine-tune Saturation (S): Increase Saturation Tolerance to catch washed-out or oversaturated variants
  4. Verify Distractors: Random squares should stay black. If >20% turn white, tighten tolerances
  5. Test "Trap" Colors: ~30 distractors share your exact target color. These MUST be white. If they're black, your mask is too strict.

Step 4: Save Configuration

  • Apply to config.json: Overwrites the loaded config with your tuned values
  • Save As...: Exports to a new file (recommended for backups/testing)

💡 Pro Tips

  • 🔴 Red-bordered squares = Low brightness test (V ≤ 50). These are the hardest to detect and critical for shadow/distance scenarios
  • 🎯 Trap Distractors = 20% of noise shares your target color. Use them to validate sensitivity, not just noise rejection
  • 🌈 HSV > BGR/RGB: Always tune in HSV first. Switch to your target color space afterward to verify consistency
  • ⚖️ Balance over Precision: A mask that's too tight will miss targets in shadows. A mask that's too loose will trigger on UI elements. Aim for the sweet spot.
  • 🔄 Animation Speed: Squares move at 4px/frame. Adjust sliders gradually while watching the binary mask update in real-time.

🐛 Troubleshooting

Issue Solution
Blank/Black window Check console for ❌ Animation error. Verify Pillow is installed
Distractors turning white Reduce Hue/Saturation tolerance. Check if your base color matches the game exactly
Dark squares not detecting Increase Value tolerance. Slightly boost Saturation tolerance (dark colors lose saturation)
Config not loading Ensure config.json contains valid JSON. Use Save As... to generate a fresh template
High CPU usage Close other heavy apps. The animation runs at ~30 FPS intentionally for smooth tuning

📄 License

Provided AS IS with zero liability. Free to modify & distribute for non-commercial use. Must credit Frank1o3. Will never be sold by the author. See LICENSE.md for full terms.