Class WordCram

wordcram
Class WordCram
java.lang.Object
wordcram.WordCram

public class WordCram
extends java.lang.Object
The main API for WordCram.
There are three steps to making a WordCram:

weight your words
style your words
draw your WordCram
You start with a new WordCram(this), and then…
Step One: Weight Your Words
Give WordCram some text to chew on, or an array of Words you’ve weighted yourself.
Let WordCram Weight Your Words
WordCram weights your words by the number of times they appear in a document. It can load the document a few ways:

fromWebPage(String) and fromHtmlFile(String) load the HTML and scrape out the words
fromHtmlString(String…) takes a String (or String[]), assumes it’s HTML, and scrapes out its text
fromTextFile(String) loads a file (from the filesystem or the network), and counts the words
fromTextString(String…) takes a String (or String[]), and counts the words
If you need some other way to load your text, pass your own TextSource to fromText(TextSource), and WordCram get its text via TextSource.getText().

Once the text is loaded, you can control how WordCram counts up the words.

Case sensitivity: If your text contains “hello”, “HELLO”, and “Hello”,

lowerCase() will count them all as “hello”
upperCase() will count them all as “HELLO”
keepCase(), the default, will count them separately, as three different words
Numbers: If your text contains words like “42” or “3.14159”, you can remove them with excludeNumbers() (the default), or include them with includeNumbers().

Stop words: WordCram uses cue.language to remove common words from the text by default, but you can add your own stop words with withStopWords(String).

Weight Your Own Words
If you have some other way to weight your words, you can pass them to fromWords(Word[]), and in that case, you can use Word.setColor(int), Word.setFont(PFont), Word.setAngle(float), and/or Word.setPlace(PVector) to control how any (or all) of your Words are drawn.

Step Two: Style Your Words
There are six questions you have to answer when drawing a word on the WordCram:
How big should it be?
A word can be sizedByWeight(int, int), sizedByRank(int, int), or withSizer(WordSizer)
How should it be angled?
It can be angledAt(float…), angledBetween(float, float), or withAngler(WordAngler)
What font should it be in?
You can render words withFont(String) or withFonts(String…) (those both can also take PFonts), or withFonter(WordFonter)
How should it be colored?
withColor(int), withColors(int…), or withColorer(WordColorer)
Where on the image should it go?
withPlacer(WordPlacer)
If it doesn’t fit at first, how should I nudge it?
withNudger(WordNudger)
Step Three: Draw Your WordCram
After all that, actually rendering the WordCram is simple. You can repeatedly call drawNext() while the WordCram hasMore() words to draw (probably once per Processing frame):

void draw() {
if (wordCram.hasMore()) {
wordCram.drawNext();
}
}

Or you can call drawAll() once, and let it loop for you:
void draw() {
wordCram.drawAll();
}

Step Three-and-a-Half: How Did It Go?
If you’re having trouble getting your words to show up, you might want to getSkippedWords(). Knowing which words were skipped, and why (see Word.wasSkippedBecause()), can help you size and place your words better.

You can also getWords() to see the whole list, and getWordAt(float,float) to see which word covers a given pixel.

Constructor Summary
Constructors
Constructor and Description
WordCram(processing.core.PApplet parent)
Make a new WordCram.
Method Summary
All MethodsInstance MethodsConcrete MethodsDeprecated Methods
Modifier and Type Method and Description
WordCram angledAt(float… anglesInRadians)
Make the WordCram rotate each word at one of the given angles.
WordCram angledBetween(float minAngleInRadians, float maxAngleInRadians)
Make the WordCram rotate words randomly, between the min and max angles.
void drawAll()
Just like it sounds: draw all the words.
void drawNext()
If the WordCram has any more words to draw, draw the next one.
WordCram excludeNumbers()
Exclude numbers from the text in the WordCram.
WordCram fromHtmlFile(java.lang.String htmlFilePath)
Make a WordCram from the text in a HTML file.
WordCram fromHtmlFile(java.lang.String htmlFilePath, java.lang.String cssSelector)
Make a WordCram from the text in any elements on a web page that match the cssSelector.
WordCram fromHtmlString(java.lang.String… html)
Deprecated.
because its signature is annoying, and makes it hard to pass a CSS Selector. If you love this method, and want it to stick around, let me know: open a github issue, send me a tweet, or say hello at wordcram at gmail. Otherwise, it’ll be deleted in a future release, probably 0.6.
WordCram fromText(TextSource textSource)
Makes a WordCram from any TextSource.
WordCram fromTextFile(java.lang.String textFilePathOrUrl)
Makes a WordCram from a text file, either on the filesystem or the network.
WordCram fromTextString(java.lang.String… text)
Makes a WordCram from a String of text.
WordCram fromWebPage(java.lang.String webPageAddress)
Make a WordCram from the text on a web page.
WordCram fromWebPage(java.lang.String webPageAddress, java.lang.String cssSelector)
Make a WordCram from the text in any elements on a web page that match the cssSelector.
WordCram fromWords(Word[] words)
Makes a WordCram from your own custom Word array.
WordCram fromWords(WordSource wordSource)
float getProgress()
How far through the words are we? Useful for when drawing to a custom PGraphics.
Word[] getSkippedWords()
Returns an array of words that could not be placed.
Word getWordAt(float x, float y)
Get the Word at the given (x,y) coordinates.
Word[] getWords()
Get the Words that WordCram is drawing.
boolean hasMore()
If you’re drawing the words one-at-a-time using drawNext(), this will tell you whether the WordCram has any words left to draw.
WordCram includeNumbers()
Include numbers from the text in the WordCram.
WordCram keepCase()
Make the WordCram leave all words cased as they appear in the text.
WordCram lowerCase()
Make the WordCram change all words to lower-case.
WordCram maxAttemptsToPlaceWord(int maxAttempts)
How many attempts should be used to place a word.
WordCram maxNumberOfWordsToDraw(int maxWords)
The maximum number of Words WordCram should try to draw.
WordCram minShapeSize(int minShapeSize)
The smallest-sized Shape the WordCram should try to draw.
WordCram sizedByRank(int minSize, int maxSize)
Make the WordCram size words by their rank.
WordCram sizedByWeight(int minSize, int maxSize)
Make the WordCram size words by their weight, where the “heaviest” word will be sized at maxSize.
void testPlacer()
Render a heatmap of the locations where your WordPlacer places words.
WordCram toCanvas(processing.core.PGraphics canvas)
Use a custom canvas instead of the applet’s default one.
WordCram toSvg(java.lang.String filename, int width, int height)
WordCram upperCase()
Make the WordCram change all words to upper-case.
WordCram withAngler(WordAngler angler)
Use the given WordAngler to pick angles for each word.
WordCram withColor(int color)
Renders all words in the given color.
WordCram withColorer(WordColorer colorer)
Use the given WordColorer to pick colors for each word.
WordCram withColors(int… colors)
Render words by randomly choosing from the given colors.
WordCram withCustomCanvas(processing.core.PGraphics canvas)
Deprecated.
for more consistent naming. Use toCanvas(PGraphics canvas) instead.
WordCram withFont(processing.core.PFont font)
Make the WordCram render all words in the given PFont.
WordCram withFont(java.lang.String fontName)
Make the WordCram render all words in the font that matches the given name, via Processing’s createFont.
WordCram withFonter(WordFonter fonter)
Use the given WordFonter to pick fonts for each word.
WordCram withFonts(processing.core.PFont… fonts)
This WordCram will render words in one of the given PFonts.
WordCram withFonts(java.lang.String… fontNames)
This WordCram will get a PFont for each fontName, via createFont, and will render words in one of those PFonts.
WordCram withNudger(WordNudger nudger)
Use the given WordNudger to pick angles for each word.
WordCram withObserver(Observer observer)
WordCram withPlacer(WordPlacer placer)
Use the given WordPlacer to pick locations for each word.
WordCram withSizer(WordSizer sizer)
Use the given WordSizer to pick fonts for each word.
WordCram withStopWords(java.lang.String extraStopWords)
Tells WordCram which words to ignore when it counts up the words in your text.
WordCram withWordPadding(int padding)
Add padding around each word, so they stand out from each other more.
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Constructor Detail
WordCram
public WordCram(processing.core.PApplet parent)
Make a new WordCram.
It’s the starting point of the fluent API for building WordCrams.

Parameters:
parent – Your Processing sketch. Pass it as this.
Method Detail
withStopWords
public WordCram withStopWords(java.lang.String extraStopWords)
Tells WordCram which words to ignore when it counts up the words in your text. These words won’t show up in the image.
Stop-words are always case-insensitive: if your source text contains “The plane, the plane!”, using “the” for a stop-word is enough to block both “the” and “The”.

It doesn’t matter whether this is called before or after the “for{text}” methods.

Note: Stop-words have no effect if you’re passing in your own custom Word array, since WordCram won’t do any text analysis on it (other than sorting the words and scaling their weights).

Parameters:
extraStopWords – a space-delimited String of words to ignore when counting the words in your text.
Returns:
The WordCram, for further setup or drawing.
excludeNumbers
public WordCram excludeNumbers()
Exclude numbers from the text in the WordCram. They’re excluded by default.
Words that are all numbers, like 1, 3.14159, 42, or 1492, will be excluded. Words that have some letters and some numbers like 1A, U2, or funnyguy194 will be included.

Returns:
The WordCram, for further setup or drawing.
See Also:
includeNumbers()
includeNumbers
public WordCram includeNumbers()
Include numbers from the text in the WordCram. They’re excluded by default.
Returns:
The WordCram, for further setup or drawing.
See Also:
excludeNumbers()
lowerCase
public WordCram lowerCase()
Make the WordCram change all words to lower-case. Stop-words are unaffected; they’re always case-insensitive. The default is to keep words as they appear in the text.
Returns:
The WordCram, for further setup or drawing.
upperCase
public WordCram upperCase()
Make the WordCram change all words to upper-case. Stop-words are unaffected; they’re always case-insensitive. The default is to keep words as they appear in the text.
Returns:
The WordCram, for further setup or drawing.
keepCase
public WordCram keepCase()
Make the WordCram leave all words cased as they appear in the text. Stop-words are unaffected; they’re always case-insensitive. This is the default.
Returns:
The WordCram, for further setup or drawing.
fromWebPage
public WordCram fromWebPage(java.lang.String webPageAddress)
Make a WordCram from the text on a web page. Just before the WordCram is drawn, it’ll load the web page’s HTML, scrape out the text, and count and sort the words.
Parameters:
webPageAddress – the URL of the web page to load
Returns:
The WordCram, for further setup or drawing.
fromWebPage
public WordCram fromWebPage(java.lang.String webPageAddress,
java.lang.String cssSelector)
Make a WordCram from the text in any elements on a web page that match the cssSelector. Just before the WordCram is drawn, it’ll load the web page’s HTML, scrape out the text, and count and sort the words. HTML parsing is handled by Jsoup, so see the Jsoup selector documentation if you’re having trouble writing your selector.
Parameters:
webPageAddress – the URL of the web page to load
cssSelector – a CSS selector to filter the HTML by, before extracting text
Returns:
The WordCram, for further setup or drawing.
fromHtmlFile
public WordCram fromHtmlFile(java.lang.String htmlFilePath)
Make a WordCram from the text in a HTML file. Just before the WordCram is drawn, it’ll load the file’s HTML, scrape out the text, and count and sort the words.
Parameters:
htmlFilePath – the path of the html file to load
Returns:
The WordCram, for further setup or drawing.
fromHtmlFile
public WordCram fromHtmlFile(java.lang.String htmlFilePath,
java.lang.String cssSelector)
Make a WordCram from the text in any elements on a web page that match the cssSelector. Just before the WordCram is drawn, it’ll load the file’s HTML, scrape out the text, and count and sort the words. HTML parsing is handled by Jsoup, so see the Jsoup selector documentation if you’re having trouble writing your selector.
Parameters:
htmlFilePath – the path of the html file to load
cssSelector – a CSS selector to filter the HTML by, before extracting text
Returns:
The WordCram, for further setup or drawing.
fromHtmlString
@Deprecated
public WordCram fromHtmlString(java.lang.String… html)
Deprecated. because its signature is annoying, and makes it hard to pass a CSS Selector. If you love this method, and want it to stick around, let me know: open a github issue, send me a tweet, or say hello at wordcram at gmail. Otherwise, it’ll be deleted in a future release, probably 0.6.
Makes a WordCram from a String of HTML. Just before the WordCram is drawn, it’ll scrape out the text from the HTML, and count and sort the words. It takes one String, or any number of Strings, or an array of Strings, so you can easily use it with loadStrings().
Parameters:
html – the String(s) of HTML
Returns:
The WordCram, for further setup or drawing.
fromTextFile
public WordCram fromTextFile(java.lang.String textFilePathOrUrl)
Makes a WordCram from a text file, either on the filesystem or the network. Just before the WordCram is drawn, it’ll load the file, and count and sort its words.
Parameters:
textFilePathOrUrl – the path of the text file
Returns:
The WordCram, for further setup or drawing.
fromTextString
public WordCram fromTextString(java.lang.String… text)
Makes a WordCram from a String of text. It takes one String, or any number of Strings, or an array of Strings, so you can easily use it with loadStrings().
Parameters:
text – the String of text to get the words from
Returns:
The WordCram, for further setup or drawing.
fromText
public WordCram fromText(TextSource textSource)
Makes a WordCram from any TextSource.
It only caches the TextSource – it won’t load the text from it until drawAll() or drawNext() is called.

Parameters:
textSource – the TextSource to get the text from.
Returns:
The WordCram, for further setup or drawing.
fromWords
public WordCram fromWords(Word[] words)
Makes a WordCram from your own custom Word array. The Words can be ordered and weighted arbitrarily – WordCram will sort them by weight, and then divide their weights by the weight of the heaviest Word, so the heaviest Word will end up with a weight of 1.0.
Note: WordCram won’t do any text analysis on the words; stop-words will have no effect, etc. These words are supposed to be ready to go.

Returns:
The WordCram, for further setup or drawing.
fromWords
public WordCram fromWords(WordSource wordSource)
withFonts
public WordCram withFonts(java.lang.String… fontNames)
This WordCram will get a PFont for each fontName, via createFont, and will render words in one of those PFonts.
Returns:
The WordCram, for further setup or drawing.
withFont
public WordCram withFont(java.lang.String fontName)
Make the WordCram render all words in the font that matches the given name, via Processing’s createFont.
Parameters:
fontName – the font name to pass to createFont.
Returns:
The WordCram, for further setup or drawing.
withFonts
public WordCram withFonts(processing.core.PFont… fonts)
This WordCram will render words in one of the given PFonts.
Returns:
The WordCram, for further setup or drawing.
withFont
public WordCram withFont(processing.core.PFont font)
Make the WordCram render all words in the given PFont.
Parameters:
font – the PFont to render the words in.
Returns:
The WordCram, for further setup or drawing.
withFonter
public WordCram withFonter(WordFonter fonter)
Use the given WordFonter to pick fonts for each word. You can make your own, or use a pre-fab one from Fonters.
Parameters:
fonter – the WordFonter to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordFonter, Fonters
sizedByWeight
public WordCram sizedByWeight(int minSize,
int maxSize)
Make the WordCram size words by their weight, where the “heaviest” word will be sized at maxSize.
Specifically, it makes the WordCram use Sizers.byWeight(int, int).

Parameters:
minSize – the size to draw a Word of weight 0
maxSize – the size to draw a Word of weight 1
Returns:
The WordCram, for further setup or drawing.
sizedByRank
public WordCram sizedByRank(int minSize,
int maxSize)
Make the WordCram size words by their rank. The first word will be sized at maxSize.
Specifically, it makes the WordCram use Sizers.byRank(int, int).

Parameters:
minSize – the size to draw the last Word
maxSize – the size to draw the first Word
Returns:
The WordCram, for further setup or drawing.
withSizer
public WordCram withSizer(WordSizer sizer)
Use the given WordSizer to pick fonts for each word. You can make your own, or use a pre-fab one from Sizers.
Parameters:
sizer – the WordSizer to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordSizer, Sizers
withColors
public WordCram withColors(int… colors)
Render words by randomly choosing from the given colors. Uses Colorers.pickFrom(int…).
Note: if you want all your words to be, say, red, don’t do this:

…withColors(255, 0, 0)… // Not what you want!

You’ll just see a blank WordCram. Since Processing stores colors as integers, WordCram will see each integer as a different color, and it’ll color about 1/3 of your words with the color represented by the integer 255, and the other 2/3 with the color represented by the integer 0. The punchline is, Processing stores opacity (or alpha) in the highest bits (the ones used for storing really big numbers, from 224 to 232), so your colors 0 and 255 have, effectively, 0 opacity — they’re completely transparent. Oops.
Use this instead, and you’ll get what you’re after:

…withColors(color(255, 0, 0))… // Much better!

Parameters:
colors – the colors to randomly choose from.
Returns:
The WordCram, for further setup or drawing.
withColor
public WordCram withColor(int color)
Renders all words in the given color.
Parameters:
color – the color for each word.
Returns:
The WordCram, for further setup or drawing.
See Also:
withColors(int…)
withColorer
public WordCram withColorer(WordColorer colorer)
Use the given WordColorer to pick colors for each word. You can make your own, or use a pre-fab one from Colorers.
Parameters:
colorer – the WordColorer to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordColorer, Colorers
angledAt
public WordCram angledAt(float… anglesInRadians)
Make the WordCram rotate each word at one of the given angles.
Parameters:
anglesInRadians – The list of possible rotation angles, in radians
Returns:
The WordCram, for further setup or drawing.
angledBetween
public WordCram angledBetween(float minAngleInRadians,
float maxAngleInRadians)
Make the WordCram rotate words randomly, between the min and max angles.
Parameters:
minAngleInRadians – The minimum rotation angle, in radians
maxAngleInRadians – The maximum rotation angle, in radians
Returns:
The WordCram, for further setup or drawing.
withAngler
public WordCram withAngler(WordAngler angler)
Use the given WordAngler to pick angles for each word. You can make your own, or use a pre-fab one from Anglers.
Parameters:
angler – the WordAngler to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordAngler, Anglers
withPlacer
public WordCram withPlacer(WordPlacer placer)
Use the given WordPlacer to pick locations for each word. You can make your own, or use a pre-fab one from Placers.
Parameters:
placer – the WordPlacer to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordPlacer, Placers, PlottingWordPlacer
withNudger
public WordCram withNudger(WordNudger nudger)
Use the given WordNudger to pick angles for each word. You can make your own, or use a pre-fab one.
Parameters:
nudger – the WordNudger to use.
Returns:
The WordCram, for further setup or drawing.
See Also:
WordNudger, SpiralWordNudger, RandomWordNudger, PlottingWordNudger
maxAttemptsToPlaceWord
public WordCram maxAttemptsToPlaceWord(int maxAttempts)
How many attempts should be used to place a word. Higher values ensure that more words get placed, but will make algorithm slower.
Parameters:
maxAttempts –
Returns:
The WordCram, for further setup or drawing.
maxNumberOfWordsToDraw
public WordCram maxNumberOfWordsToDraw(int maxWords)
The maximum number of Words WordCram should try to draw. This might be useful if you have a whole bunch of words, and need an artificial way to cut down the list (for speed). By default, it’s unlimited.
Parameters:
maxWords – can be any value from 0 to Integer.MAX_VALUE. Values < 0 are treated as unlimited.
Returns:
The WordCram, for further setup or drawing.
minShapeSize
public WordCram minShapeSize(int minShapeSize)
The smallest-sized Shape the WordCram should try to draw. By default, it’s 7.
Parameters:
minShapeSize – the size of the smallest Shape.
Returns:
The WordCram, for further setup or drawing.
withCustomCanvas
public WordCram withCustomCanvas(processing.core.PGraphics canvas)
Deprecated. for more consistent naming. Use toCanvas(PGraphics canvas) instead.
Use a custom canvas instead of the applet’s default one. This may be needed if rendering in background or in other dimensions than the applet size is needed.
Parameters:
canvas – the canvas to draw to
Returns:
The WordCram, for further setup or drawing.
toCanvas
public WordCram toCanvas(processing.core.PGraphics canvas)
Use a custom canvas instead of the applet’s default one. This may be needed if rendering in background or in other dimensions than the applet size is needed.
Parameters:
canvas – the canvas to draw to
Returns:
The WordCram, for further setup or drawing.
toSvg
public WordCram toSvg(java.lang.String filename,
int width,
int height)
throws java.io.FileNotFoundException
Throws:
java.io.FileNotFoundException
withWordPadding
public WordCram withWordPadding(int padding)
Add padding around each word, so they stand out from each other more. If you call this multiple times, the last value will be used. WordCram uses a tree of java.awt.Rectangle objects to detect whether two words overlap. What this method actually does is call Rectangle.grow(padding) on the leaves of that tree.
Parameters:
padding – The number of pixels to grow each rectangle by. Defaults to zero.
Returns:
The WordCram, for further setup or drawing.
testPlacer
public void testPlacer()
Render a heatmap of the locations where your WordPlacer places words. This is pretty accurate: it renders all your words according to your sizer, fonter, angler, and placer, without nudging them, to an in-memory buffer. Then it splits your sketch into 10×10 pixel squares, and counts how many words overlap each square, and renders a heatmap: black for 0 words, green for 1, and red for more than 8. Rendering too many words at the same spot will make your WordCram run slower, and skip more words, so learning where your hotspots are can be helpful. This is very experimental, and could be changed or removed in a future release.
hasMore
public boolean hasMore()
If you’re drawing the words one-at-a-time using drawNext(), this will tell you whether the WordCram has any words left to draw.
Returns:
true if the WordCram has any words left to draw; false otherwise.
See Also:
drawNext()
drawNext
public void drawNext()
If the WordCram has any more words to draw, draw the next one.
See Also:
hasMore(), drawAll()
drawAll
public void drawAll()
Just like it sounds: draw all the words. Once the WordCram has everything set, call this and wait just a bit.
See Also:
drawNext()
getWords
public Word[] getWords()
Get the Words that WordCram is drawing. This can be useful if you want to inspect exactly how the words were weighted, or see how they were colored, fonted, sized, angled, or placed, or why they were skipped.
getWordAt
public Word getWordAt(float x,
float y)
Get the Word at the given (x,y) coordinates.
This can be called while the WordCram is rendering, or after it’s done. If a Word is too small to render, or hasn’t been placed yet, it will never be returned by this method.

Parameters:
x – the X coordinate
y – the Y coordinate
Returns:
the Word that covers those coordinates, or null if there isn’t one
getSkippedWords
public Word[] getSkippedWords()
Returns an array of words that could not be placed.
Returns:
An array of the skipped words
getProgress
public float getProgress()
How far through the words are we? Useful for when drawing to a custom PGraphics.
Returns:
The current point of progress through the list, as a float between 0 and 1.
withObserver
public WordCram withObserver(Observer observer)