MRaster
Copyright © 2024 Mitch Richling. All rights reserved. |
Table of Contents
1. Introduction
From the README:
1.1. Introduction
MRaster is a very simple C++ library for generating raster images – espeically things like fractals.
It is designed to be easy enough for beginners, but advanced enough for experts. It integrates well into existing code, uses pure C++20, requires no external dependencies, and is quite fast.
Some examples of what can be done with MRaster:
- Mandelbrot Mountains
- Newton Fractal
- Burning Ship
- Multibrot Fractals
- Mandelbrot Iteration Movie
- Tricorn Fractal
- Collatz Fractal
- Tippets Fractal
- Dancing Biomorphs
- Pickover Popcorn
- Mandelbrot Biomorph
- Inverted Mandelbrot
- Mandelbrot Wave
- Peter de Jong Fractal
- Symmetric Fractals
- Tinkerbell
- Hopalong Fractals
- Chaos Game
- Chaos Game Levy Curve
- Apollonian Gasket
- Attracting Torus
- Julia Sets
- Circle Art
- Some desktop backgrounds
For a bit more detail about MRaster: https://richmit.github.io/mraster/index.html
A quick start guide: https://richmit.github.io/mraster/QuickStart.html
Color schemes included in MRaster: https://richmit.github.io/mraster/ColorSchemes.html
API Documentation: https://www.mitchr.me/SS/mraster/doc-lib/autodocs/html/index.html
Example Documentation: https://www.mitchr.me/SS/mraster/doc-examples/autodocs/html/index.html
The code: https://github.com/richmit/mraster/
1.2. Versions
This library has defined "releases" intended to identify a stable snapshot of the code – they are tagged in git with a tag name starting with a "v". If you are looking for stability, then get the latest one.
That said, I try to only commit complete, working code. So I think
it's pretty safe for most people to just pull HEAD
– i.e. just do a
regular git clone.
The change log
has entries for each release as well as a section for what has changed
on HEAD
since the last release.
2. Design goals
- Extreme portability (ISO C++20 only, no third party library requirements)
Note the code is broken across two git repositories – one for MRaster proper and one for some simple mathematical utilities. In older versions of MRaster these mathematical routines were included in the repo; however, I have pulled them out because they are generally useful by themselves. - Super simple and easy to use, but full featured enough for an expert to be happy with
My goal was to be able to hand this package to a student with minimal C++ experience, and have them be able to create a Mandelbrot image in an few minutes. For the most part my students were very successful! - Easy integration with existing code and libraries
The idea is to make the classes adapt to the setting in which they are being used, and not to force programmers to adapt. For example, colors may be set via naive types, numeric characters, hex strings, web color hex strings, name strings, enumerated corner names, symbolic characters, or floating point numbers. As another example points for drawing functions be be provided as coordinate pairs, point objects, complex numbers, tuples, arrays, etc… - Extreme flexibility and high performance
In general, many operations are optimized for the specific image layout and type. For example a small, integer based color may be treated in RAM as a single packed integer while larger colors may be treated as an array of channels. As another example,colorTpl
member functions will pass a color by value if it is small (like a 24-bit RGB color), and by const reference if it large (like a 192-bit RGB color). In addition the code is carefully structured to allow the optimizer to do as much compile time optimization as possible. - No Explicit Limits
Image size, channel depth, and channel count are limited only by available RAM. - Sophisticated color API via a zero cost, object based pixel store
MRaster
is an outlier among image libraries in that pixels are objects. These objects deliver a very rich API for color theory computations, color schemes, transformations, etc… And they do so with zero overhead in RAM or runtime performance. In fact, these templated objects are one of the primary tools used to optimizeMRaster
performance. Before the conversion to C++20,colorTpl
made up about 80% of the code base – yes larger thanramCanvasTpl
even with the complexity of the scanline conversion code in the canvas object. - High reliability
The library is very mature and has been in published since 1991. While the code has undergone major rewrites in that time, each rewrite has been regression tested against the previously stable version. More recently, an extensive unit test suite has been built up against thecolorTpl
class. - Mathematical Use cases
Images have both real & integer coordinates, so they may be thought of as part of the real plane. In addition a great many discrete and continuous color schemes are supported. Together these features makeMRaster
a very friendly environment for mathematically oriented visualization – stuff like drawing Mandelbrot set fractals. - 100% focus on raster graphics synthesis
This is kind of a non-feature. We simply don't try to do things like anti-aliasing, vector graphics, or FFT based image processing. What we do:
- Manipulate pixels!
- Efficient primitive scanline conversion and clipping including Old school "pixel paint" techniques (set, xor, and, etc….)
3. Who is using it, and what are they using it for?
While I can't know what everyone uses it for, many users have shared with me how they use MRaster
.
- The majority of
MRaster
users are doing direct image synthesis for mathematical visualization.- Raster based fractals like the Mandelbrot set
MRaster
is used for some university non-linear dynamics courses, generating a higher user count than I expected. - Strange attractor projections, incidence histograms, bifurcation plots, etc…
- Complex function phase portraits
- Making color schemes for other graphics tools
- Producing POV-ray Maps and Height fields
- Raster based fractals like the Mandelbrot set
- Visualizations in HPC (supercomputer) environments. For large 2D fields,
MRaster
can be a less complex and more efficient alternative to traditional visualization tools. - Scientific images (astronomy and microscopy mostly) with very high depth and/or channel count.
- Satellite and other hyperspectral remote-sensing imagery with crazy numbers of channels.
- The last sizable group of
MRaster
users makes no use of the "raster" part. ;)- Many developers use the
colorTpl
template for color theory computations with other graphics libraries. - Quite a few people use
colorTpl
for creating color schemes for visualizations created in other tools.
- Many developers use the
4. Perhaps more important is what people don't use it for.
What don't we do with MRaster
? Frankly, the non-features are features – i.e. we don't do things that we are not good at or things for which other
libraries are better.
- Anti-aliased primitive rendering.
- Sophisticated font rendering.
- Very little support for non-homogeneous image processing transforms.
- No 3D – but
MRaster
makes for a fantastic back end for 3D rendering tools.
Most of these things can be better achieved via other libraries:
- Cairo – My favorite vector graphics library.
- ImageJ – One of my favorite image analysis & processing platforms.
- ImageMagick – A veritable Swiss army knife for batch image processing.
- VTK – Comprehensive 3D data visualization library.