The drawit project contains software that allows blind people to create
simple images. It certainly doesn't have the power of photoshop,
but then again, photoshop is unusable to us.
As so often happens, these programs are also used by sighted people,
who want images that they can tweak by editing an ascii file.
Change the color of this circle, change the location of that line, etc.
These programs can be expanded in their capabilities,
and I certainly welcome ideas and contributions.

Authors: Karl Dahlke and Kevin Carhart.

This software uses the ImageMagick library. Make sure
this library is installed, along with the corresponding development headers.
Appropriate CFLAGS and LDLIBS are in src/makefile.
Well, they are appropriate for the pi that I am working on;
you may need to change them for your platform.

--------------------

The first program is called letterart; source in src/letterart.c.
It takes an ascii file as input and produces an image as output.
The input file contains a matrix of letters.
I sometimes use the .mat suffix for clarity, though that is not strictly necessary.
The letters define rectilinear shapes, as though they were squares pasted together.
In other words, the program draws lines around the shapes,
whenever adjacent letters are different.
Here is a simple example.
With this as input, the output is a tall rectangle on the left,
then another rectangle, then two squares on the right.

abc
abd

letterart chooses the size of the individual squares,
so that the entire matrix fits on a page.
It is centered with a modest white border around.
Use /bin/convert to change the size of the resulting image.

If you are familiar with the Hex™ puzzle, which has been on the market
since the 1960's, you already know the 12 pentominoes well.
They are, in my nomenclature: the line, the L, the Y
(you have to tilt it a little to look like a Y), the C, the stairs, the faucet,
the Utah, the lightning bolt, the zigzag, the T, the cross, and the chair.
The Hex puzzle asks you to tile a 6×10 rectangle with these 12 pieces.
I encountered this puzzle at age 8, and have been fascinated by tiling problems ever since.
I wrote a C program, hexsol.c, to find all solutions,
not just for the 6×10 board, but also the 5×12, 4×15, and 3×20 rectangles.
The latter has only two solutions.
hexsol 8 fills an 8 by 8 board, with the center 2 by 2 square removed, rather like a doughnut.
This has 65 solutions.
The original puzzle, on a 6 by 10 board, has 2339 solutions.
The source, hexsol.c, is in the trec project under eklhad.

hexsol -c
2339 solutions

With the -d option,
this program generates solutions as an ascii matrix, ready for letterart.
Thus a solution to the Hex puzzle might look like this.

EEEIIIDDDJ
EAELIIFDJJ
AAALLFFDKJ
CALLFFGGKJ
CBBBBBHGKK
CCCHHHHGGK

For a sighted person this is not very satisfying.
If the above matrix is in a file calld hex610.mat, invoke the program this way.

letterart hex610.mat png48:hex610.png

The prefix png48: on the output file is important!
On some machines, ImageMagick generates a space saving 8 bit black&white image
format, which most image programs do not recognize.
png48: forces 16 bit RGB, which can be read by every program,
and by every browser, if you wish to put images on your web site.
The picture that goes with the above matrix is in pictures/hex610.png.
Take a moment and look at it, and compare with the above matrix.

letterart foo is shorthand for letterart foo png48:foo.png
Using this shorthand, you won't forget about the png48: prefix.

If you want to extract the individual pieces from the matrix, for machine
analysis, use the m2p perl script. (matrix to pieces)
src/m2p <matrix-file >pieces-file

A possible enhancement to letterart would color the individual pieces,
using the MagickFloodfillPaintImage() function.
A -c option would allow for the colors.
In this case, the letters of the matrix would have meaning: y is for yellow,
b is for blue, g is for green, etc.
For clarity, use the same letter color correspondence as in drawit.c.
I haven't implemented this, but it wouldn't be hard to do.

--------------------

The next program is called colorstates; source in src/colorstates.c.
It creates a map of the United States, where each state is assigned a color.
A political map might show the blue states, the red states, and the purple states.
A map might show the states you have visited, and the states you have lived in.
You choose the colors for this.

The input file contains 51 lines, a line for each state and one for dc.
Each line is the two letter state abbreviation, and a color,
as recognized by the ImageMagick library.
I just pass the color through, so there is a lot of power here.
Consult ImageMagick documentation for the recognized colors.
This example makes Michigan green and Texas orange.
Note that everything is lower case.

mi green
tx orange

The command runs like this:
colorstates foo.txt foo.png
However, you have to have us50.png, the template, in the current directory.
This is in the pictures directory in this project.
You can change the code to use an absolute path, wherever you keep us50.png,
or make a -t template option.

I don't know if you need the png48: prefix on the output file.
Since the template is in png48, the output file probably will be as well.

Here is an example, an illustration of the states that allow felons to vote.
The fifteenth amendment to the Constitution makes it crystal clear.

"The right of citizens of the United States to vote shall not be denied or
abridged by the United States or by any State on account of race, color,
or previous condition of servitude."

Green states restore voting rights as soon as you step out of jail,
and pink states restore voting rights after parole is complete.
Bear in mind, a felon could be on parole for 8 years, so this is not a great solution.
Red states don't restore voting rights at all, unless you jump through
a lot of expensive hoops, and even then it is at the discretion of a review board.
Pink states violate the spirit of the 15th amendment;
red states violate the spirit and the letter of the 15th amendment.
But we don't really care about rights or the Constitution when black people are involved.
See pictures/felonvote.txt and pictures/felonvote.png.
Note, this map is not guaranteed to be up to date.
We can only hope that more states turn green as the moral arc bends slowly.

--------------------

The third and final program is called drawit; source in src/drawit.c.
This program draws a picture, with lines, circles,
ellipses, and colors, based on a line oriented input file.
Blank lines, or lines starting with #, are ignored.
In all other lines, the first character is a command of sorts,
followed by some numeric arguments.
Here is a file that draws a tall black rectangle against a white background.
The semantics are described below.

f50,90
s5,5
d5,85
d45,85
d45,5
d5,5

The first line starts with f, and defines the frame.
The first noncomment line has to be the frame.
The arguments are pixels across and pixels down.
When you refer to coordinates on subsequent lines, make sure they are within your frame.

The s command sets the pencil - where to start drawing.
Arguments are pixels across and pixels down.
As a mathematician, I found this standard a bit jarring.
It does not follow matrix notation, down then across,
nor does it follow the xy plane, which is across then up, with the origin at the lower left.
It is the ImageMagick standard, and we just have to get use to it.
So the second line starts the pencil at 5,5,
5 pixels over and 5 down.

The d command is for draw.
Draw down to 85,5, then over to 45,85,
then up to 45,5, then back to 5,5, which is where we started.
This builds the rectangle on the page.

Certain letters can be used to fill shapes with colors.
All drawing commands must come first, then the color commands.
If you want the above rectangle to be red, do this.

f50,90
s5,5
d5,85
d45,85
d45,5
d5,5
r30,50

r means red, and 30,50 is the point where red begins.
Red spreads out until it runs into the black borders, in this case the rectangle.
Thus the entire tall rectangle is red.
If you want the top half to be red and the bottom half blue,
draw a line in the middle, to cut the rectangle in half,
then use the r and b commands.

f50,90
s5,5
d5,85
d45,85
d45,5
d5,5
s5,45
d45,45
r25,25
b25,65

Color codes are as follows.

b blue
r red
g green
y yellow
p pink
o orange
k black
w white
e purple

The c command draws a circle, specifying the center and radius.

c30,20r12

This moves over 30, down 20, and draws a circle of radius 12, which does indeed fit on the page.
If the circle runs off the page, the portion that is out-of-frame is not drawn.

Mathematicians will again have to adjust, for it doesn't draw a circle,
it draws a disk. The circle and its interior are drawn.
We'll talk about drawing just the circle later; there is a trick.

To draw a green circle, append one of the color codes, like this.

c30,20r12g

Remember, the entire disk of radius 12 is green.
Let's say you want just the green circle, with the background white inside.
Draw a green circle first, then a smaller white circle with the same center.

c30,20r12g
c30,20r9w

Here is a red disk inside a green circle.

c30,20r12g
c30,20r9r

Since ImageMagick can draw ellipses, we can take advantage of that.
The letter s after the radius indicates an ellipse.
Here is an ellipse, centered at 25,30,
with major axis of length 40, and minor axis of length 20.
In other words, it is longer across than it is wide top to bottom.

c25,30r20s10

Remember that the entire ellipse is drawn, including the interior, all black.
Follow up with a color code for a colored ellipse.
Here is the same ellipse but yellow.

c25,30r20s10y

For the border of an ellipse, draw the first ellipse in your favorite color,
then a smaller one with the same center, in white, leaving just the border.

c25,30r20s10o
c25,30r18s8w

Use l instead of s for the lower half of an ellipse,
and u instead of s for the upper half of an ellipse.
Here is the lower half of the ellipse, blue with an orange border.

c25,30r20l10o
c25,30r18l8b

Those are all the capabilities of drawit.
It would be nice to add colored lines, at present all lines are black,
and written words for captions etc.

The command line is as you would expect.
drawit file png48:file.png
Or simply drawit file, which does the same thing.

The drawtest file, in src, exercises these various commands, and includes comments.

--------------------

svg is a drawing language within html.
An image is denoted by the <svg> tag.
This is more complicated than my drawit program, and more powerful.
The picture appears within the context of a web page,
so takes a bit to extract it as a stand alone image.
Many online tutorials are available,
including https://blindsvg.com/, which is written for blind developers.

--------------------

Send questions or feedback to [email protected]