Skip to content

USER_GUIDE.md

Latest commit

 

History

History
321 lines (250 loc) · 10.3 KB

USER_GUIDE.md

File metadata and controls

321 lines (250 loc) · 10.3 KB

PY ImageMapper - User Guide

Table of Contents

  1. Getting Started
  2. Interface Overview
  3. Creating Image Maps
  4. Editing Areas
  5. Project Management
  6. Exporting HTML
  7. Preferences
  8. Keyboard Shortcuts
  9. Tips & Tricks

Getting Started

Launching the Application

Run the application by executing:

python main.py

First Steps

  1. Open an Image: Click "Open Image" in the Tools panel (left side) or use File → Open Image from the menu bar.
  2. Supported Formats: PNG, JPG, JPEG, GIF, BMP, and other common image formats.
  3. Set Map Name: Enter a name for your image map in the "Map Name" field (required for HTML export).

Interface Overview

The application window is divided into several sections:

Left Panel - Tools

  • Image Controls: Open Image button and zoom controls (Zoom In, Zoom Out, Reset)
  • Drawing Tools:
    • Select: Click to select and edit existing areas
    • Rectangle: Draw rectangular areas
    • Circle: Draw circular areas
    • Polygon: Draw custom polygon shapes
  • Finish Polygon: Button to complete polygon drawing (enabled when polygon has 3+ points)

Center - Canvas

The main workspace where your image is displayed and areas are drawn. The canvas supports:

  • Zooming (mouse wheel with Ctrl, or zoom buttons)
  • Panning (hold Space and drag, or middle mouse button)
  • Real-time coordinate display in the status bar

Right Panel - Areas & Properties

  • Area List: Shows all defined areas with their names and shapes
  • Properties Panel: Edit selected area properties:
    • Name, ID, Href (URL), Alt text, Title text
    • Target window (_blank, _self, etc.)
    • CSS class
    • Data attributes
    • NoHref option

Top - Map Properties

  • Map Name: Required identifier for the HTML map
  • Image Alt Text: Alternative text for the image
  • Image Title: Title attribute for the image

Bottom - Status Bar

Displays current mouse coordinates over the image and zoom level.

Creating Image Maps

Drawing Rectangles

  1. Click the Rectangle button in the Tools panel
  2. Click and drag on the canvas to define two opposite corners
  3. Release the mouse to create the rectangle
  4. The area appears with a semi-transparent fill (default: light blue)

Drawing Circles

  1. Click the Circle button in the Tools panel
  2. Click and drag from the top-left corner (like rectangles)
  3. The circle expands as you drag
  4. Release the mouse to finalize the circle

Drawing Polygons

  1. Click the Polygon button in the Tools panel
  2. The cursor changes to a pointing hand
  3. Click on the canvas to place each vertex (corner point)
  4. Continue clicking to add more points
  5. Finish the polygon using one of these methods:
    • Click the Finish Polygon button (enabled when you have 3+ points)
    • Double-click on the canvas
    • Right-click on the canvas
  6. Note: A polygon needs at least 3 points to be valid

Selecting Areas

  • Click the Select tool, then click on an area in the canvas
  • Or click an area name in the Area List
  • Selected areas are highlighted in red (or your custom selected color)

Deleting Areas

  1. Select an area (click it or select from the list)
  2. Press Delete key, or use Edit → Delete Selected Area
  3. The area is removed from both the canvas and the list

Editing Areas

Selecting an Area

  • Click on the area in the canvas, or
  • Click the area name in the Area List on the right

Editing Properties

Once an area is selected, you can edit its properties in the Properties Panel:

  • Name: Internal name for the area (for your reference)
  • ID: HTML id attribute (must be unique)
  • Href: URL or link destination (e.g., https://example.com or #section)
  • Alt Text: Alternative text for accessibility
  • Title Text: Tooltip text shown on hover
  • Target: Link target window:
    • _blank: Opens in new tab/window
    • _self: Opens in same window (default)
    • _parent: Opens in parent frame
    • _top: Opens in full window
  • CSS Class: CSS class name for styling
  • Data Attributes: Custom data attributes (click "Edit Data Attributes" button)
    • Format: key=value, one per line
    • Example: id=123 or category=feature
  • NoHref: Checkbox to make the area non-clickable (no link)

Note: Changes are saved automatically as you type.

Editing Data Attributes

  1. Click the Edit Data Attributes button in the Properties Panel
  2. Enter attributes as key=value pairs, one per line
  3. Example: 
    id=123
category=feature
type=button
  4. Click OK to save

Project Management

Saving Projects

  • Save Project (Ctrl+S): Saves to the current project file
  • Save Project As (Ctrl+Shift+S): Saves to a new file
  • Projects are saved as .imagemap JSON files
  • The application tracks unsaved changes (indicated by * in the window title)

Opening Projects

  • Open Project (Ctrl+O): Opens an existing .imagemap file
  • The application loads:
    • The image file (if it still exists at the saved path)
    • All defined areas with their properties
    • Map name and image attributes

New Project

  • New Project (Ctrl+N): Creates a fresh project
  • You'll be prompted to save if there are unsaved changes

Exporting HTML

Export Process

  1. Ensure you have:
    • At least one area defined
    • A map name set (required)
  2. Go to File → Export HTML...
  3. Choose an option:
    • Save to File: Saves HTML to a file (recommended: save in the same folder as your image)
    • Copy to Clipboard: Copies HTML code to clipboard for pasting

HTML Output

The exported HTML includes:

  • Complete HTML page structure (<!DOCTYPE html>, <html>, <head>, <body>)
  • <img> tag with usemap attribute
  • <map> element with all <area> tags
  • CSS for cursor styling (pointer on hover)
  • JavaScript for visual highlighting (red border on hover)
  • Relative image paths (automatically calculated based on HTML file location)

Image Paths

The application automatically calculates relative paths:

  • If the image is in the same folder as the HTML file: filename.jpg
  • If the image is in a subfolder: /foldername/filename.jpg

Tip: Save your HTML file in the same folder as your image, or in a parent folder, for best results.

Previewing

Open the exported HTML file in a web browser to:

  • See the image map in action
  • Test all clickable areas
  • Verify hover effects (red border highlight and pointer cursor)

Preferences

Accessing Preferences

Go to Edit → Preferences...

Available Settings

Area Color

  • Sets the color for unselected areas (default: light blue)
  • Useful for images with similar colors to improve contrast
  • Click the color button to open a color picker

Selected Color

  • Sets the color for selected areas (default: red)
  • Helps distinguish selected areas from unselected ones
  • Click the color button to open a color picker

Applying Changes

  • Click OK to apply and save preferences
  • Changes are immediately applied to all existing areas
  • Preferences are saved and restored when you restart the application

Keyboard Shortcuts

File Operations

  • Ctrl+N: New Project
  • Ctrl+O: Open Project
  • Ctrl+S: Save Project
  • Ctrl+Shift+S: Save Project As
  • Ctrl+Q or Alt+F4: Exit

Editing

  • Delete: Delete selected area
  • Escape: Cancel current drawing operation

View Controls

  • Ctrl++ or Ctrl+=: Zoom In
  • Ctrl+-: Zoom Out
  • Ctrl+0: Reset Zoom (if available)
  • Space + Drag: Pan the canvas

Mouse Controls

  • Left Click: Select area or start drawing
  • Left Click + Drag: Draw rectangle/circle or pan (if Space is held)
  • Double Click: Finish polygon
  • Right Click: Finish polygon (when drawing)
  • Mouse Wheel: Zoom in/out (hold Ctrl)
  • Middle Mouse + Drag: Pan the canvas

Tips & Tricks

Working with Large Images

  • Use zoom controls to work on detailed areas
  • Hold Space and drag to pan around the image
  • Use View → Fit to Window to see the entire image

Grid Assistance

  • Enable View → Show Grid to see a grid overlay
  • Enable View → Snap to Grid to snap points to grid intersections
  • Useful for precise alignment

Polygon Drawing

  • The cursor changes to a pointing hand when polygon tool is active
  • You need at least 3 points to create a valid polygon
  • The "Finish Polygon" button is enabled once you have 3+ points
  • You can add as many points as needed before finishing

Area Selection

  • Click directly on areas in the canvas to select them
  • Selected areas are highlighted in red (or your custom selected color)
  • Use the Area List to quickly jump to specific areas

Color Customization

  • If your image has colors similar to the default area colors, use Edit → Preferences to change them
  • This improves visibility and contrast

Project Organization

  • Save projects frequently (Ctrl+S)
  • Use descriptive map names
  • Keep image files in accessible locations (relative paths are used in HTML export)

HTML Export Best Practices

  1. Save the HTML file in the same folder as your image (or a parent folder)
  2. Test the exported HTML in a web browser
  3. Verify all links work correctly
  4. Check that hover effects appear as expected

Troubleshooting

  • Image not loading: Check that the image file path is correct
  • Areas not visible: Adjust area colors in Preferences for better contrast
  • Polygon not finishing: Ensure you have at least 3 points before finishing
  • HTML export fails: Make sure you've set a Map Name

Additional Notes

  • All coordinates are stored in the image's original pixel coordinate system
  • The application remembers window size, position, and dock widget layouts
  • Unsaved changes are tracked - you'll be prompted to save before closing
  • The exported HTML includes modern CSS and JavaScript for enhanced interactivity
  • Hover effects (red border and pointer cursor) work in all modern browsers

Support

For issues or questions:

  • Check that Python 3.12 and PyQt6 v6.8+ are installed
  • Ensure image files are in supported formats
  • Verify that map names are set before exporting HTML

Happy Mapping! 🗺️