☕ Java Image Manipulator

An intuitive desktop application for fundamental image processing, built with Java Swing.

🧭 Table of Contents

☕ Java Image Manipulator
🧭 Table of Contents
✨ Overview
🚀 Feature Highlights
- Core Manipulations
- User Interface
🏗️ Architecture & Design
🚀 Getting Started
💡 Usage & Workflows
🚫 Limitations, Known Issues & Future Roadmap
🤝 Contributing & Development Guidelines
📄 License, Credits & Contact
📚 Appendix

✨ Overview

The Java Image Manipulator is a lightweight, graphical desktop application designed for performing essential image transformations. It provides a user-friendly interface to load images and apply various manipulations like black & white conversion, inversion, rotation, and resizing.

Purpose & Goals

The primary goal of this project is to serve as an educational and practical example of building a desktop application with Java Swing, demonstrating basic image processing algorithms and UI design patterns. It aims to:

✅ Provide a clear implementation of fundamental image manipulation techniques.
✅ Showcase a modular design for extending image processing capabilities.
✅ Offer an easy-to-use interface for quick, everyday image adjustments.

Why it Matters

In a world increasingly reliant on visual content, the ability to quickly adjust images is invaluable. This application offers a straightforward solution for basic edits without the need for complex, professional software. For developers, it provides an excellent starting point for understanding how to interact with image data in Java and build responsive UIs.

Target Audience

Student Developers: Learning Java, Swing, and basic image processing.
Hobbyists: Looking for a simple tool for quick image adjustments.
Educators: Seeking a clear, open-source example for teaching image manipulation concepts.

⬆️ Back to Top

🚀 Feature Highlights

Here are some of the key capabilities of the Java Image Manipulator:

Core Manipulations

🎨 Black and White Conversion: Convert any colored image to a grayscale representation, emphasizing luminance values.
🔄 Image Inversion: Create a "negative" effect by inverting the color values of each pixel.
↩️ Rotation: Rotate images to any arbitrary angle (0-360 degrees) with smooth interpolation.
📏 Resizing: Adjust image dimensions to fit various display or storage needs.

💡 Tip: The rotation feature uses AffineTransform for high-quality rotations, minimizing pixelation.

User Interface

🖼️ Image Loading: Easily load images from your local file system via a file chooser.
👁️ Live Preview: See the results of your manipulations in real-time as you apply them.
🖱️ Interactive Controls:
- Dedicated buttons for Invert and Black & White.
- A slider for precise control over image rotation angles.
🖥️ Scrollable Display: Handles large images gracefully, allowing you to view them within the application window.

⬆️ Back to Top

🏗️ Architecture & Design

The application follows a modular design, separating UI concerns from image processing logic. This makes it easier to extend with new image manipulation algorithms without heavily impacting the user interface.

Component Diagram

The following diagram illustrates the high-level components and their interactions:

graph TD
    A[ImageManipulatorUI] --> B(ImageManipulator Interface)
    A --> C(Resize Utility)
    A -- "Displays" --> D[BufferedImage]
    B -- "Manipulates" --> D
    C -- "Manipulates" --> D

    subgraph Core Image Manipulations (imgmanip package)
        B1[BlackAndWhite]
        B2[Inversion]
        B3[Rotation]
        B1 --> B
        B2 --> B
        B3 --> B
    end

    subgraph UI Components (ui package)
        A
        C
    end

    style A fill:#cef,stroke:#333,stroke-width:2px;
    style B fill:#f9f,stroke:#333,stroke-width:2px;
    style C fill:#ccf,stroke:#333,stroke-width:2px;
    style D fill:#efe,stroke:#333,stroke-width:2px;

Modules Explained

ui Package (ImageManipulatorUI.java, Resize.java):
- ImageManipulatorUI: This is the main entry point and the graphical user interface of the application. It handles user interactions (loading images, button clicks, slider adjustments) and displays the manipulated image. It orchestrates the application of various ImageManipulator implementations.
- Resize: A utility class within the UI package responsible for handling image resizing operations. It likely provides methods to scale a BufferedImage to new dimensions.
imgmanip Package (ImageManipulator.java, BlackAndWhite.java, Inversion.java, Rotation.java):
- ImageManipulator (Interface): Defines a contract for all image manipulation operations. Any class implementing this interface must provide a manipulate(BufferedImage original) method, ensuring a consistent API for applying transformations.
- BlackAndWhite: Implements ImageManipulator to convert an image to grayscale based on luminance calculation.
- Inversion: Implements ImageManipulator to invert the colors of an image (creating a negative effect).
- Rotation: Implements ImageManipulator to rotate an image by a specified angle using AffineTransform for quality.

Technology Stack

Language: Java
UI Framework: Swing (part of Java SE)
Image Processing: Java AWT (Abstract Window Toolkit) and BufferedImage for pixel manipulation and graphics operations.

⬆️ Back to Top

🚀 Getting Started

Follow these steps to get the Java Image Manipulator up and running on your local machine.

Prerequisites

Before you begin, ensure you have the following installed:

Java Development Kit (JDK): Version 11 or higher.

🔍 Check your Java version: Open your terminal or command prompt and run java -version and javac -version.

Installation

Click to expand detailed installation steps

Clone the repository:
```
git clone https://github.com/GDSC-FSC/Java-Projects.git
cd Java-Projects/ML/Image
```
💡 Tip: If you only need the Image Manipulator, you can navigate directly to the ML/Image subdirectory after cloning the larger Java-Projects repository.
Open in an IDE (Recommended):
- This project contains .iml files, indicating it's structured for IntelliJ IDEA.
- Open IntelliJ IDEA.
- Select File -> Open....
- Navigate to the cloned Java-Projects directory and select it. IntelliJ should automatically detect the modules (Java-Projects.iml, ML/Image/Image.iml) and configure the project.
- Ensure the correct JDK is selected for the project (e.g., File -> Project Structure -> Project SDK).

Manual Compilation (Optional, for advanced users): If you prefer not to use an IDE, you can compile from the command line:

# Navigate to the root of the Image project
cd Java-Projects/ML/Image

# Compile the source files
javac -d out src/imgmanip/*.java src/ui/*.java

# Create a JAR file (optional, for easier distribution)
# First, create a manifest file, e.g., MANIFEST.MF, with the content:
# Main-Class: ui.ImageManipulatorUI
#
# Then run:
# jar cvfm ImageManipulator.jar MANIFEST.MF -C out .

Configuration

This application does not require specific configuration files or environment variables. All settings are managed within the application's source code.

Running the Application

Click to expand running instructions

From an IDE (IntelliJ IDEA):

Open the project in IntelliJ IDEA (as described in Installation).
Navigate to src/ui/ImageManipulatorUI.java.
Right-click on the main method within ImageManipulatorUI.java or on the file itself in the Project Explorer.
Select Run 'ImageManipulatorUI.main()'.
The Image Manipulator UI window should appear.

From the Command Line (after manual compilation):

Ensure you have compiled the project as described in the Installation section.
Navigate to the out directory created during compilation:
```
cd Java-Projects/ML/Image/out
```

Run the application:

java ui.ImageManipulatorUI

If you created a JAR file:

java -jar ImageManipulator.jar

⬆️ Back to Top

💡 Usage & Workflows

Using the Java Image Manipulator is straightforward. Here’s how you can perform basic image edits.

Basic Workflow

Launch the application.
Load an image using the "Load Image" button.
Select a manipulation (Invert, Black and White, Rotate) from the buttons or slider.
Observe the real-time changes in the display area.
(Future: Save the manipulated image.)

Detailed Steps

Starting the Application: Once the application is running, a window titled "Image Manipulator" will appear with a "Load Image" button at the top.
Loading an Image:
- Click the Load Image button.
- A file chooser dialog will open. Navigate to the directory containing your image and select a file (e.g., .jpg, .png).
- Click Open. The selected image will be displayed in the center of the window, and the manipulation buttons will become visible at the bottom.
  
  ⚠️ Important: If your image is very large, it might take a moment to load and render.
Applying Manipulations:
- Invert Colors:
  - Click the Invert button. The image colors will immediately invert, creating a negative effect. Clicking it again will revert to the previous state.
- Black and White:
  - Click the Black and White button. The image will be converted to grayscale. Clicking it again will revert to the original colored image (or the last applied state if other manipulations were active).
- Rotate Image:
  - Adjust the Rotation Slider at the bottom.
  - Moving the slider from 0 to 360 degrees will rotate the image in real-time. The image will rotate around its center point.
- Resizing (if implemented in UI):
  - (Based on Resize.java in ui package, this feature would be accessible via a button or specific input fields in the UI. For now, assume a conceptual interaction if not yet fully integrated into the main ImageManipulatorUI buttons.)
  - If there's a specific button or input for resize, you would typically specify new width/height and apply.

Code Samples (Extending Functionality)

Want to add a new manipulation? It's straightforward thanks to the ImageManipulator interface.

Click to expand example: Adding a new "Blur" effect

Create a new class that implements ImageManipulator in the imgmanip package:

// ML/Image/src/imgmanip/Blur.java
package imgmanip;

import java.awt.image.BufferedImage;
import java.awt.image.ConvolveOp;
import java.awt.image.Kernel;

public class Blur implements ImageManipulator {
    private final float[] blurKernel;
    private final int kernelSize;

    public Blur(int radius) {
        this.kernelSize = radius * 2 + 1;
        this.blurKernel = new float[kernelSize * kernelSize];
        float value = 1.0f / (kernelSize * kernelSize);
        for (int i = 0; i < blurKernel.length; i++) {
            blurKernel[i] = value;
        }
    }

    @Override
    public BufferedImage manipulate(BufferedImage original) {
        Kernel kernel = new Kernel(kernelSize, kernelSize, blurKernel);
        ConvolveOp op = new ConvolveOp(kernel, ConvolveOp.EDGE_NO_OP, null);
        return op.filter(original, null);
    }
}

Integrate into ImageManipulatorUI: Add a new button and its action listener in the createManipulationPanel() method.

// In ui/ImageManipulatorUI.java, inside createManipulationPanel()
// ... other buttons ...

JButton blurButton = new JButton("Blur");
blurButton.addActionListener(e -> {
    if (originalImage != null) {
        // Apply a blur with a radius of 1 (3x3 kernel)
        loadedImage = new Blur(1).manipulate(originalImage);
        displayImage(loadedImage);
    }
});
panel.add(blurButton);

⬆️ Back to Top

🚫 Limitations, Known Issues & Future Roadmap

This application is designed as a learning tool and a basic utility, and as such, it has certain limitations.

Current Limitations

No Save Functionality: The most significant limitation is the inability to save the manipulated image. Users can only view the changes.
Limited Filters: Only a few basic image manipulation filters are available (Black & White, Invert, Rotate, Resize).
No Undo/Redo: There is no history tracking, meaning you cannot undo or redo manipulations. Reverting often means reapplying an opposite effect or reloading the original image.
Basic File Format Support: Relies on Java's default ImageIO capabilities, which might not support all exotic image formats.
No Batch Processing: Manipulations are applied one image at a time.

Known Issues

Performance with Very Large Images: While generally responsive, processing extremely high-resolution images can lead to temporary UI freezes or slower rendering due to direct pixel manipulation on the CPU.
Resize Quality: Depending on the scaling algorithm used in Resize.java, image quality might degrade noticeably when scaling significantly, especially for enlargement. (This depends on the implementation details of Resize.java).

Future Roadmap

Here are some planned enhancements and ideas for future development:

💾 Implement Save Functionality: Allow users to save their manipulated images to various formats (JPG, PNG).
➕ More Filters: Add a wider range of manipulation options:
- Brightness and Contrast adjustments
- Sharpen and additional blur effects
- Cropping functionality
- Color balance adjustments
↩️ Undo/Redo History: Implement a command pattern or similar mechanism for tracking and reverting changes.
🖼️ Enhanced UI:
- Zoom functionality for detailed inspection.
- Drag-and-drop support for loading images.
- Thumbnail previews.
⚡ Performance Improvements: Explore using java.awt.image.ConvolveOp for filter effects and potentially looking into hardware acceleration for very large images.
📦 Batch Processing: Allow applying a series of manipulations to multiple images.

⬆️ Back to Top

🤝 Contributing & Development Guidelines

Contributions are welcome! If you're looking to contribute to this project, please follow these guidelines.

How to Contribute

Fork the repository on GitHub.
Clone your forked repository to your local machine.
Create a new branch for your feature or bug fix (e.g., feature/add-save-button or fix/rotation-bug).
Implement your changes, following the existing code style.
Test your changes thoroughly to ensure they work as expected and don't introduce new issues.
Commit your changes with clear and concise commit messages.
Push your branch to your forked repository.
Open a Pull Request (PR) to the main branch of the original gdsc-fsc/java-projects repository.
- Provide a descriptive title and detailed explanation of your changes in the PR description.
- Reference any related issues.

Branching & Pull Request Guidelines

Main Branch: The main branch is considered stable and deployable. All pull requests should target main.
Feature Branches: All new features and bug fixes should be developed in dedicated branches.
Commit Messages: Use clear, imperative commit messages (e.g., "Add save functionality," not "Added save functionality").
Pull Request Review: All PRs require at least one approving review before merging.

Code Style & Best Practices

Java Code Conventions: Adhere to standard Java code conventions (e.g., Google Java Format or Oracle's conventions).
Readability: Write clean, self-documenting code. Use meaningful variable and method names.
Modularity: Keep classes and methods focused on a single responsibility.
Error Handling: Implement robust error handling where appropriate, especially for file I/O operations.
Comments: Use comments to explain complex logic or design decisions, but prefer self-documenting code where possible.
UI Thread: Be mindful of Swing's single-thread rule for UI updates. Perform long-running tasks in background threads (e.g., SwingWorker) to keep the UI responsive.

⬆️ Back to Top

📄 License, Credits & Contact

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Acknowledgments

GDSC-FSC: For hosting and promoting open-source projects.
Java Community: For providing robust libraries and a supportive ecosystem.
All Contributors: To this and related projects.

Maintainer & Contact

This project is maintained by the GDSC-FSC community. For questions, feedback, or collaborations, please open an issue on the GitHub repository or contact us via:

GitHub: GDSC-FSC/Java-Projects

⬆️ Back to Top

📚 Appendix

Changelog

v1.0.0 (Initial Release) - 2023-10-27

Initial development of core image manipulation features: Black & White, Invert, Rotation.
Basic Swing UI for image loading and displaying manipulations.
Introduction of ImageManipulator interface for extensibility.
Resize utility added (functionality assumed based on file existence).

FAQ (Frequently Asked Questions)

Q: How can I add a new image filter?

A: To add a new filter, create a new Java class in the imgmanip package that implements the ImageManipulator interface. Implement the manipulate(BufferedImage original) method with your desired image processing logic. Then, add a new button or control to the ImageManipulatorUI and call your new manipulator. See the Code Samples section for an example.

Q: Does it support all image formats?

A: The application relies on Java's built-in javax.imageio.ImageIO capabilities. This typically includes common formats like JPEG, PNG, GIF, and BMP. Support for less common or proprietary formats might be limited.

Q: Why can't I save my manipulated images?

A: Save functionality is a planned feature but not yet implemented in the current version. You can only view the changes within the application. We welcome contributions to add this feature!

Q: The UI freezes when I load a very large image or apply complex manipulations. Is this normal?

A: For very large images or computationally intensive operations, a temporary UI freeze can occur because the image processing is performed on the Event Dispatch Thread (EDT). In future versions, we plan to move these operations to background threads (e.g., using SwingWorker) to keep the UI responsive.

Troubleshooting Guide

"Load Image" button doesn't work / No image appears:
- Check the console for any error messages related to file I/O or ImageIO.
- Ensure the selected file is a valid image format (e.g., .jpg, .png).
- Verify that java.io.File has read permissions for the selected image.
Application window doesn't appear after running:
- Ensure your JDK is correctly installed and configured.
- Check your IDE's run configuration or command-line output for errors.
- Verify that ui.ImageManipulatorUI is correctly specified as the main class.
Rotation is slow or pixelated:
- The current rotation uses AffineTransform which should provide decent quality. Performance can be affected by image size and system resources. For extreme rotations or very large images, some visual artifacts might be unavoidable with basic methods.

API Reference (Source Code)

For an in-depth understanding of the application's internals, you can directly browse the source code:

⬆️ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
ML/Image		ML/Image
.gitignore		.gitignore
Java-Projects.iml		Java-Projects.iml
README.md		README.md

GDSC-FSC/Java-Projects

Folders and files

Latest commit

History

Repository files navigation

☕ Java Image Manipulator

🧭 Table of Contents

✨ Overview

Purpose & Goals

Why it Matters

Target Audience

🚀 Feature Highlights

Core Manipulations

User Interface

🏗️ Architecture & Design

Component Diagram

Modules Explained

Technology Stack

🚀 Getting Started

Prerequisites

Installation

Configuration

Running the Application

💡 Usage & Workflows

Basic Workflow

Detailed Steps

Code Samples (Extending Functionality)

🚫 Limitations, Known Issues & Future Roadmap

Current Limitations

Known Issues

Future Roadmap

🤝 Contributing & Development Guidelines

How to Contribute

Branching & Pull Request Guidelines

Code Style & Best Practices

📄 License, Credits & Contact

License

Acknowledgments

Maintainer & Contact

📚 Appendix

Changelog

FAQ (Frequently Asked Questions)

Troubleshooting Guide

API Reference (Source Code)

About

Topics

Resources

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages