marc
is a tool for visualizing sparse matrices in matrix market format.
For given sparse matrix, it produces an image that displays the density of non-zeroes. Each part of the matrix is colored and the higher the intensity of the color the more non-zeros in that particular region of the matrix there are. Here are some examples:
Typically, sparse matrices are very large, so we can't draw all elements of the matrix, even if they are drawn as one pixel only, since the resulting image would be gigantic. Instead, marc
splits the matrix into square blocks and counts the number of non-zeros in each of them. This way we obtain a grid of blocks that is much smaller and thus results into a much smaller image.
One limitation of this tool is that the precise size of the image can't be guaranteed and the size specified on the command-line is considered as an upper-bound. Meaning the output image is as large as possible while still fitting into the specified area.
Additionally, the aspect ratio of the matrix is preserved only for square matrices. Rectangular matrices might be drawn with a slightly different aspect ratio.
The reason for both of these is that the size of blocks is a whole number and each is drawn as one pixel. So in most cases there is one block size which would result into an image that is too large but the block size one smaller would result into an image that is too small. To have the precise size we would need blocks with fractional size or draw blocks with subpixel precision.
As for the aspect ratio issue. The last block usually "sticks" of the matrix and for rectangular matrices it very likely sticks out by different amounts in each dimension which slightly distorts the aspect ratio.
There are two ways colors can be assigned to blocks. One way is to map each possible occupation of a block to a color, with 0 meaning white and full block meaning the highest intensity. One issue with this is that blocks don't usually contain many non-zeros and their occupation is fairly low, which results into quite dim colors. Nevertheless this is the default setting.
The other option is to adjust the color range to only map to the actual occupation of the blocks. Meaning 0 is still white but now the highest intensity is assigned to the maximum occupation in all of the blocks. This can be turned on using the --adjust-colors
options.
There are no dependencies, the only requirement is a c 17 compiler and cmake.
marc
can be easily built using the standard cmake workflow:
$ mkdir build
$ cd build
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make
If you want to install marc
system-wide you can simple run the following command in the build directory:
$ sudo cmake --install .
If you want to install it to the location of your choice use the --prefix
option:
$ sudo cmake --install . --prefix <prefix>
The marc
executable will by install to <prefix>/bin
.
The basic usage is:
$ marc <input-file> -o <output-file>
The default file format is png
but you can select one of png
, jpg
, bmp
, tga
or svg
using the --output-format
option.
If you don't specify the output filename using the -o
option, the default is out
with a file extension determined by the chosen file format.
Other options include:
-
-v
enables verbose output. -
-w
,--width
and-h
,--height
are used to specify the maximum size of the output image. The image is guaranteed to fit into this area but might be smaller. For more information see the section Image size considerations. If only one dimension is specified the other is computed using the aspect ratio of the matrix. If none of them is specified a default value of 600 by 600 is used. -
-a
,--adjust-colors
can be used to adjust the colors as described in Colors. -
-f
,--output-format
determines the format of the output image. Can be one ofpng
,jpg
,bmp
,tga
orsvg
.