UP | HOME

MRaster Quick Start
Linux/UNIX/Msys2/Cygwin/OSX

Copyright © 2024 Mitch Richling. All rights reserved.

Table of Contents

1. Quick Start (The Absolute Minimum WITHOUT Cmake)

If you are interested playing around with MRaster as quickly as possible, then this section is for you.

The first step is to download MRaster and MRMathCPP. The easiest way is to clone them with git: 

git clone 'https://github.com/richmit/mraster.git'
git clone 'https://github.com/richmit/MRMathCPP.git'

Alternatly, you could download the zip files:

Once you have it downloaded, make note of the "lib" folder within each repository containing all the headers. Both libraries are "header only" meaning all you need to to to use them is include the headers. If you are looking for the absolute simplest path forward, just copy the *.hpp files in both "lib" directories into the directory with your code. Alternately, if you are using an IDE, then you can simply "add" the include files to the project in your IDE. Alternately you can direct your build environment to add the "lib" directories to your compiler's "include path". With an IDE that's usually a few clicks away. On the command line, with GCC/Clang, you can add the directories with the -I option.

Here is a very minimal example you can try. Put in a file called "hello.cpp": 

#include "ramCanvas.hpp"                                                     // The main MRaster include

int main(void) {
  mjr::ramCanvas3c8b theRamCanvas(1024, 1024);                               // Create a canvas object
  for(int y=0;y<theRamCanvas.getNumPixY();y++)                               // Run over the rows 
    for(int x=0;x<theRamCanvas.getNumPixX();x++)                             //   and columns of the image
      theRamCanvas.drawPoint(x, y, mjr::color3c8b::csCColdeRainbow::c(x+y)); // Pick a "rainbow" color for the point
  theRamCanvas.writeTIFFfile("hello.tiff");                                  // Write out our image to disk
}

Now we can compile it with GCC like this: 

g++ -m64 -std=gnu++20 hello.cpp -o hello

Now you can run it, and take a look at the file it created ("hello.tiff"):

hello.png

That's it! How easy was that?

1.1. How do I get advanced TIFF reader support without cmake?

If you have libtiff installed in a standard location, then you can probably just add "=-DTIFF_FOUND" to the compile command like this: 

g++ -DTIFF_FOUND -m64 --std=gcc++20 hello.cpp -o hello

Please note that advanced TIFF reader is only required to read TIFF files. MRaster can save TIFF, TGA, and MRAW files without any external library support.

2. Playing With MRaster's Example Programs

Probably the first stop for most people trying out MRaster is the example programs.

MRaster ships with a cmake build system that should be able to interrogate your environment, and produce make files for your OS. One complication is that I've broken the project into two git repositories (one for some generic math stuff and another for MRaster proper). To build the example programs: 

git clone 'https://github.com/richmit/MRMathCPP.git'    # Download MRMathCPP
cd MRMathCPP                                            # Change directory to the root of the MRMathCPP git repository
mkdir build                                             # Create a 'build' directory
cd build                                                # Change directory to the build directory
cmake -G 'MSYS Makefiles' ..                            # Configure the build system with cmake (NOTE 1)
cmake --build . -t install                              # Install the package in the build directory (NOTE 2)
cd ../..                                                # Change directory back to where you cloned the first repo
git clone 'https://github.com/richmit/mraster.git'      # Download MRaster
cd mraster                                              # Change directory to the root of the mraster git repository
mkdir build                                             # Create a 'build' directory
cd build                                                # Change directory to the build directory
cmake -G 'MSYS Makefiles' ..                            # Configure the build system with cmake (NOTE 1)
cmake --build . -t examples                             # Build all the examples
NOTE 1
  • I normally use the "configure.sh" script in the root directory instead of running cmake directly for the configuration step. I don't suggest it above because it won't work for everybody because "configure.sh" is a bash script – i.e. it will only work if you have a working bash envoronmtn (i.e. linux, macOS, UNIX, Windows MSYS 2, Windows WSL, etc…).
  • In the example above we use "MSYS Makefiles" for the "-G" option – this value works for Windows 10/11 running MSYS2.
  • If you don't know what to use for the "-G" option, then take a look at the "configure.sh" script for ideas.
NOTE 2
  • The command will install the cmake package into the build directory within the git repository. In particular, this step will not install anything on your system! If you do want to install the package someplace, then you can use the standard cmake install arguments to do that.
  • This step is not actually necessary. The cmake configuration in MRaster will detect a MRMathCPP repository located at the same level and consume the include files even if the package configuration hasn't been generated or installed. I suggest doing the install because it insures the MRMathCPP can be properly configured on your system, and sets up a proper cmake package to export the library.

3. Platform Notes

3.1. Windows 11 with MSYS2 GCC 12.1.0 (and newer GCCs – tested up to v14.1.0)

Everything works with the following cmake: 

cmake -G 'MSYS Makefiles' -DCMAKE_CXX_COMPILER=g++ ..

3.2. Windows 11 with MSYS2 clang 14.0.6-18 (and newer clangs – tested up to v18.1.6)

Everything works with the following cmake: 

cmake -G 'MSYS Makefiles' -DCMAKE_CXX_COMPILER=clang++ ..

3.3. Windows 11 with MSYS2 cmake and Visual Studio 2022 Community Edition

This method works, but you won't get any external dependencies like GLUT, SDL2, libTIFF, boost, etc… But, you will get enough to run many of the examples.

From the MSYS2 shell, we can run cmake like this: 

cmake -G 'Visual Studio 17 2022' ..

Then open up the directory with explorer, and double click on one of the project files. That will open up VS, and load up the project.

3.4. Windows 11 with Visual Studio 2022 Community Edition

Everything works, but it's harder to get set up. Simply fire up VS, and open the folder with the CMakeLists.txt file in it. VS will detect a cmake project. Next use vcpkg to install GLUT, SDL2, libTIFF, & boost. Update CMakeLists.txt as described here. Refresh the cmake, and you should be able to build.

3.5. Mac OS X Monterey 12.5.1 with Homebrew GCC 12.1.0

I had trouble getting boost to work, but everything else seems OK. Note the -DGLUT_glut_LIBRARY option – this is required to direct cmake to use the Apple provided GLUT instead of freeglut from homebrew.

Here is what I installed via Homebrew: 

brew install gcc
brew install cmake
brew install sdl2
brew install doxygen
brew install libtiff
brew install boost

And I used the following cmake: 

cmake -DCMAKE_CXX_COMPILER=g++-12 -DGLUT_glut_LIBRARY=/System/Library/Frameworks/GLUT.framework ..

3.6. Mac OS X Monterey 12.5.1 with Apple clang 13.1.6

Right now clang doesn't have support for floating point template parameters, and thus the templates csPLY_tpl & csCubeHelix_tpl are not available. This also means that examples using these features are not built:

  • color_lut_poly.cpp
  • color_lut_docs.cpp
  • color_lut_cubehelix.cpp
  • heart2022.cpp

In addition, the Apple version of clang is missing the C++20 feature bit_cast. Right now MRaster has conditional compilation sections removing those features when using this compiler. Hopefully Apple will have better C++20 support soon.

Lastly, note the -DGLUT_glut_LIBRARY option – this is required to direct cmake to use the Apple provided GLUT instead of freeglut from homebrew. 

cmake -DCMAKE_CXX_COMPILER=clang++ -DGLUT_glut_LIBRARY=/System/Library/Frameworks/GLUT.framework ..

3.7. Debian 12.6 bookworm with GCC 13.3.0 (or with the GCC-14 package – tested with version 14.0.1)

This is the stock compiler that comes with bookworm. It's a bit old, but everything seems to work

You can install everything you might want for MRaster like so: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick

Now you can use the following cmake command: 

cmake ..

3.8. Debian bullseye 11.4 with GCC 10.2.1

This is the stock compiler that comes with bullseye. It's a bit old, and is missing support for both floating point template arguments and bit_cast.

You can install everything you might want for MRaster like so: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install cmake/bullseye-backports

Now you can use the following cmake command: 

cmake ..

3.9. Debian bullseye 11.4 with GCC 11.3

With this newer compiler all MRaster features are supported.

This is the compiler currently in the bullseye testing channel for 11.4

Here is my /etc/apt/sources.list file: 

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://security.debian.org/debian-security bullseye-security main
deb http://ftp.debian.org/debian bullseye-backports main

deb http://mirrors.xmission.com/debian/ testing main non-free contrib
deb http://http.us.debian.org/debian testing main contrib non-free
deb http://ftp.us.debian.org/debian testing main non-free contrib

Here is my /etc/apt/preferences file: 

Package: *
Pin: release a=testing
Pin-Priority: 490

You can install everything with the following: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install cmake/bullseye-backports
sudo apt install -t testing g++-11 gcc-11

Now you can use the following cmake command: 

cmake -DCMAKE_CXX_COMPILER=g++-11 ..

3.10. Debian bullseye 11.6 with GCC 12.2

With this newer compiler all MRaster features are supported.

This is the compiler currently in the bullseye testing channel for 11.6

Here is my /etc/apt/sources.list file: 

[sudo] password for richmit:
deb http://deb.debian.org/debian bullseye main
deb-src http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian bullseye-updates main
deb http://security.debian.org/debian-security bullseye-security main


deb http://deb.debian.org/debian testing main
deb-src http://deb.debian.org/debian testing main

Here is my /etc/apt/preferences.d/prefs.pref file: 

Package: *
Pin: release a=stable
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 400

You can install everything with the following: 

sudo apt update
sudo apt upgrade
sudo apt-get install build-essential libsdl2-dev libtiff-dev freeglut3-dev doxygen libboost-all-dev 
sudo apt-get install povray ffmpeg imagemagick
sudo apt install -t testing --install-suggests gcc-12 gfortran-12 cmake

Now you can use the following cmake command: 

cmake -DCMAKE_CXX_COMPILER=g++-11 ..

4. FAQ

4.1. Q1: What's up with "-std=gcc++20" instead of "-std=c++20"?

A: MRaster works just fine with standard C++20 compilers. The "-std=gcc++20" option enables specific features of GCC that make MRaster better. In particular, it enables 128-bit integers on platforms that support it – allowing, for example, a very high performance floating point RGBA image format. If you want to turn off 128-bit integers, and use pure C++20 instead with GCC, then you can use a command line like this: 

g++ -DMJR_LOOK_FOR_128_BIT_TYPES=0 -m64 --std=c++20 hello.cpp -o hello

4.2. Q2: The examples seem to be missing standard/system include files

A: It is good form to place necessary includes in each file that needs them; however, I have violated this sound practice in the examples shipped with MRaster. In particular, because the ramCanvasTpl.hpp and MRcolorTpl.hpp files include just about everything the examples need I have tended to shorten up the examples and depend on the includes from these headers.