A minimal, independent C++ library for basic scientific diagram generation and image processing. The library is designed to be portable and self-contained, with no dependencies on external libraries or operating system-specific APIs.
- Zero dependencies: No external libraries required
- Cross-platform: Works on any system with a C++ compiler
- Scientific visualization: Optimized for charts, diagrams, and data visualization
- Pixel-level control: Direct pixel manipulation API
- Rich drawing primitives: Lines, circles, rectangles, ellipses, B-splines, triangles, flood fill
- Text rendering: BDF font support with multi-color text
- Image filters: Comprehensive set of transformation and visual effect filters
- Output formats: PPM image format support
To build the project from scratch:
./rebuild.sh # Build everything (demos and tests)
./build_all_demos.sh # Build all demo applications individually
./run_demos.sh # Run all demo applications
./run_tests.sh # Run all tests
./clean.sh # Clean all build artifactsAll binaries are placed in the build/ directory:
- Demo executables:
build/demos/ - Test executables:
build/tests/
uimg/
├── include/uimg/ # Public API headers
│ ├── base/ # Core data structures
│ ├── charts/ # Chart generation utilities
│ ├── filters/ # Pixel filter transformations
│ ├── fonts/ # BDF font support
│ ├── images/ # Image handling (PPM I/O, RGB)
│ ├── painters/ # Drawing primitives API
│ ├── pixels/ # Pixel-level API
│ ├── text/ # Text rendering
│ └── utils/ # Utility functions
├── demos/ # Example applications (organized by subdirectory)
│ ├── 2d_line_chart/ # 2D line chart demo
│ ├── basic_logging/ # Logging system demo
│ ├── cast/ # Type casting demo
│ ├── cast_validation_disabled/ # Cast validation demo
│ ├── chart3d/ # 3D single chart demo
│ ├── draw_primitives/ # Drawing primitives showcase
│ ├── filters/ # Image filters demo (renamed from filter_demo)
│ ├── mandelbrot/ # Mandelbrot set visualization
│ ├── multi_chart3d/ # 3D multi-chart demo
│ ├── observers/ # Observer pattern demo
│ ├── text/ # Text rendering demo (renamed from text_demo)
│ ├── voronoi/ # Voronoi diagram generation
│ └── common/ # Shared demo code and headers
│ └── include/ # Common headers for demos
├── tests/ # Unit tests
├── fonts/ # Sample BDF fonts
└── images/ # Sample outputs
The library includes several demonstration applications showcasing different capabilities:
Line chart with customizable options including anti-aliasing for smoother line rendering.
Source: demos/2d_line_chart/main.cpp
Usage:
./build/demos/2d_line_chart_demo -font fonts/courR12.bdf -charts 2 -out output.ppm -aaSample output (anti-aliased):
Basic 3D surface chart rendering for individual mathematical functions.
Source: demos/chart3d/main.cpp
Usage:
./build/demos/chart3d_demo chart3d.ppmSample output:
Advanced 3D surface chart demo with support for multiple functions, layouts, and comprehensive customization. Features include:
- Support for 1-4 charts displayed simultaneously on a single image
- Configurable image size and font paths
- Optional anti-aliasing for smoother line rendering
- Automatic layout management with special 3-chart layout (bottom chart spans full width)
- Mathematical formula titles for each chart
- Dark/light mode themes with borders
- Several built-in function types (Ripple, Mexican Hat, Gaussian, Peaks, etc.)
Source: demos/multi_chart3d/main.cpp
Usage:
# Multi-chart demo with all features (as used in run_demos.sh from build directory)
./build/demos/multi_chart3d_demo -font fonts/courR12.bdf -size 1024x512 -charts 2 -layout auto -aa -dark -borders multi_chart3d.ppm
# Customizable examples
./build/demos/multi_chart3d_demo -charts 3 -size 1200x900 output.ppm
./build/demos/multi_chart3d_demo -charts 4 -layout 2x2 -borders output.ppmSample output (dual charts with dark theme and borders):
Pixel map depicting Voronoi diagram generation.
Source: demos/voronoi/main.cpp
Sample output:
Pixel map image for selected window of the Mandelbrot set.
Source: demos/mandelbrot/main.cpp
Sample output:
Demonstration of included primitive shape support including lines, circles, rectangles, ellipses, and other geometric shapes.
Source: demos/draw_primitives/main.cpp
Sample output:
Demonstration of BDF font rendering capabilities with multi-color text support.
Source: demos/text/main.cpp
Usage:
./build/demos/text_demo -font fonts/courR12.bdf -out text_output.ppmSample output:
Demonstration of various pixel filters including transformations, transparency, zoom, and gradients.
Source: demos/filters/main.cpp
Sample output:
Basic demonstration of the integrated logging system.
Source: demos/basic_logging/main.cpp
Demonstrations of safe type casting utilities:
- Cast Demo: demos/cast/main.cpp - Basic casting operations
- Cast Validation Disabled: demos/cast_validation_disabled/main.cpp - Performance-oriented casting
Demonstration of the observer pattern implementation for event handling.
Source: demos/observers/main.cpp
If you prefer to build manually or need more control over the build process:
mkdir _build
cd _buildcmake ..make./voronoi_demoThe library provides a layered API architecture. Include the specific header files you need for your use case.
- Core data structures and fundamental types
- Point, Size, Rectangle classes
- Color representations (RGB, etc.)
- Low-level pixel manipulation API
- Direct pixel access and modification
- Pixel-level drawing operations
PixelImage: Abstract image interfaceRgbImage: In-memory RGB image containerPpmImageWriter: PPM format outputPpmImageLoader: PPM format input
- High-level drawing API for graphic primitives
- Lines, circles, rectangles, ellipses
- B-splines, triangles, flood fill
- Anti-aliasing support
- Specialized chart generation utilities
- 2D line charts
- 3D surface plots
- Multi-chart layouts
BdfFont: BDF font representationBdfGlyph: Individual glyph bitmap dataFontUtils: Font loading and management utilitiesTextPainterForBdfFont: BDF font rendering
TextSource: Interface for text content sourcesTextPainter: Abstract text rendering interface- Text positioning and alignment utilities
- Multi-color text rendering support
PixelFilter: Base class for all pixel transformations- Transformation filters (rotation, flipping, offset, zoom)
- Visual effect filters (transparency, alpha blending)
- Gradient filters (linear gradients)
- Internal utility functions
- Type casting utilities
- Mathematical helpers
- Observer pattern implementation
The library provides a rich set of pixel filter transformations through the PixelFilter class hierarchy. These filters can be chained together to create complex transformations and visual effects.
DiscreteRotationFilter: Rotate pixels by discrete angles (-180°, -90°, 0°, 90°, 180°)HorizontalFlipFilter: Mirror pixels horizontally around a center pointVerticalFlipFilter: Mirror pixels vertically around a center pointOffsetFilter: Move pixels by a specified offsetClipFilter: Limit drawing operations to a specified rectangular region
TransparencyFilter: Make specific colors transparentMaskDiffFilter: Apply pixels only where mask differs from specified colorMaskEqFilter: Apply pixels only where mask equals specified colorAlphaFilter: Blend pixels with existing image using alpha transparency
PixelSpreadFilter: Scale pixels with defined center point and zoom factorPixelZoomFilter: Scale pixels with expansion, filling gaps between pixels
GradientFilter2C: Apply a linear gradient between two colors
Filters can be easily combined by chaining. Each filter is initialized with the target painter and its specific parameters:
// Create a base painter
PixelPainterForRgbImage basePainter(image);
// Apply a horizontal flip filter
HorizontalFlipFilter flipFilter(basePainter, Point(width / 2, 0));
// Add transparency
TransparencyFilter transFilter(flipFilter, RgbColor(255, 0, 255));
// Use the filter chain
transFilter.putPixel(x, y, color);The filter demo application showcases all available filters and their combinations.
The library provides a comprehensive text rendering system using BDF fonts. Text rendering is implemented through the uimg::TextSource interface and the uimg::TextPainter abstract class. The concrete implementation uimg::TextPainterForBdfFont handles rendering for BDF fonts.
- Loading and rendering BDF fonts
- Multi-color text rendering
- Precise text positioning
- Support for text alignment
- Basic text formatting
The library uses the BDF (Bitmap Distribution Format) font format:
Format specifications:
Font sources:
- X.org Font Archive
- Example:
font-adobe-75dpi-1.0.0.tar.gzcontainscourR12.bdf
- Example:
Sample fonts are included in the fonts/ directory.
./build/demos/text_demo -font fonts/courR12.bdf -out text_output.ppmHere's a simple example to get you started:
#include "uimg/images/RgbImage.h"
#include "uimg/images/PpmImageWriter.h"
#include "uimg/painters/PixelPainterForRgbImage.h"
#include "uimg/painters/LinePainter.h"
int main() {
// Create a 400x300 RGB image
uimg::RgbImage image(400, 300, uimg::RgbColor(255, 255, 255));
// Create a painter for the image
uimg::PixelPainterForRgbImage painter(image);
// Draw a red line from (10,10) to (390,290)
uimg::LinePainter linePainter(painter);
linePainter.drawLine(
uimg::Point(10, 10),
uimg::Point(390, 290),
uimg::RgbColor(255, 0, 0)
);
// Save to PPM file
uimg::PpmImageWriter writer;
writer.writeToFile(image, "output.ppm");
return 0;
}Contributions are welcome! Please ensure that:
- All new features include appropriate demo applications
- Code follows the existing style and patterns
- Tests are included for new functionality
- Documentation is updated accordingly
Run the test suite with:
./run_tests.shTests are located in the tests/ directory and cover:
- Core functionality validation
- Logging system tests
- Type casting utilities
- Various API components
See LICENSE file for license information.
For more advanced plotting and charting capabilities, consider:
- cpplot - C++ plotting library
- JKQtPlotter - Qt-based scientific plotting library