PY ImageMapper

PY ImageMapper is a Windows desktop app for creating HTML image maps. Load an image, draw clickable areas (rectangles, circles, polygons), set properties (links, alt text, IDs, CSS classes, data attributes), and export HTML with < img > and < map > < area > tags. It includes zoom/pan, grid/snap, color preferences, project save/load, and hover highlighting in the exported HTML.

Features

• Visual Editor: Draw interactive areas (rectangles, circles, polygons) directly on images
• Area Management: Edit properties for each area including:
  • Name, ID, href (link), alt text, title text
  • Target window (_blank, _self, etc.)
  • CSS class
  • Data attributes (data-*)
  • NoHref option for non-clickable areas
• Project Management: Save and load projects as JSON files
• HTML Export: Generate valid HTML <img> and <map><area></map> code
• Zoom & Pan: Navigate large images with zoom and pan controls
• Grid Support: Optional grid display and snap-to-grid functionality

Requirements

• Python 3.12
• PyQt6 v6.8 or higher

Installation

1. Ensure Python 3.12 is installed
2. Install PyQt6:

   pip install PyQt6

Usage

Running the Application

python main.py

Basic Workflow

1. Open an Image: Click "Open Image" or use File → Open Image to load a PNG, JPG, GIF, or other supported image format.

2. Draw Areas:

   • Select a drawing tool (Rectangle, Circle, or Polygon)
   • For rectangles: Click and drag to define two corners
   • For circles: Click to set center, drag to define radius
   • For polygons: Click to add vertices, double-click to finish

3. Edit Area Properties:

   • Select an area by clicking on it or selecting it from the area list
   • Edit properties in the right panel (name, ID, href, alt, title, target, CSS class, etc.)

4. Set Map Properties:

   • Enter a map name (required for HTML export)
   • Set image alt text and title (optional)

5. Save Project: Use File → Save Project to save your work as a .imagemap file

6. Export HTML: Use File → Export HTML to generate HTML code. You can:

   • Save to a file
   • Copy to clipboard

Keyboard Shortcuts

• Ctrl+N: New Project
• Ctrl+O: Open Project
• Ctrl+S: Save Project
• Ctrl+Shift+S: Save Project As
• Delete: Delete selected area
• Ctrl+Plus: Zoom In
• Ctrl+Minus: Zoom Out
• Space: Hold and drag to pan (when released, returns to normal mode)

Mouse Controls

• Left Click: Select area or start drawing
• Drag: Draw rectangle/circle or move selected area
• Double Click: Finish polygon
• Mouse Wheel: Zoom in/out (hold Ctrl)
• Space + Drag: Pan the canvas

Project File Format

Projects are saved as JSON files with the .imagemap extension. The format includes:

• Image path
• Map name and image attributes
• List of areas with all their properties

Generated HTML Format

The application generates HTML in the following format:

<img src="image.jpg" usemap="#mainmap" alt="Example Map" width="800" height="600">

<map name="mainmap">
  <area shape="rect" coords="34,44,270,350" href="https://example.com" alt="Example Area" id="area1">
  <area shape="circle" coords="400,300,50" href="https://example.org" alt="Circle Area" id="area2">
  <area shape="poly" coords="100,100,200,100,200,200,100,200" href="#" alt="Poly Area" id="area3">
</map>

File Structure

• main.py - Application entry point
• ui_mainwindow.py - Main window UI and logic
• image_canvas.py - Custom widget for displaying image and drawing areas
• models.py - Data models (ImageMapArea, ImageMapProject)
• project_io.py - Project save/load functionality
• html_exporter.py - HTML code generation
• utils.py - Shared utility functions

Notes

• All coordinates are stored in the image's original pixel coordinate system
• The application remembers window size and dock widget positions
• Unsaved changes are tracked and you'll be prompted to save before closing

License

This project is provided as-is for educational and development purposes.