Skip to content

Latest commit

 

History

History
336 lines (238 loc) · 10.1 KB

README.md

File metadata and controls

336 lines (238 loc) · 10.1 KB

DeepWiki

Pegasus

Give wings to pixels 🪽

A powerful image processing and analysis tool built with Electron and Sharp, featuring an intuitive multi-panel interface for batch image operations.

image

📋 Table of Contents

✨ Features

🖼️ Multi-Panel Interface

  • Horizontal scrollable image panels for easy navigation
  • Multi-select support: Select multiple images using Ctrl + Click
  • Batch operations: Apply transformations to multiple images at once
  • Drag & drop: Load images directly into panels
  • Live preview: See changes in real-time

🎨 Image Processing

  • Resize: Scale images by percentage or pixel width
  • Crop: Interactive cropping with visual feedback
  • Rotate: Arbitrary angles or quick 90° rotations
  • Flip/Flop: Mirror images horizontally or vertically
  • Filters: Blur, sharpen, median, dilate, erode, normalize
  • Color: Grayscale, negative, tint, threshold
  • Watermark: Composite images with transparency
  • Paint: Draw directly on images with adjustable brush

🎬 Advanced Features

  • Animated GIF support with playback controls
  • Color picker: Extract colors from images
  • Undo/Redo: Full history for each image layer
  • Format conversion: Convert between 13+ image formats
  • Keyboard shortcuts: Fast workflow with hotkeys

📦 Requirements

For Development

  • Node.js: v22.18.0 or higher
  • IDE: Visual Studio Code (recommended)
  • Platform: Windows, macOS, or Linux

For End Users

  • Download and install Pegasus Setup.exe from releases
  • No additional dependencies required

🚀 Installation

Development Setup

  1. Clone the repository
git clone https://github.com/Pascal-Institute/pegasus.git
cd pegasus
  1. Install dependencies
npm install
  1. Rebuild native modules
npm run rebuild

User Installation

Simply download and run the installer for your platform from the Releases page.

💻 Development

Run in Development Mode

Windows:

npm start

Linux:

electron . --ozone-platform=x11

Build for Production

npm run build

This creates installers in the output/ directory.

Build for Windows Store

npm run build:win-store

📁 Project Structure

pegasus/
├── core/                   # Core image rendering engine
│   ├── image_renderer.js   # Main UI renderer and panel manager
│   ├── image_layer.js      # Individual image panel component
│   └── pix.js              # Custom .pix format handler
│
├── features/               # Feature modules
│   ├── image_mode.js       # Interaction mode system (crop, draw, etc.)
│   ├── image_layer_events.js  # Event handlers for panels
│   ├── layer_history.js    # Undo/redo implementation
│   └── gif_animation.js    # Animated GIF playback
│
├── processing/             # Image processing logic
│   ├── image_processor.js  # Main processing operations
│   ├── image_loader.js     # File loading and validation
│   └── format_converter.js # Format conversion utilities
│
├── renderer/               # UI renderers for each panel
│   ├── main_renderer.js    # Main application renderer
│   ├── resize_renderer.js
│   ├── crop_renderer.js
│   ├── filter_renderer.js
│   ├── rotate_renderer.js
│   ├── paint_renderer.js
│   └── image_analysis_renderer.js
│
├── pages/                  # HTML panel templates
├── css/                    # Stylesheets
├── components/             # Reusable UI components
├── utils/                  # Utility functions
│   ├── ipc_bridge.js       # IPC communication bridge
│   └── ui_loader.js        # Dynamic UI component loader
│
├── main.js                 # Electron main process
├── image_kit.js            # Public API exports
└── index.html              # Main application window

Key Modules

Core Module

  • ImgKitRenderer: Manages the scrollable container and image panels
  • ImageLayer: Represents each individual image with canvas and controls

Features Module

  • ImageMode: Defines interaction modes (NORMAL, CROPPING, DRAWING, etc.)
  • ModeManager: Handles mode transitions for each layer
  • LayerHistory: Implements undo/redo stack
  • GifAnimation: Controls animated GIF playback

Processing Module

  • ImageProcessor: Pure image processing functions using Sharp
  • ImageLoader: Handles file I/O and format validation
  • FormatConverter: Converts between different image formats

🎮 Usage

Basic Workflow

  1. Load Images: Drag & drop or use File > Open
  2. Select Tool: Click tool buttons (Resize, Crop, Filter, etc.)
  3. Apply Operation: Adjust parameters in the panel
  4. Save: File > Save or Save As

Keyboard Shortcuts

Shortcut Action
Ctrl + A Select all images
Ctrl + Z Undo
Ctrl + Y Redo
Alt + M Toggle magnifying glass
Alt + H Hide current layer
F11 Toggle fullscreen

Multi-Select

  • Select: Click on an image panel
  • Add to selection: Ctrl + Click
  • Deselect: Ctrl + Click on selected panel
  • Visual Feedback: Selected panels show green border

🖼️ Supported Formats

Input/Output Formats

png, jpg, jpeg, webp, gif, bmp, ico, tiff, tif, svg, avif, heif, heic, pix

Special Features

  • ✅ Animated GIF: Full playback controls (play, pause, frame navigation)
  • ✅ PIX format: Custom format for lossless editing
  • ✅ ICC profiles: Preserved during conversion
  • ✅ EXIF data: Metadata preservation

See GIF Animation Documentation for animated GIF details.

🏗️ Architecture

Electron Process Model

Main Process (main.js)
    ├── Creates BrowserWindow
    ├── Handles file dialogs
    ├── Manages IPC communication
    └── Coordinates processing operations

Renderer Process (index.html)
    ├── UI Components (components/)
    ├── Image Panels (core/image_layer.js)
    ├── Event Handlers (features/image_layer_events.js)
    └── Tool Panels (renderer/*.js)

Processing Worker
    └── Sharp-based image operations (processing/)

Data Flow

User Action → Renderer → IPC → Main Process → ImageProcessor → Sharp → Result
                ↑                                                        ↓
                └──────────────── IPC Response ─────────────────────────┘

Module Dependencies

image_kit.js (Entry Point)
    ├── core/image_renderer.js
    │   ├── core/image_layer.js
    │   │   ├── features/image_layer_events.js
    │   │   ├── features/layer_history.js
    │   │   ├── features/gif_animation.js
    │   │   ├── processing/image_processor.js
    │   │   └── processing/image_loader.js
    │   └── features/image_mode.js
    ├── processing/image_processor.js
    │   └── processing/format_converter.js
    └── features/image_mode.js

🛠️ Coding Conventions

  • File naming: Use underscores (resize_panel.js)
  • Classes: PascalCase (ImageProcessor)
  • Functions: camelCase (processImage)
  • Constants: UPPER_SNAKE_CASE (LAYER_EVENT_CHANNEL)

📚 Documentation

🤝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Follow the coding conventions
  4. Submit a pull request

📄 License

See LICENSE file for details.

🙏 Acknowledgments

Built with:

Made with ❤️ by Pascal Institute