UP | HOME

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:

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 optimize MRaster performance. Before the conversion to C++20, colorTpl made up about 80% of the code base – yes larger than ramCanvasTpl 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 the colorTpl 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 make MRaster 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
  • 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.

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.