ruby_wordcram 1.0.1 → 2.0.0

data/src/wordcram/WordCramEngine.java

@@ -0,0 +1,196 @@
+package wordcram;
+
+import java.awt.Color; // awt: turns P5-land color into awt color, for renderers
+import java.awt.Shape; // awt: word->shape, skip if too small, pass it on
+import java.awt.geom.Rectangle2D; // awt: to get bounding box width & height
+import java.util.ArrayList;
+import java.util.ListIterator;
+
+import processing.core.PFont;
+import processing.core.PVector;
+
+class WordCramEngine {
+
+    private final WordRenderer renderer;
+
+    private final WordFonter fonter;
+    private final WordSizer sizer;
+    private final WordColorer colorer;
+    private final WordAngler angler;
+    private final WordPlacer placer;
+    private final WordNudger nudger;
+
+    private final ArrayList<EngineWord> eWords;
+    private final ListIterator<EngineWord> eWordIter;
+    private final ArrayList<EngineWord> drawnWords = new ArrayList<>();
+    private final ArrayList<Word> skippedWords = new ArrayList<>();
+
+    private final RenderOptions renderOptions;
+    private final Observer observer;
+
+    // TODO Damn, really need to break down that list of arguments.
+    WordCramEngine(WordRenderer renderer, Word[] words, WordFonter fonter, WordSizer sizer, WordColorer colorer, WordAngler angler, WordPlacer placer, WordNudger nudger, WordShaper shaper, BBTreeBuilder bbTreeBuilder, RenderOptions renderOptions, Observer observer) {
+        this.renderer = renderer;
+
+        this.fonter = fonter;
+        this.sizer = sizer;
+        this.colorer = colorer;
+        this.angler = angler;
+        this.placer = placer;
+        this.nudger = nudger;
+        this.observer = observer;
+
+        this.renderOptions = renderOptions;
+        this.eWords = wordsIntoEngineWords(words, shaper, bbTreeBuilder);
+        this.eWordIter = eWords.listIterator();
+    }
+
+    private ArrayList<EngineWord> wordsIntoEngineWords(Word[] words, WordShaper wordShaper, BBTreeBuilder bbTreeBuilder) {
+        ArrayList<EngineWord> engineWords = new ArrayList<>();
+
+        int maxNumberOfWords = words.length;
+        if (renderOptions.maxNumberOfWordsToDraw >= 0) {
+            maxNumberOfWords = Math.min(maxNumberOfWords, renderOptions.maxNumberOfWordsToDraw);
+        }
+
+        for (int i = 0; i < maxNumberOfWords; i++) {
+            Word word = words[i];
+            EngineWord eWord = new EngineWord(word, i, words.length, bbTreeBuilder);
+
+            PFont wordFont = word.getFont(fonter);
+            float wordSize = word.getSize(sizer, i, words.length);
+            float wordAngle = word.getAngle(angler);
+
+            Shape shape = wordShaper.getShapeFor(eWord.word.word, wordFont, wordSize, wordAngle);
+            if (isTooSmall(shape, renderOptions.minShapeSize)) {
+                skipWord(word, WordSkipReason.SHAPE_WAS_TOO_SMALL);
+            }
+            else {
+                eWord.setShape(shape, renderOptions.wordPadding);
+                engineWords.add(eWord);  // DON'T add eWords with no shape.
+            }
+        }
+
+        for (int i = maxNumberOfWords; i < words.length; i++) {
+            skipWord(words[i], WordSkipReason.WAS_OVER_MAX_NUMBER_OF_WORDS);
+        }
+
+        return engineWords;
+    }
+
+    private boolean isTooSmall(Shape shape, int minShapeSize) {
+        if (minShapeSize < 1) {
+            minShapeSize = 1;
+        }
+        Rectangle2D r = shape.getBounds2D();
+
+        // Most words will be wider than tall, so this basically boils down to height.
+        // For the odd word like "I", we check width, too.
+        return r.getHeight() < minShapeSize || r.getWidth() < minShapeSize;
+    }
+
+    private void skipWord(Word word, WordSkipReason reason) {
+        // TODO delete these properties when starting a sketch, in case it's a re-run w/ the same words.
+        // NOTE: keep these as properties, because they (will be) deleted when the WordCramEngine re-runs.
+        word.wasSkippedBecause(reason);
+        skippedWords.add(word);
+        observer.wordSkipped(word);
+    }
+
+    boolean hasMore() {
+        return eWordIter.hasNext();
+    }
+
+    void drawAll() {
+    	observer.beginDraw();
+    	while(hasMore()) {
+            drawNext();
+        }
+        renderer.finish();
+        observer.endDraw();
+    }
+
+    void drawNext() {
+        if (!hasMore()) return;
+        EngineWord eWord = eWordIter.next();
+        boolean wasPlaced = placeWord(eWord);
+        if (wasPlaced) { // TODO unit test (somehow)
+            drawWordImage(eWord);
+            observer.wordDrawn(eWord.word);
+        }
+    }
+
+    private boolean placeWord(EngineWord eWord) {
+        Word word = eWord.word;
+        Rectangle2D rect = eWord.getShape().getBounds2D(); // TODO can we move these into EngineWord.setDesiredLocation? Does that make sense?
+        int wordImageWidth = (int)rect.getWidth();
+        int wordImageHeight = (int)rect.getHeight();
+
+        eWord.setDesiredLocation(placer, eWords.size(), wordImageWidth, wordImageHeight, renderer.getWidth(), renderer.getHeight());
+
+        // Set maximum number of placement trials
+        int maxAttemptsToPlace = renderOptions.maxAttemptsToPlaceWord > 0 ?
+                                    renderOptions.maxAttemptsToPlaceWord :
+                                    calculateMaxAttemptsFromWordWeight(word);
+
+        EngineWord lastCollidedWith = null;
+        for (int attempt = 0; attempt < maxAttemptsToPlace; attempt++) {
+
+            eWord.nudge(nudger.nudgeFor(word, attempt));
+
+            PVector loc = eWord.getCurrentLocation();
+            if (loc.x < 0 || loc.y < 0 || loc.x + wordImageWidth >= renderer.getWidth() || loc.y + wordImageHeight >= renderer.getHeight()) {
+                continue;
+            }
+
+            if (lastCollidedWith != null && eWord.overlaps(lastCollidedWith)) {
+                continue;
+            }
+
+            boolean foundOverlap = false;
+            for (EngineWord otherWord : drawnWords) {
+                if (eWord.overlaps(otherWord)) {
+                    foundOverlap = true;
+                    lastCollidedWith = otherWord;
+                    break;
+                }
+            }
+
+            if (!foundOverlap) {
+                eWord.finalizeLocation();
+                return true;
+            }
+        }
+
+        skipWord(eWord.word, WordSkipReason.NO_SPACE);
+        return false;
+    }
+
+    private int calculateMaxAttemptsFromWordWeight(Word word) {
+        return (int)((1.0 - word.weight) * 600) + 100;
+    }
+
+    private void drawWordImage(EngineWord word) {
+        drawnWords.add(word);
+        renderer.drawWord(word, new Color(word.word.getColor(colorer), true));
+    }
+
+    Word getWordAt(float x, float y) {
+        int size = drawnWords.size() - 1;
+        for (int i = size; i >= 0; i--) {
+            EngineWord eWord = drawnWords.get(i);
+            if (eWord.containsPoint(x, y)) {
+                return eWord.word;
+            }
+        }
+        return null;
+    }
+
+    Word[] getSkippedWords() {
+        return skippedWords.toArray(new Word[0]);
+    }
+
+    float getProgress() {
+        return (float) eWordIter.nextIndex() / eWords.size();
+    }
+}

data/src/wordcram/WordFonter.java

@@ -0,0 +1,24 @@
+package wordcram;
+
+import processing.core.PFont;
+
+/**
+ * A WordFonter tells WordCram what font to render a word in.
+ * <p>
+ * Some useful implementations are available in {@link Fonters}.
+ * <p>
+ * <i>The name "WordFonter" was picked because it matches the others: WordColorer,
+ * WordPlacer, WordSizer, etc. Apologies if it sounds a bit weird to your ear; I
+ * eventually got used to it.</i>
+ *
+ * @author Dan Bernier
+ */
+public interface WordFonter {
+
+    /**
+     * What font should this {@link Word} be drawn in?
+     * @param word the word to pick the PFont for
+     * @return the PFont for the word
+     */
+    public PFont fontFor(Word word);
+}

data/src/wordcram/WordNudger.java

@@ -0,0 +1,44 @@
+package wordcram;
+
+import processing.core.PVector;
+
+/**
+ * Once a WordPlacer tells WordCram where a word <i>should</i> go, a WordNudger
+ * tells WordCram how to nudge it around the field, until it fits in with the
+ * other words around it, or the WordCram gives up on the word.
+ * <p>
+ * WordCram gets a PVector from the nudger, and adds it to the word's desired
+ * location, to find the next spot to try fitting the word. Note that the
+ * PVectors returned from a nudger <i><b>don't accumulate</b></i>: if the placer
+ * puts a Word at (0, 0), and the nudger returns (1, 1), and then (2, 2),
+ * WordCram will try the word at (1, 1), and then (2, 2) -- <i>not</i> (1, 1)
+ * and then (3, 3).
+ * <p>
+ * A WordNudger should probably start nudging the word only a little, to keep it
+ * near its desired location, and gradually nudge it more and more, so that,
+ * even if the desired area is congested, the word can still fit in somewhere.
+ * This is why the WordCram passes in <code>attemptNumber</code>: it's the
+ * number of times it's attempted to place the word. This could (for example)
+ * scale the PVector, since the nudges don't accumulate (see above).
+ *
+ * @see RandomWordNudger
+ * @see SpiralWordNudger
+ *
+ * @author Dan Bernier
+ */
+public interface WordNudger {
+
+    /**
+     * How should this word be nudged, this time?
+     *
+     * @param word
+     *            the word to nudge
+     * @param attemptNumber
+     *            how many times WordCram has tried to place this word; starts
+     *            at zero, and ends at
+     *            <code>(int)((1.0-word.weight) * 600) + 100</code>
+     * @return the PVector to add to the word's desired location, to get the
+     *         next spot to try fitting the word
+     */
+    public PVector nudgeFor(Word word, int attemptNumber);
+}

data/src/wordcram/WordPlacer.java

@@ -0,0 +1,44 @@
+package wordcram;
+
+import processing.core.PVector;
+
+/**
+ * A WordPlacer tells WordCram where to place a word (in x,y coordinates) on the field.
+ * <p>
+ * A WordPlacer only suggests: the WordCram will try to place the Word where the
+ * WordPlacer tells it to, but if the Word overlaps other Words, a WordNudger
+ * will suggest different near-by spots for the Word until it fits, or until the
+ * WordCram gives up.
+ * <p>
+ * Some useful implementations are available in {@link Placers}.
+ *
+ * @author Dan Bernier
+ */
+public interface WordPlacer {
+
+    /**
+     * Where should this {@link Word} be drawn on the field?
+     *
+     * @param word
+     *            The Word to place. A typical WordPlacer might use the Word's
+     *            weight.
+     * @param wordIndex
+     *            The index (rank) of the Word to place. Since this isn't a
+     *            property of the Word, it's passed in as well.
+     * @param wordsCount
+     *            The total number of words. Gives a context to wordIndex:
+     *            "Word {wordIndex} of {wordsCount}".
+     * @param wordImageWidth
+     *            The width of the word image.
+     * @param wordImageHeight
+     *            The height of the word image.
+     * @param fieldWidth
+     *            The width of the field.
+     * @param fieldHeight
+     *            The height of the field.
+     * @return the desired location for a Word on the field, as a 2D PVector.
+     */
+    public abstract PVector place(Word word, int wordIndex, int wordsCount,
+            int wordImageWidth, int wordImageHeight, int fieldWidth,
+            int fieldHeight);
+}

data/src/wordcram/WordRenderer.java

@@ -0,0 +1,10 @@
+package wordcram;
+
+import java.awt.Color; // awt: JUST for the interface (this IS an interface)
+
+interface WordRenderer {
+	int getWidth();
+	int getHeight();
+	void drawWord(EngineWord word, Color color);
+	void finish();
+}

data/src/wordcram/WordShaper.java

@@ -0,0 +1,78 @@
+package wordcram;
+
+import java.awt.Font; // awt: font+word=shape
+import java.awt.Shape; // awt: font+word=shape
+import java.awt.font.FontRenderContext; // awt: font+word=shape
+import java.awt.font.GlyphVector; // awt: font+word=shape
+import java.awt.geom.AffineTransform; // awt: move and rotate shape
+import java.awt.geom.Rectangle2D; // awt: move shape
+
+import processing.core.PFont;
+
+public class WordShaper {
+    private final FontRenderContext frc = new FontRenderContext(null, true, true);
+
+
+    private boolean rightToLeft;
+    public WordShaper(boolean rightToLeft) {
+        this.rightToLeft = rightToLeft;
+    }
+    public WordShaper() {
+        this(false);
+    }
+
+
+    public Shape getShapeFor(String word, Font font, float fontSize, float angle) {
+        Shape shape = makeShape(word, sizeFont(font, fontSize));
+        return moveToOrigin(rotate(shape, angle));
+    }
+
+    public Shape getShapeFor(String word, Font font) {
+        return getShapeFor(word, font, font.getSize2D(), 0);
+    }
+
+    public Shape getShapeFor(String word, PFont pFont, float fontSize, float angle) {
+        return getShapeFor(word, (Font)pFont.getNative(), fontSize, angle);
+    }
+
+    public Shape getShapeFor(String word, PFont pFont) {
+        return getShapeFor(word, (Font)pFont.getNative());
+    }
+
+
+
+    private Font sizeFont(Font unsizedFont, float fontSize) {
+        if (fontSize == unsizedFont.getSize2D()) {
+            return unsizedFont;
+        }
+    	return unsizedFont.deriveFont(fontSize);
+    }
+
+    private Shape makeShape(String word, Font font) {
+        char[] chars = word.toCharArray();
+
+        // TODO hmm: this doesn't render newlines.  Hrm.  If your word text is "foo\nbar", you get "foobar".
+        GlyphVector gv = font.layoutGlyphVector(frc, chars, 0, chars.length,
+                this.rightToLeft ? Font.LAYOUT_RIGHT_TO_LEFT : Font.LAYOUT_LEFT_TO_RIGHT);
+
+        return gv.getOutline();
+    }
+
+    private Shape rotate(Shape shape, float rotation) {
+        if (rotation == 0) {
+            return shape;
+        }
+
+        return AffineTransform.getRotateInstance(rotation).createTransformedShape(shape);
+    }
+
+    private Shape moveToOrigin(Shape shape) {
+        Rectangle2D rect = shape.getBounds2D();
+
+        if (rect.getX() == 0 && rect.getY() == 0) {
+            return shape;
+        }
+
+        return AffineTransform.getTranslateInstance(-rect.getX(), -rect.getY()).createTransformedShape(shape);
+    }
+}

data/src/wordcram/WordSizer.java

@@ -0,0 +1,46 @@
+package wordcram;
+
+/**
+ * A WordSizer tells WordCram how big to render each word.
+ * You'll pass a WordSizer to WordCram via {@link WordCram#withSizer(WordSizer)}.
+ * <p>
+ * Some useful implementations are available in {@link Sizers}.
+ *
+ * @author Dan Bernier
+ */
+public interface WordSizer {
+
+    /**
+     * How big should this {@link Word} be rendered?
+     * <p>
+     * Generally, a word cloud draws more important words bigger. Two typical
+     * ways to measure word's importance are its weight, and its rank (its
+     * position in the list of words, sorted by weight).
+     * <p>
+     * Given that, sizeFor is passed the Word (which knows its own weight), its
+     * rank, and the total number of words.
+     * <p>
+     * For example, given the text "I think I can I think", the words would look
+     * like this:
+     * <ul>
+     * <li>"I", weight 1.0 (3/3), rank 1</li>
+     * <li>"think", weight 0.667 (2/3), rank 2</li>
+     * <li>"can", weight 0.333 (1/3), rank 3</li>
+     * </ul>
+     * ...and the WordSizer would be called with the following values:
+     * <ul>
+     * <li>Word "I" (weight 1.0), 1, 3</li>
+     * <li>Word "think" (weight 0.667), 2, 3</li>
+     * <li>Word "can" (weight 0.333), 3, 3</li>
+     * </ul>
+     *
+     * @param word
+     *            the Word to determine the size of
+     * @param wordRank
+     *            the rank of the Word
+     * @param wordCount
+     *            the total number of Words being rendered
+     * @return the size to render the Word
+     */
+    public float sizeFor(Word word, int wordRank, int wordCount);
+}