{"id":40410757,"url":"https://github.com/vpiotr/uimg","last_synced_at":"2026-01-20T14:08:02.137Z","repository":{"id":139543746,"uuid":"289586665","full_name":"vpiotr/uimg","owner":"vpiotr","description":"Simple drawing library with PPM output","archived":false,"fork":false,"pushed_at":"2025-08-17T22:56:43.000Z","size":874,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-17T23:23:07.940Z","etag":null,"topics":["drawing-primitives","mandelbrot","pixels","ppm","voronoi-diagram"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vpiotr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-23T00:05:16.000Z","updated_at":"2025-08-17T22:56:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"ae616ba9-e39f-4270-b0c5-db01aec91bb9","html_url":"https://github.com/vpiotr/uimg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vpiotr/uimg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpiotr%2Fuimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpiotr%2Fuimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpiotr%2Fuimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpiotr%2Fuimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vpiotr","download_url":"https://codeload.github.com/vpiotr/uimg/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpiotr%2Fuimg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28604712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T12:01:53.233Z","status":"ssl_error","status_checked_at":"2026-01-20T12:01:46.545Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["drawing-primitives","mandelbrot","pixels","ppm","voronoi-diagram"],"created_at":"2026-01-20T14:08:01.384Z","updated_at":"2026-01-20T14:08:02.128Z","avatar_url":"https://github.com/vpiotr.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# uimg - Micro Image Generation Library\n\nA 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.\n\n## Key Features\n\n- **Zero dependencies**: No external libraries required\n- **Cross-platform**: Works on any system with a C++ compiler\n- **Scientific visualization**: Optimized for charts, diagrams, and data visualization\n- **Pixel-level control**: Direct pixel manipulation API\n- **Rich drawing primitives**: Lines, circles, rectangles, ellipses, B-splines, triangles, flood fill\n- **Text rendering**: BDF font support with multi-color text\n- **Image filters**: Comprehensive set of transformation and visual effect filters\n- **Output formats**: PPM image format support\n\n## Quick Start\n\nTo build the project from scratch:\n\n```bash\n./rebuild.sh         # Build everything (demos and tests)\n./build_all_demos.sh # Build all demo applications individually  \n./run_demos.sh       # Run all demo applications\n./run_tests.sh       # Run all tests\n./clean.sh           # Clean all build artifacts\n```\n\nAll binaries are placed in the `build/` directory:\n- Demo executables: `build/demos/`\n- Test executables: `build/tests/`\n\n## Project Structure\n\n```\nuimg/\n├── include/uimg/          # Public API headers\n│   ├── base/             # Core data structures\n│   ├── charts/           # Chart generation utilities\n│   ├── filters/          # Pixel filter transformations\n│   ├── fonts/            # BDF font support\n│   ├── images/           # Image handling (PPM I/O, RGB)\n│   ├── painters/         # Drawing primitives API\n│   ├── pixels/           # Pixel-level API\n│   ├── text/             # Text rendering\n│   └── utils/            # Utility functions\n├── demos/                # Example applications (organized by subdirectory)\n│   ├── 2d_line_chart/    # 2D line chart demo\n│   ├── basic_logging/    # Logging system demo\n│   ├── cast/             # Type casting demo\n│   ├── cast_validation_disabled/ # Cast validation demo\n│   ├── chart3d/          # 3D single chart demo\n│   ├── draw_primitives/  # Drawing primitives showcase\n│   ├── filters/          # Image filters demo (renamed from filter_demo)\n│   ├── mandelbrot/       # Mandelbrot set visualization\n│   ├── multi_chart3d/    # 3D multi-chart demo\n│   ├── observers/        # Observer pattern demo\n│   ├── text/             # Text rendering demo (renamed from text_demo)\n│   ├── voronoi/          # Voronoi diagram generation\n│   └── common/           # Shared demo code and headers\n│       └── include/      # Common headers for demos\n├── tests/                # Unit tests\n├── fonts/                # Sample BDF fonts\n└── images/               # Sample outputs\n```\n\n# Demo Applications\n\nThe library includes several demonstration applications showcasing different capabilities:\n\n## 1. 2D Line Chart Demo\n\nLine chart with customizable options including anti-aliasing for smoother line rendering.\n\n**Source:** [demos/2d_line_chart/main.cpp](demos/2d_line_chart/main.cpp)\n\n**Usage:**\n```bash\n./build/demos/2d_line_chart_demo -font fonts/courR12.bdf -charts 2 -out output.ppm -aa\n```\n\n**Sample output (anti-aliased):**\n\n![2D Line Chart](images/2d_line_chart_aa.png?raw=true)\n\n## 2. 3D Single Chart Demo\n\nBasic 3D surface chart rendering for individual mathematical functions.\n\n**Source:** [demos/chart3d/main.cpp](demos/chart3d/main.cpp)\n\n**Usage:**\n```bash\n./build/demos/chart3d_demo chart3d.ppm\n```\n\n**Sample output:**\n\n![3D single chart](images/chart3d.png?raw=true)\n\n## 3. 3D Multi-Chart Demo\n\nAdvanced 3D surface chart demo with support for multiple functions, layouts, and comprehensive customization. Features include:\n- Support for 1-4 charts displayed simultaneously on a single image\n- Configurable image size and font paths\n- Optional anti-aliasing for smoother line rendering\n- Automatic layout management with special 3-chart layout (bottom chart spans full width)\n- Mathematical formula titles for each chart\n- Dark/light mode themes with borders\n- Several built-in function types (Ripple, Mexican Hat, Gaussian, Peaks, etc.)\n\n**Source:** [demos/multi_chart3d/main.cpp](demos/multi_chart3d/main.cpp)\n\n**Usage:**\n```bash\n# Multi-chart demo with all features (as used in run_demos.sh from build directory)\n./build/demos/multi_chart3d_demo -font fonts/courR12.bdf -size 1024x512 -charts 2 -layout auto -aa -dark -borders multi_chart3d.ppm\n\n# Customizable examples\n./build/demos/multi_chart3d_demo -charts 3 -size 1200x900 output.ppm\n./build/demos/multi_chart3d_demo -charts 4 -layout 2x2 -borders output.ppm\n```\n\n**Sample output (dual charts with dark theme and borders):**\n\n![3D dual chart](images/multi_chart3d_dark_2.png?raw=true)\n\n## 4. Voronoi Diagram\n\nPixel map depicting Voronoi diagram generation.\n\n**Source:** [demos/voronoi/main.cpp](demos/voronoi/main.cpp)\n\n**Sample output:**\n\n![Voronoi diagram](images/voronoi.png?raw=true)\n\n## 5. Mandelbrot Set\n\nPixel map image for selected window of the Mandelbrot set.\n\n**Source:** [demos/mandelbrot/main.cpp](demos/mandelbrot/main.cpp)\n\n**Sample output:**\n\n![Mandelbrot](images/mandelbrot.png?raw=true)\n\n## 6. Drawing Primitives Demo\n\nDemonstration of included primitive shape support including lines, circles, rectangles, ellipses, and other geometric shapes.\n\n**Source:** [demos/draw_primitives/main.cpp](demos/draw_primitives/main.cpp)\n\n**Sample output:**\n\n![Primitives](images/primitives.png?raw=true)\n\n## 7. Text Rendering Demo\n\nDemonstration of BDF font rendering capabilities with multi-color text support.\n\n**Source:** [demos/text/main.cpp](demos/text/main.cpp)\n\n**Usage:**\n```bash\n./build/demos/text_demo -font fonts/courR12.bdf -out text_output.ppm\n```\n\n**Sample output:**\n\n![Text Demo](images/text_demo_output.png?raw=true)\n\n## 8. Filters Demo\n\nDemonstration of various pixel filters including transformations, transparency, zoom, and gradients.\n\n**Source:** [demos/filters/main.cpp](demos/filters/main.cpp)\n\n**Sample output:**\n\n![Filter Demo](images/filter_demo_output.png?raw=true)\n\n## 9. Logging Demo\n\nBasic demonstration of the integrated logging system.\n\n**Source:** [demos/basic_logging/main.cpp](demos/basic_logging/main.cpp)\n\n## 10. Type Casting Demos\n\nDemonstrations of safe type casting utilities:\n- **Cast Demo**: [demos/cast/main.cpp](demos/cast/main.cpp) - Basic casting operations\n- **Cast Validation Disabled**: [demos/cast_validation_disabled/main.cpp](demos/cast_validation_disabled/main.cpp) - Performance-oriented casting\n\n## 11. Observer Pattern Demo\n\nDemonstration of the observer pattern implementation for event handling.\n\n**Source:** [demos/observers/main.cpp](demos/observers/main.cpp) \n\n# Manual Build Process\n\nIf you prefer to build manually or need more control over the build process:\n\n## 1. Create build directory\n\n```bash\nmkdir _build\ncd _build\n```\n\n## 2. Configure with CMake\n\n```bash\ncmake ..\n```\n\n## 3. Build the project\n\n```bash\nmake\n```\n\n## 4. Run a demo\n\n```bash\n./voronoi_demo\n```\n\n# API Reference\n\nThe library provides a layered API architecture. Include the specific header files you need for your use case.\n\n## Core Modules\n\n### Base (`include/uimg/base/`)\n- Core data structures and fundamental types\n- Point, Size, Rectangle classes\n- Color representations (RGB, etc.)\n\n### Pixels (`include/uimg/pixels/`)\n- Low-level pixel manipulation API\n- Direct pixel access and modification\n- Pixel-level drawing operations\n\n### Images (`include/uimg/images/`)\n- **`PixelImage`**: Abstract image interface\n- **`RgbImage`**: In-memory RGB image container\n- **`PpmImageWriter`**: PPM format output\n- **`PpmImageLoader`**: PPM format input\n\n### Painters (`include/uimg/painters/`)\n- High-level drawing API for graphic primitives\n- Lines, circles, rectangles, ellipses\n- B-splines, triangles, flood fill\n- Anti-aliasing support\n\n### Charts (`include/uimg/charts/`)\n- Specialized chart generation utilities\n- 2D line charts\n- 3D surface plots\n- Multi-chart layouts\n\n### Fonts (`include/uimg/fonts/`)\n- **`BdfFont`**: BDF font representation\n- **`BdfGlyph`**: Individual glyph bitmap data\n- **`FontUtils`**: Font loading and management utilities\n- **`TextPainterForBdfFont`**: BDF font rendering\n\n### Text (`include/uimg/text/`)\n- **`TextSource`**: Interface for text content sources\n- **`TextPainter`**: Abstract text rendering interface\n- Text positioning and alignment utilities\n- Multi-color text rendering support\n\n### Filters (`include/uimg/filters/`)\n- **`PixelFilter`**: Base class for all pixel transformations\n- Transformation filters (rotation, flipping, offset, zoom)\n- Visual effect filters (transparency, alpha blending)\n- Gradient filters (linear gradients)\n\n### Utilities (`include/uimg/utils/`)\n- Internal utility functions\n- Type casting utilities\n- Mathematical helpers\n- Observer pattern implementation\n\n# Advanced Features\n\n## Pixel Filters\n\nThe 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.\n\n### Filter Types\n\n#### Transformation Filters\n- **`DiscreteRotationFilter`**: Rotate pixels by discrete angles (-180°, -90°, 0°, 90°, 180°)\n- **`HorizontalFlipFilter`**: Mirror pixels horizontally around a center point\n- **`VerticalFlipFilter`**: Mirror pixels vertically around a center point\n- **`OffsetFilter`**: Move pixels by a specified offset\n- **`ClipFilter`**: Limit drawing operations to a specified rectangular region\n\n#### Visual Effect Filters\n- **`TransparencyFilter`**: Make specific colors transparent\n- **`MaskDiffFilter`**: Apply pixels only where mask differs from specified color\n- **`MaskEqFilter`**: Apply pixels only where mask equals specified color\n- **`AlphaFilter`**: Blend pixels with existing image using alpha transparency\n\n#### Zoom and Scaling Filters\n- **`PixelSpreadFilter`**: Scale pixels with defined center point and zoom factor\n- **`PixelZoomFilter`**: Scale pixels with expansion, filling gaps between pixels\n\n#### Gradient Filters\n- **`GradientFilter2C`**: Apply a linear gradient between two colors\n\n### Using Filters\n\nFilters can be easily combined by chaining. Each filter is initialized with the target painter and its specific parameters:\n\n```cpp\n// Create a base painter\nPixelPainterForRgbImage basePainter(image);\n\n// Apply a horizontal flip filter\nHorizontalFlipFilter flipFilter(basePainter, Point(width / 2, 0));\n\n// Add transparency\nTransparencyFilter transFilter(flipFilter, RgbColor(255, 0, 255));\n\n// Use the filter chain\ntransFilter.putPixel(x, y, color);\n```\n\nThe filter demo application showcases all available filters and their combinations.\n\n## Text Rendering and Font Support\n\nThe 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.\n\n### Features\n- Loading and rendering BDF fonts\n- Multi-color text rendering\n- Precise text positioning\n- Support for text alignment\n- Basic text formatting\n\n### BDF Font Format\n\nThe library uses the BDF (Bitmap Distribution Format) font format:\n\n**Format specifications:**\n- [Wikipedia: Glyph Bitmap Distribution Format](https://en.wikipedia.org/wiki/Glyph_Bitmap_Distribution_Format)\n- [Adobe BDF Specification](https://partners.adobe.com/public/developer/en/font/5005.BDF_Spec.pdf)\n- [X11 Font Description](http://www.linuxfromscratch.org/blfs/view/svn/x/x7font.html)\n\n**Font sources:**\n- [X.org Font Archive](http://ftp.x.org/pub/individual/font/)\n  - Example: `font-adobe-75dpi-1.0.0.tar.gz` contains `courR12.bdf`\n\nSample fonts are included in the `fonts/` directory.\n\n### Text Demo Usage\n\n```bash\n./build/demos/text_demo -font fonts/courR12.bdf -out text_output.ppm\n```\n\n## Getting Started Example\n\nHere's a simple example to get you started:\n\n```cpp\n#include \"uimg/images/RgbImage.h\"\n#include \"uimg/images/PpmImageWriter.h\"\n#include \"uimg/painters/PixelPainterForRgbImage.h\"\n#include \"uimg/painters/LinePainter.h\"\n\nint main() {\n    // Create a 400x300 RGB image\n    uimg::RgbImage image(400, 300, uimg::RgbColor(255, 255, 255));\n    \n    // Create a painter for the image\n    uimg::PixelPainterForRgbImage painter(image);\n    \n    // Draw a red line from (10,10) to (390,290)\n    uimg::LinePainter linePainter(painter);\n    linePainter.drawLine(\n        uimg::Point(10, 10), \n        uimg::Point(390, 290), \n        uimg::RgbColor(255, 0, 0)\n    );\n    \n    // Save to PPM file\n    uimg::PpmImageWriter writer;\n    writer.writeToFile(image, \"output.ppm\");\n    \n    return 0;\n}\n```\n\n# Contributing\n\nContributions are welcome! Please ensure that:\n\n1. All new features include appropriate demo applications\n2. Code follows the existing style and patterns\n3. Tests are included for new functionality\n4. Documentation is updated accordingly\n\n## Testing\n\nRun the test suite with:\n\n```bash\n./run_tests.sh\n```\n\nTests are located in the `tests/` directory and cover:\n- Core functionality validation\n- Logging system tests\n- Type casting utilities\n- Various API components\n\n# License\n\nSee [LICENSE](LICENSE) file for license information.\n\n# Related Projects\n\nFor more advanced plotting and charting capabilities, consider:\n\n- [cpplot](https://github.com/thclark/cpplot) - C++ plotting library\n- [JKQtPlotter](https://github.com/jkriege2/JKQtPlotter/) - Qt-based scientific plotting library\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpiotr%2Fuimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpiotr%2Fuimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpiotr%2Fuimg/lists"}