How to use the handwriter package
Interested in trying it out yourself?
While we work on something interactive and web-based, you can download the package yourself and give it a try.
The following is a step by step tutorial to help you along the way.
Recently we have been incorporating our research work built on top of handwriter so that you may also use those.
See the Research Pipelines section for more.
Things you'll need:
- The R software environment, downloadable from
The R Project.
You may use this mirror from Iowa State if you wish.
RStudio Desktop, an IDE that should simplify the experience.
- A sample of handwriting in .png format, you can:
- Write something up (black and white works best) and scan it digitally.
Use an online tool like
create and export some handwriting easily.
- Use one of our images to get started.
Terms to know
- Graphs | Often letters, but not always due to the separation algorithm used.
- Index | Top to bottom and left to right, our way of keeping track where a pixel sits on the document as a whole.
Once you have R installed, you'll want to install and load our package from CRAN using:
Get your image as a .png (we'll use this one, available
Once you have that, read in the image:
The image is also cropped as part of this process.
csafe = list()
csafe$image = readPNGBinary("path/to/the/picture.png")
Preparing the image for processing
Plot the original, cropped image:
thin the image and you can plot it again:
csafe$thin = thinImage(csafe$image)
Processing the image exploring the results
Process the image
csafe_processlist = processHandwriting(csafe$thin, dim(csafe$image))
processHandwriting() will return tons of information about the document. It is worth exploring, and we've provided a handy list here of what each element of the list means
On a document level:
- nodes | A list of all 'points of interest'
- connectingNodes | A list of all nodes where graphs connect
- terminalNodes | A list of all nodes where a path in a graphs ends
- breakPoints | A list of calculated points to break graphs apart (based on connectingNodes)
As well as a letterList for each letter/graph that includes:
- path | A list of all points
- nodes | A list of all 'points of interest'
- allPaths | A list of lists of calculated 'paths'
- adjMatrix | Adjacency matrix
- letterCode | A unique letter code
- connectingNodes | A list of all nodes where the graph connects
- terminalNodes | A list of all nodes where a path in the graph ends
- characterFeatures | A list of all 'points of interest' in the document
- aspect_ratio | Height to width ratio
- height | Height of the graph, measured in pixels
- width | Width of the graph, measured in pixels
- topmost_row | The top-most row, as its y coordinate
- bottom_row | The bottom-most row, as its y coordinate
- leftmost_col | The left-most column, as its x coordinate
- rightmost_col | The left-most column, as its x coordinate
- centroid_index | The centroid of the graph, as its index
- centroid_y | The y coordinate of the centroid
- centroid_x | The x coordinate of the centroid
- centroid_horiz_location |
- centroid_vert_location |
- lHalf | List of all points on the left half of the graph
- rHalf | List of all points on the right half of the graph
- disjoint_centroids | The centroids of the left and right halves, as their idicies
- slope | The slope of the graph as it runs through the centroid
- pixel_density |
- box_density |
- uniqueid | A unique numerical identifier for the graph
- down_dist | Distance from the lowest point of a graph to the next graph, measured in pixels
- line_number | The position of the graph in the line
- order_within_line | The ordered within the line the graph falls in
- l_neighbor_dist | Distance from the left-most point in the graph to its left neighbor, measured in pixels
- r_neighbor_dist | Distance from the right-most point in the graph to its left neighbor, measured in pixels
- xvar | Variance of X, used to calculate the covariance in covar
- yvar | Variance of Y, used to calculate the covariance in covar
- covar | Covarience of the graph
- wordIndex | Word number the graph belongs to
Exploring processed writing
Using the information returned from processHandwriting(), Handwriter allows plotting on a letter (or graph), word, sentence, or the entire document.
Make sure to save this information so that the plotting functions work correctly
csafe$nodes = csafe_processlist$nodes
csafe$breaks = csafe_processlist$breakPoints
dims = dim(csafe$image)
Also included is the ability to plot individual graphs from the sample of writing, using
plotLetter(). First lets look at the parameters and options, and then run through a few examples.
The parameters include:
The index of the graph you wish to plot
OPTIONAL: Boolean - Number the paths within the graph
OPTIONAL: Boolean - Plot the centroid of the graph
OPTIONAL: Boolean - Plot the slope of the graph
The following will result in the first graph being plotted with all optional paramters:
plotLetter(csafe_processList$letterlist, 1, dims)
#Note: No optional parameters specified is the same as:
#plotLetter(csafe_processlist$letterList, 1, dims, TRUE, TRUE, TRUE)
This will plot the fifth graph with just the slope and centroid:
plotLetter(csafe_processlist$letterList, 5, dims, FALSE, TRUE, TRUE)
To plot words, a little bit of extra processing must be done:
words = create_words(csafe_processList)
words_after_processing = process_words(words, dim(csafe_document$image), TRUE)
Then you can plot just the word with plotWord
plotWord(csafe_processList$letterList, 1, dims)
Or optionally, use the plotColorNodes function to show some additional information.
plotColorNodes(csafe_processList$letterList, 1, dims, words_after_processing)
Plot the line, where the second parameters is the line_number
plotLine(csafe_processList$letterList, 1, dims)
Plot the original, cropped image
Plot the thinned image
Plot all nodes found during processing
plotNodes(csafe$image, csafe$thin, csafe$nodes)
Plot all graph breaks found during processing
plotNodes(csafe$image, csafe$thin, csafe$breaks)
K-means Clustering | Perform K-means clustering on a graph level | Read more
Triangle Decomposition | Perform triangle decomposition on a word level | Read more