AOI Area Calculator (v2.2)
========================================

Created by Laurens (Tobii Strategic Sales Team)
Experimental PoC, unofficial tool – not supported by Tobii

----------------------------------------
Purpose
----------------------------------------
The AOI Area Calculator is a lightweight desktop tool designed to help researchers and analysts quickly calculate and visualize the surface area coverage of Areas of Interest (AOIs) exported from Tobii Pro Lab.

It provides a simple and visual way to understand how large each AOI is relative to the total image area, which can be useful for:

- Weighting metrics based on AOI size
- Comparing AOI coverage across multiple images or sessions
- Checking AOI consistency across datasets
- Generating clear visualizations for reports and presentations

Note: The tool assumes images are photographed or captured head-on. If the image has strong perspective distortion (e.g., angled shelves), AOI proportions may appear slightly skewed.

----------------------------------------
Key Features
----------------------------------------
Core Analysis
- Calculates exact AOI surface area (in pixels) using the Shoelace Formula
- Computes each AOI’s coverage (%) relative to the total image area
- Supports loading multiple AOI files (.aois) at once for comparison
- Generates an Excel report with a separate sheet per image, plus a summary tab
- Displays total AOI coverage per image

Interactive Preview
- Preview AOIs visually on the original snapshot image
- Draggable AOI labels – move them freely (even outside the image) for readability
- Customizable label font, color, and background
- Adjustable AOI border color, style, width, and transparency
- Fit to Window scaling for large, high-resolution images
- Export annotated image as transparent PNG or high-quality JPG
  (The exported view matches the on-screen preview)

Usability & Customization
- Saved settings persist between sessions
- Sortable columns in the results table
- Copy results to clipboard for quick pasting into Excel or reports
- Clean interface with progress feedback and error handling

----------------------------------------
How It Works
----------------------------------------
1. In Tobii Pro Lab, open your AOI setup or snapshot.
2. Right-click your AOI set and choose Export AOIs → Save as ".aois" file.
3. Launch AOI Area Calculator.
4. Click “Select AOIS Files”.
5. Choose one or multiple ".aois" files to process.
6. When prompted, select a location and name for the Excel output file.
7. The tool automatically:
   - Parses each AOI file
   - Calculates AOI surface areas and percentages
   - Exports everything to Excel
   - Displays a sortable summary in the app
8. To preview a specific file visually:
   - Click any row in the list from the .aois file that matches the image
   - Press “Preview AOI”
   - When prompted, select the associated image file (PNG/JPG) from your snapshot
9. Adjust label and AOI appearance from:
   - Label Settings
   - AOI Settings
   - General Settings
10. Optionally export the preview image (PNG/JPG) for reporting.

----------------------------------------
Output Example
----------------------------------------
Excel File:
- One sheet per .aois file (named after the image)
- Columns: File Name | AOI Name | Surface Area (px) | Area (%)
- “Summary” sheet includes total AOI coverage per image

Preview Export (PNG/JPG):
- AOIs drawn in your chosen color and style
- Labels positioned as in the preview window
- Transparent background (PNG) or black background (JPG)
- Entire visible area exported, including labels outside the image

----------------------------------------
Customization Options
----------------------------------------
Label Settings
  - Font family, size, color, background
  - Font weight: normal or bold
  - Move labels freely in the preview

AOI Settings
  - Line color, width, and style (solid or dotted)
  - Fill option (semi-transparent 50%)

General Settings
  - Decimal places for precision
  - Sheet name length for Excel

----------------------------------------
Tips
----------------------------------------
- Use “Fit to Window” feature for large images in the Preview function.
- Drag labels outside AOIs or even outside the snapshot image completely (will automatically expand canvas) to declutter visuals.
- PNG exports keep transparency outside the image.
- If your exported image looks black or wrong, ensure your snapshot is a valid image and displays well in other image viewers.

----------------------------------------
FAQ
----------------------------------------
Q: Can I analyze AOIs without an image file?
A: Yes. Calculations work without the image, but previews require one.

Q: Does this modify my AOIs or Pro Lab data?
A: No. The tool only reads .aois files and exports results externally.

Q: My labels overlap. Can I move them?
A: Yes – click and drag the label in Preview. It will stay there even after export.

Q: Can I update or modify the tool?
A: The software is offered fully Open Source, feel free to adjust the included Python script but please keep credits in place. 

----------------------------------------
Disclaimer
----------------------------------------
This tool is experimental and provided as-is as Proof of Concept of how .aois file export can be used.
It is not official Tobii software and not supported by Tobii.

Feedback & bug reports are welcome to: 
Laurens van den Broek 
Email: lvk@tobii.com