🖼️ eikon - Image Processing Library

eikon is a lightweight and efficient C++ library designed for those who want to handle image files without wading through a swamp of convoluted frameworks. It lets you load, tweak, and create images effortlessly, with built-in tools for adding geometric shapes. And for command-line lovers, there's a nifty utility that makes image manipulation refreshingly straightforward.

"Make art with code, eikon takes care of the boring stuff"

✨ Features

• Read images: Load image files effortlessly into your application
• Modify Images: Perform image editing operations with ease
• Insert Geometric Shapes: Add lines, rectangles, circles, and more directly into your images
• Command-Line Utility: Use the library directly from the command line for quick tasks
• Custom Testing Framework: For robust and scalable image generation testing
• Dependency-light: Everything is implemented from scratch or is from the standard library
  
  
• Supported formats: BMP PPM PNG

📋 Requirements

• A C++ 20 compiler
• Basic knowledge of C++ and OOP

👨‍💻 Installation

1. Clone the repository:

git clone https://github.com/giovanni-iannaccone/eikon
cd eikon

2. Install the library on your system:

chmod +x build.sh
sudo ./build.sh --install

Follow the installation guide for detailed instructions on how to install a custom library on your system.

Tip

Refer to the latest release to have a stable and fully-working version of eikon

🎨 Usage

• Library Integration
  Include the library in your C++ project:

#include <eikon/eikon.hpp>

• Use predefined shapes
  The library provides a collection of predefined shapes for use in your project:

eikon::Canvas canvas {HEIGHT, WIDTH};

eikon::shapes::Rectangle rec {150, 200, 100, 200, 0xFFA1FF15};
canvas.draw(rec);

Warning

Predefined shapes are designed for speed. If used with incorrect values, they can easily cause segmentation faults. To avoid this situation, use the safe version (e.g., eikon::shapes::SafeRectangle). Use the unsafe version when you know the given input is valid.

• Define your own shapes:
  By using the dependency injection pattern, you can define custom shapes:

class MyShape: public eikon::Drawable {
private:
    int example_var;
    
public:
    MyShape(int value)
        : example_var(value) {}
        
    void draw(eikon::PixelBuffer &pixels) const override {
        // code
    }
}

MyShape myshape = MyShape(VALUE);
canvas.draw(myshape);

Refer to the documentation and ./src/shapes.cpp for the implementation details of the default shapes.

• Execute specific operations on each pixel:
  Use the map method—modeled after Python’s map function—to apply a function to every pixel. This method handles value caching to speed up repetitive, expensive operations. To disable caching, pass false as the second argument.

canvas.map([] (uint32_t &pixel) {
  pixel |= 0xFF;
});

• Apply default methods to modify your image’s appearance:
  Refer to the documentation to learn more about the effects, FX, enhancements, and transformations available in eikon.

• Support for CSS named colors:
  eikon supports all CSS named colors. To use them, simply include:

#include <eikon/colors.hpp>

You’ll then have access to the full set of CSS named colors from the colors enum. If they don’t suit your project, you can always define your own using hex ARGB codes.

• Linking process:
  If you use eikon in your project, remember to add -leikon to g++'s flags.

🧱 Binding

C

To build the library, run make:

cd binding/c && sudo make install

This command will install eikon_wrap on your system. Once installed, you can include the library in your C project and use it as follows:

#include "eikon.h"

int main() {
    Canvas *c = eikon_new_canvas_file("test.bmp");
    
    eikon_circle(c, 50, 400, 400, 0xFF00FF00);
    eikon_add_noise(c, 50);
    eikon_save(c, "test.bmp");
    
    eikon_delete_canvas(c);
    return 0;
}

When compiling your project, don't forget to link the library by adding the -leikon_wrap flag.

🧃 Command Line Utility

1. Compile the CLI tool with cmake:

sudo ./build.sh --cli

2. Interact directly with images using the eikon CLI tool:

./bin/eikoncli --help

Read CLI documentation to know more about eikon utility tool.

Tip

Easly convert images from one format to another

eikoncli -i area.ppm -o area.bmp

3. If you want to use it from anywhere in your system, move the compiled binary to /usr/bin on linux or add it to your PATH on Windows:

sudo mv ./bin/eikoncli /usr/bin

👀 Who can find this helpful ?

Everybody who...

• is willing to learn a new way to create art
• has tried lots of libraries but couldn’t find one that’s easy to use
• likes building things from scratch
• is working on a big project like an image viewer or image editor

🤝 Community

Don’t keep your work to yourself—this community thrives on inspiration, and your project might spark someone else’s next big idea. Whether it’s polished or experimental, we’d love to see what you’ve built with eikon. Share your results, ask questions, give feedback, or just drop by to cheer others on. Every contribution adds to the creative energy here!

🔭 Learn

Read documentation to learn more about eikon implementation and how to properly use it in your C++ project.

• BMP specs
• PNG specs
• PPM specs

🧩 Contributing

We welcome contributing. See CONTRIBUTING.md file for details.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project, you agree to abide by its terms.

Thanks to every contributor

⚖️ License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

⚔️ Contact

• For any inquiries or support, please contact iannacconegiovanni444@gmail.com .
• Visit my site for more informations about me and my work https://giovanni-iannaccone.github.io