public class WordCram
extends java.lang.Object
There are three steps to making a WordCram:
new WordCram(this), and then...
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 wordsfromHtmlString(String...) takes a String (or String[]), assumes it's HTML, and scrapes out its textfromTextFile(String) loads a file (from the filesystem or the network), and counts the wordsfromTextString(String...) takes a String (or String[]), and counts the wordsIf 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 wordsNumbers: 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).
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.
sizedByWeight(int, int),
sizedByRank(int, int), or
withSizer(WordSizer)
angledAt(float...),
angledBetween(float, float), or
withAngler(WordAngler)
withFont(String) or withFonts(String...) (those both can
also take PFonts), or withFonter(WordFonter)
withColor(int),
withColors(int...), or
withColorer(WordColorer)
withPlacer(WordPlacer)
withNudger(WordNudger)
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();
}
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.
| Modifier and Type | Field and Description |
|---|---|
static int |
NO_SPACE
Skip Reason: WordCram tried placing the Word, but it couldn't find a clear
spot.
|
static int |
SHAPE_WAS_TOO_SMALL
Skip Reason: the Word's shape was too small.
|
static int |
WAS_OVER_MAX_NUMBER_OF_WORDS
Skip Reason: the Word was skipped because
maxNumberOfWordsToDraw(int)
was set to some value, and the Word came in over that limit. |
| Constructor and Description |
|---|
WordCram(processing.core.PApplet parent)
Make a new WordCram.
|
| 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 |
fromHtmlString(java.lang.String... html)
Makes a WordCram from a String of HTML.
|
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 |
fromWords(Word[] words)
Makes a WordCram from your own custom Word array.
|
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. |
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)
Use a custom canvas instead of the applet's default one.
|
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 |
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.
|
public static final int WAS_OVER_MAX_NUMBER_OF_WORDS
maxNumberOfWordsToDraw(int)
was set to some value, and the Word came in over that limit.
It's really about the Word's rank, its position in the list once the words are
sorted by weight: if its rank is greater than the value passed to maxNumberOfWordsToDraw(),
then it'll be skipped, and this will be the reason code.public static final int SHAPE_WAS_TOO_SMALL
minShapeSize(int).public static final int NO_SPACE
WordNudger nudged it around a bunch (according to
maxAttemptsToPlaceWord(int), if it was set), but there was just no room.public WordCram(processing.core.PApplet parent)
It's the starting point of the fluent API for building WordCrams.
parent - Your Processing sketch. Pass it as this.public WordCram withStopWords(java.lang.String extraStopWords)
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).
extraStopWords - a space-delimited String of words to ignore when counting the words in your text.public WordCram excludeNumbers()
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.
includeNumbers()public WordCram includeNumbers()
excludeNumbers()public WordCram lowerCase()
public WordCram upperCase()
public WordCram keepCase()
public WordCram fromWebPage(java.lang.String webPageAddress)
webPageAddress - the URL of the web page to loadpublic WordCram fromHtmlFile(java.lang.String htmlFilePath)
htmlFilePath - the path of the html file to loadpublic WordCram fromHtmlString(java.lang.String... html)
html - the String(s) of HTMLpublic WordCram fromTextFile(java.lang.String textFilePathOrUrl)
textFilePathOrUrl - the path of the text filepublic WordCram fromTextString(java.lang.String... text)
text - the String of text to get the words frompublic WordCram fromText(TextSource textSource)
It only caches the TextSource - it won't load the text
from it until drawAll() or drawNext() is
called.
textSource - the TextSource to get the text from.public WordCram fromWords(Word[] words)
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.
public WordCram withFonts(java.lang.String... fontNames)
public WordCram withFont(java.lang.String fontName)
fontName - the font name to pass to createFont.public WordCram withFonts(processing.core.PFont... fonts)
public WordCram withFont(processing.core.PFont font)
font - the PFont to render the words in.public WordCram withFonter(WordFonter fonter)
Fonters.fonter - the WordFonter to use.WordFonter,
Fonterspublic WordCram sizedByWeight(int minSize, int maxSize)
maxSize.
Specifically, it makes the WordCram use Sizers.byWeight(int, int).
minSize - the size to draw a Word of weight 0maxSize - the size to draw a Word of weight 1public WordCram sizedByRank(int minSize, int maxSize)
maxSize.
Specifically, it makes the WordCram use Sizers.byRank(int, int).
minSize - the size to draw the last WordmaxSize - the size to draw the first Wordpublic WordCram withSizer(WordSizer sizer)
Sizers.public WordCram withColors(int... colors)
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!
colors - the colors to randomly choose from.public WordCram withColor(int color)
color - the color for each word.withColors(int...)public WordCram withColorer(WordColorer colorer)
Colorers.colorer - the WordColorer to use.WordColorer,
Colorerspublic WordCram angledAt(float... anglesInRadians)
anglesInRadians - The list of possible rotation angles, in radianspublic WordCram angledBetween(float minAngleInRadians, float maxAngleInRadians)
minAngleInRadians - The minimum rotation angle, in radiansmaxAngleInRadians - The maximum rotation angle, in radianspublic WordCram withAngler(WordAngler angler)
Anglers.angler - the WordAngler to use.WordAngler,
Anglerspublic WordCram withPlacer(WordPlacer placer)
Placers.placer - the WordPlacer to use.WordPlacer,
Placers,
PlottingWordPlacerpublic WordCram withNudger(WordNudger nudger)
nudger - the WordNudger to use.WordNudger,
SpiralWordNudger,
RandomWordNudger,
PlottingWordNudgerpublic WordCram maxAttemptsToPlaceWord(int maxAttempts)
maxAttempts - public WordCram maxNumberOfWordsToDraw(int maxWords)
maxWords - can be any value from 0 to Integer.MAX_VALUE. Values < 0 are treated as unlimited.public WordCram minShapeSize(int minShapeSize)
minShapeSize - the size of the smallest Shape.public WordCram withCustomCanvas(processing.core.PGraphics canvas)
canvas - the canvas to draw topublic WordCram withWordPadding(int padding)
Rectangle.grow(padding) on the
leaves of that tree.padding - The number of pixels to grow each rectangle by. Defaults to zero.public boolean hasMore()
drawNext(), this will tell you whether the WordCram has
any words left to draw.drawNext()public void drawNext()
public void drawAll()
drawNext()public Word[] getWords()
public Word getWordAt(float x, float y)
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.
x - the X coordinatey - the Y coordinatepublic Word[] getSkippedWords()
public float getProgress()