ruby_wordcram 1.0.1 → 2.0.0

data/src/wordcram/Sizers.java

@@ -0,0 +1,54 @@
+package wordcram;
+
+import processing.core.PApplet;
+
+/**
+ * Sizers contains pre-made {@link WordSizer} implementations that you might
+ * find useful. Right now, it's only {@link Sizers#byWeight(int, int)} and
+ * {@link Sizers#byRank(int, int)}.
+ * @see WordSizer
+ */
+public class Sizers {
+
+    /**
+     * Returns a WordSizer that sizes words by their weight, where the
+     * "heaviest" word will be sized at <code>maxSize</code>.
+     * <p>
+     * To be specific, the font size for each word will be calculated with:
+     *
+     * <pre>
+     * PApplet.lerp(minSize, maxSize, (float) word.weight)
+     * </pre>
+     *
+     * @param minSize
+     *            the size to draw a Word with weight = 0
+     * @param maxSize
+     *            the size to draw a Word with weight = 1
+     * @return the WordSizer
+     */
+    public static WordSizer byWeight(final int minSize, final int maxSize) {
+        return (Word word, int wordRank, int wordCount) -> PApplet.lerp(minSize, maxSize, word.weight);
+    }
+
+    /**
+     * Returns a WordSizer that sizes words by their rank. The first word will
+     * be sized at <code>maxSize</code>.
+     * <p>
+     * To be specific, the font size for each word will be calculated with:
+     *
+     * <pre>
+     * PApplet.map(wordRank, 0, wordCount, maxSize, minSize)
+     * </pre>
+     *
+     * @param minSize
+     *            the size to draw the last Word
+     * @param maxSize
+     *            the size to draw the first Word
+     * @return the WordSizer
+     */
+    public static WordSizer byRank(final int minSize, final int maxSize) {
+        return (Word word, int wordRank, int wordCount) -> PApplet.map(wordRank, 0, wordCount, maxSize, minSize);
+    }
+
+    // TODO try exponent scales, rather than linear.
+}

data/src/wordcram/SketchCallbackObserver.java

@@ -0,0 +1,70 @@
+package wordcram;
+
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.HashMap;
+import processing.core.PApplet;
+
+// This is a healthy rip-off of
+// https://github.com/processing/processing/wiki/Library-Basics#adding-your-own-library-events
+
+class SketchCallbackObserver implements Observer {
+	PApplet parent;
+
+	HashMap<String, Method> sketchMethods = new HashMap<>();
+
+	SketchCallbackObserver(PApplet parent) {
+
+		this.parent = parent;
+
+		registerSketchMethod("wordsCounted", Word[].class);
+		registerSketchMethod("beginDraw");
+		registerSketchMethod("wordDrawn", Word.class);
+		registerSketchMethod("wordSkipped", Word.class);
+		registerSketchMethod("endDraw");
+	}
+
+        @Override
+	public void wordsCounted(Word[] words) {
+		invoke("wordsCounted", new Object[] { words });
+	}
+        @Override
+	public void beginDraw() {
+		invoke("beginDraw", new Object[0]);
+	}
+        @Override
+	public void wordDrawn(Word word) {
+		invoke("wordDrawn", new Object[] { word });
+	}
+        @Override
+	public void wordSkipped(Word word) {
+		invoke("wordSkipped", new Object[] { word });
+	}
+        @Override
+	public void endDraw() {
+		invoke("endDraw", new Object[0]);
+	}
+
+	private void registerSketchMethod(String name, Class... parameterTypes) {
+		try {
+			Method method = parent.getClass().getMethod(name, parameterTypes);
+			sketchMethods.put(name, method);
+	    }
+	    catch (NoSuchMethodException | SecurityException e) {
+			// The sketch doesn't have this method name. No worries.
+	    }
+	}
+
+	private void invoke(String name, Object[] arguments) {
+		if (sketchMethods.containsKey(name)) {
+			Method method = sketchMethods.get(name);
+			try {
+				method.invoke(parent, arguments);
+			}
+			catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException e) {
+				System.err.println("Disabling method " + name + " because of an error.");
+				sketchMethods.remove(name);
+			}
+		}
+	}
+}

data/src/wordcram/SpiralWordNudger.java

@@ -0,0 +1,31 @@
+package wordcram;
+
+import processing.core.PApplet;
+import processing.core.PVector;
+
+public class SpiralWordNudger implements WordNudger {
+
+    // Who knows? this seems to be good, but it seems to depend on the font --
+    // bigger fonts need a bigger thetaIncrement.
+    private float thetaIncrement = (float) (Math.PI * 0.03);
+
+    @Override
+    public PVector nudgeFor(Word w, int attempt) {
+        float rad = powerMap(0.6f, attempt, 0, 600, 1, 100);
+
+        thetaIncrement = powerMap(1, attempt, 0, 600, 0.5f, 0.3f);
+        float theta = thetaIncrement * attempt;
+        float x = PApplet.cos(theta) * rad;
+        float y = PApplet.sin(theta) * rad;
+        return new PVector(x, y);
+    }
+
+    private float powerMap(float power, float v, float min1, float max1,
+            float min2, float max2) {
+
+        float val = PApplet.norm(v, min1, max1);
+        val = PApplet.pow(val, power);
+        return PApplet.lerp(min2, max2, val);
+    }
+
+}

data/src/wordcram/SvgWordRenderer.java

@@ -0,0 +1,110 @@
+package wordcram;
+
+import java.awt.Color; // awt: color->hex
+import java.awt.Shape; // awt: shape->path
+import java.awt.geom.PathIterator; // awt: path->svg
+import java.awt.geom.Path2D; // awt: path->svg
+import java.io.PrintWriter;
+import java.io.FileNotFoundException;
+
+class SvgWordRenderer implements WordRenderer {
+	private final PrintWriter out;
+	private final int width;
+	private final int height;
+
+	SvgWordRenderer(String filename, int width, int height) throws FileNotFoundException {
+		this.out = new PrintWriter(filename);
+		this.width = width;
+		this.height = height;
+
+		pl("<?xml version=\"1.0\"?>");
+		pl("<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.0//EN\" \"http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd\">");
+		// TODO add wordcram metadata
+		pl("<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" width=\"" + width + "\" height=\"" + height + "\" fill-rule=\"evenodd\">");   // or nonzero
+	}
+
+        @Override
+	public int getWidth() {
+		return this.width;
+	}
+
+        @Override
+	public int getHeight() {
+		return this.height;
+	}
+
+        @Override
+	public void drawWord(EngineWord word, Color color) {
+		// TODO add word metadata
+		pl("<g style=\"fill:" + getColor(color) + "; stroke-width:0px\">");
+		renderShape(word.getShape());
+		pl("</g>");
+	}
+
+        @Override
+	public void finish() {
+		pl("</svg>");
+		out.flush();
+		out.close();
+	}
+
+	private String getColor(Color color) {
+		// rgb(30, 200, 90)
+		// #ff0023
+		return "#" + decToHex(color.getRed()) + decToHex(color.getGreen()) + decToHex(color.getBlue());
+	}
+
+	private String decToHex(int dec) {
+		return dec > 16 ? Integer.toHexString(dec) :
+				          "0" + Integer.toHexString(dec);
+	}
+
+	private void renderShape(Shape shape) {
+
+		Path2D.Double path2d = new Path2D.Double(shape);
+		path2d.setWindingRule(Path2D.WIND_EVEN_ODD);   // or WIND_NON_ZERO
+		PathIterator pathIter = path2d.getPathIterator(null);
+
+		float[] coords = new float[6];
+
+		p("<path d=\"");
+		while (!pathIter.isDone()) {
+
+			int type = pathIter.currentSegment(coords);
+
+			switch(type) {
+				case PathIterator.SEG_MOVETO:
+					p("M" + coords[0] + " " + coords[1]);
+					break;
+
+				case PathIterator.SEG_LINETO:
+					p("L" + coords[0] + " " + coords[1]);
+					break;
+
+				case PathIterator.SEG_QUADTO:
+					p("Q" + coords[0] + " " + coords[1] + " " + coords[2] + " " + coords[3]);
+					break;
+
+				case PathIterator.SEG_CUBICTO:
+					p("C" + coords[0] + " " + coords[1] + " " + coords[2] + " " + coords[3] + " " + coords[4] + " " + coords[5]);
+					break;
+
+				case PathIterator.SEG_CLOSE:
+					p("Z");
+					break;
+			}
+
+			pathIter.next();
+		}
+
+		pl("\"/>");
+	}
+
+	private void pl(String s) {
+		out.println(s);
+	}
+
+	private void p(String s) {
+		out.print(s);
+	}
+}

data/src/wordcram/SwirlWordPlacer.java

@@ -0,0 +1,25 @@
+package wordcram;
+
+import processing.core.*;
+
+public class SwirlWordPlacer implements WordPlacer {
+
+    @Override
+    public PVector place(Word word, int wordIndex, int wordsCount,
+            int wordImageWidth, int wordImageHeight, int fieldWidth,
+            int fieldHeight) {
+
+        float normalizedIndex = (float) wordIndex / wordsCount;
+
+        float theta = normalizedIndex * 6 * PConstants.TWO_PI;
+        float radius = normalizedIndex * fieldWidth / 2f;
+
+        float centerX = fieldWidth * 0.5f;
+        float centerY = fieldHeight * 0.5f;
+
+        float x = PApplet.cos(theta) * radius;
+        float y = PApplet.sin(theta) * radius;
+
+        return new PVector(centerX + x, centerY + y);
+    }
+}

data/src/wordcram/UpperLeftWordPlacer.java

@@ -0,0 +1,27 @@
+package wordcram;
+
+import java.util.Random;
+
+import processing.core.PApplet;
+import processing.core.PVector;
+
+public class UpperLeftWordPlacer implements WordPlacer {
+
+    private final Random r = new Random();
+
+    @Override
+    public PVector place(Word word, int wordIndex, int wordsCount, int wordImageWidth, int wordImageHeight, int fieldWidth, int fieldHeight) {
+        int x = getOneUnder(fieldWidth - wordImageWidth);
+        int y = getOneUnder(fieldHeight - wordImageHeight);
+        return new PVector(x, y);
+    }
+
+    private int getOneUnder(int limit) {
+        return PApplet.round(PApplet.map(random(random(random(random(random(1.0f))))), 0, 1, 0, limit));
+    }
+
+    private float random(float limit) {
+        return r.nextFloat() * limit;
+    }
+
+}

data/src/wordcram/WaveWordPlacer.java

@@ -0,0 +1,25 @@
+package wordcram;
+
+import processing.core.*;
+
+public class WaveWordPlacer implements WordPlacer {
+
+    @Override
+    public PVector place(Word word, int wordIndex, int wordsCount,
+            int wordImageWidth, int wordImageHeight, int fieldWidth,
+            int fieldHeight) {
+
+        float normalizedIndex = (float) wordIndex / wordsCount;
+        float x = normalizedIndex * fieldWidth;
+        float y = normalizedIndex * fieldHeight;
+
+        float yOffset = getYOffset(wordIndex, wordsCount, fieldHeight);
+        return new PVector(x, y + yOffset);
+    }
+
+    private float getYOffset(int wordIndex, int wordsCount, int fieldHeight) {
+        float theta = PApplet.map(wordIndex, 0, wordsCount, PConstants.PI, -PConstants.PI);
+
+        return (float) Math.sin(theta) * (fieldHeight / 3f);
+    }
+}

data/src/wordcram/Word.java

@@ -0,0 +1,357 @@
+package wordcram;
+
+import java.util.HashMap;
+
+import processing.core.PFont;
+import processing.core.PVector;
+
+/**
+ * A weighted word, for rendering in the word cloud image.
+ * <p>
+ * Each Word object has a {@link #word} String, and its associated {@link #weight}, and it's constructed
+ * with these two things.
+ *
+ *
+ * <h3>Hand-crafting Your Words</h3>
+ *
+ * If you're creating your own <code>Word[]</code> to pass
+ * to the WordCram (rather than using something like {@link WordCram#fromWebPage(String)}),
+ * you can specify how a Word should be rendered: set a Word's font, size, etc:
+ *
+ * <pre>
+ * Word w = new Word("texty", 20);
+ * w.setFont(createFont("myFontName", 1));
+ * w.setAngle(radians(45));
+ * </pre>
+ *
+ * Any values set on a Word will override the corresponding component ({@link WordColorer},
+ * {@link WordAngler}, etc) - it won't even be called for that word.
+ *
+ * <h3>Word Properties</h3>
+ * A word can also have properties. If you're creating custom components,
+ * you might want to send other information along with the word, for the components to use:
+ *
+ * <pre>
+ * Word strawberry = new Word("strawberry", 10);
+ * strawberry.setProperty("isFruit", true);
+ *
+ * Word pea = new Word("pea", 10);
+ * pea.setProperty("isFruit", false);
+ *
+ * new WordCram(this)
+ *   .fromWords(new Word[] { strawberry, pea })
+ *   .withColorer(new WordColorer() {
+ *      public int colorFor(Word w) {
+ *        if (w.getProperty("isFruit") == true) {
+ *          return color(255, 0, 0);
+ *        }
+ *        else {
+ *          return color(0, 200, 0);
+ *        }
+ *      }
+ *    });
+ * </pre>
+ *
+ * @author Dan Bernier
+ */
+public class Word implements Comparable<Word> {
+
+    public String word;
+    public float weight;
+
+    private Float presetSize;
+    private Float presetAngle;
+    private PFont presetFont;
+    private Integer presetColor;
+    private PVector presetTargetPlace;
+
+    // These are null until they're rendered, and can be wiped out for a re-render.
+    private Float renderedSize;
+    private Float renderedAngle;
+    private PFont renderedFont;
+    private Integer renderedColor;
+    private PVector targetPlace;
+    private PVector renderedPlace;
+    private WordSkipReason skippedBecause;
+
+    private final HashMap<String,Object> properties = new HashMap<>();
+
+    public Word(String word, float weight) {
+        this.word = word;
+        this.weight = weight;
+    }
+
+    /**
+     * Set the size this Word should be rendered at - WordCram won't even call the WordSizer.
+     * @param size
+     * @return the Word, for more configuration
+     */
+    public Word setSize(float size) {
+        this.presetSize = size;
+        return this;
+    }
+
+    /**
+     * Set the angle this Word should be rendered at - WordCram won't even call the WordAngler.
+     * @param angle
+     * @return the Word, for more configuration
+     */
+    public Word setAngle(float angle) {
+        this.presetAngle = angle;
+        return this;
+    }
+
+    /**
+     * Set the font this Word should be rendered in - WordCram won't call the WordFonter.
+     * @param font
+     * @return the Word, for more configuration
+     */
+    public Word setFont(PFont font) {  // TODO provide a string overload? Will need the PApplet...
+        this.presetFont = font;
+        return this;
+    }
+
+    /**
+     * Set the color this Word should be rendered in - WordCram won't call the WordColorer.
+     * @param color
+     * @return the Word, for more configuration
+     */
+    public Word setColor(int color) {
+        this.presetColor = color;
+        return this;
+    }
+
+    /**
+     * Set the place this Word should be rendered at - WordCram won't call the WordPlacer.
+     * @param place
+     * @return the Word, for more configuration
+     */
+    public Word setPlace(PVector place) {
+        this.presetTargetPlace = place.copy();
+        return this;
+    }
+
+    /**
+     * Set the place this Word should be rendered at - WordCram won't call the WordPlacer.
+     * @param x
+     * @param y
+     * @return the Word, for more configuration
+     */
+    public Word setPlace(float x, float y) {
+        this.presetTargetPlace = new PVector(x, y);
+        return this;
+    }
+
+    /*
+     * These methods are called by EngineWord: they return (for instance)
+     * either the color the user set via setColor(), or the value returned
+     * by the WordColorer. They're package-local, so they can't be called by the sketch.
+     */
+
+    Float getSize(WordSizer sizer, int rank, int wordCount) {
+        renderedSize = presetSize != null ? presetSize : sizer.sizeFor(this, rank, wordCount);
+        return renderedSize;
+    }
+
+    Float getAngle(WordAngler angler) {
+        renderedAngle = presetAngle != null ? presetAngle : angler.angleFor(this);
+        return renderedAngle;
+    }
+
+    PFont getFont(WordFonter fonter) {
+        renderedFont = presetFont != null ? presetFont : fonter.fontFor(this);
+        return renderedFont;
+    }
+
+    Integer getColor(WordColorer colorer) {
+        renderedColor = presetColor != null ? presetColor : colorer.colorFor(this);
+        return renderedColor;
+    }
+
+    PVector getTargetPlace(WordPlacer placer, int rank, int count, int wordImageWidth, int wordImageHeight, int fieldWidth, int fieldHeight) {
+        targetPlace = presetTargetPlace != null ? presetTargetPlace : placer.place(this, rank, count, wordImageWidth, wordImageHeight, fieldWidth, fieldHeight);
+        return targetPlace;
+    }
+
+    void setRenderedPlace(PVector place) {
+        renderedPlace = place.copy();
+    }
+
+    /**
+     * Get the size the Word was rendered at: either the value passed to setSize(), or the value returned from the WordSizer.
+     * @return the rendered size
+     */
+    public float getRenderedSize() {
+        return renderedSize;
+    }
+
+    /**
+     * Get the angle the Word was rendered at: either the value passed to setAngle(), or the value returned from the WordAngler.
+     * @return the rendered angle
+     */
+    public float getRenderedAngle() {
+        return renderedAngle;
+    }
+
+    /**
+     * Get the font the Word was rendered in: either the value passed to setFont(), or the value returned from the WordFonter.
+     * @return the rendered font
+     */
+    public PFont getRenderedFont() {
+        return renderedFont;
+    }
+
+    /**
+     * Get the color the Word was rendered in: either the value passed to setColor(), or the value returned from the WordColorer.
+     * @return the rendered color
+     */
+    public int getRenderedColor() {
+        return renderedColor;
+    }
+
+    /**
+     * Get the place the Word was supposed to be rendered at: either the value passed to setPlace(),
+     * or the value returned from the WordPlacer.
+     * @return 
+     */
+    public PVector getTargetPlace() {
+        return targetPlace;
+    }
+
+    /**
+     * Get the final place the Word was rendered at, or null if it couldn't be placed.
+     * It returns the original target location (which is either the value passed to setPlace(),
+     * or the value returned from the WordPlacer), plus the nudge vector returned by the WordNudger.
+     * @return If word was placed, it's the (x,y) coordinates of the word's final location; else it's null.
+     */
+    public PVector getRenderedPlace() {
+        return renderedPlace;
+    }
+
+    /**
+     * Indicates whether the Word was placed successfully. It's the same as calling word.getRenderedPlace() != null.
+     * If this returns false, it's either because a) WordCram didn't get to this Word yet,
+     * or b) it was skipped for some reason (see {@link #wasSkipped()} and {@link #wasSkippedBecause()}).
+     * @return true only if the word was placed.
+     */
+    public boolean wasPlaced() {
+        return renderedPlace != null;
+    }
+
+    /**
+     * Indicates whether the Word was skipped.
+     * @see Word#wasSkippedBecause()
+     * @return true if the word was skipped
+     */
+    public boolean wasSkipped() {
+        return wasSkippedBecause() != null;
+    }
+
+    /**
+     * Tells you why this Word was skipped.
+     *
+     * If the word was skipped, this will return a {@link WordSkipReason}
+     * explaining why.
+     * 
+     * If the word was successfully placed, or WordCram hasn't
+     * gotten to this word yet, this will return null.
+     *
+     * @return the {@link WordSkipReason} why the word was skipped, or null if
+     * it wasn't skipped.
+     */
+    public WordSkipReason wasSkippedBecause() {
+        return skippedBecause;
+    }
+
+    void wasSkippedBecause(WordSkipReason reason) {
+        skippedBecause = reason;
+    }
+
+    /**
+     * Get a property value from this Word, for a WordColorer, a WordPlacer, etc.
+     * @param propertyName
+     * @return the value of the property, or <code>null</code>, if it's not there.
+     */
+    public Object getProperty(String propertyName) {
+        return properties.get(propertyName);
+    }
+
+    /**
+     * Set a property on this Word, to be used by a WordColorer, a WordPlacer, etc, down the line.
+     * @param propertyName
+     * @param propertyValue
+     * @return the Word, for more configuration
+     */
+    public Word setProperty(String propertyName, Object propertyValue) {
+        properties.put(propertyName, propertyValue);
+        return this;
+    }
+
+    /**
+     * Displays the word, and its weight (in parentheses).
+     * <code>new Word("hello", 1.3).toString()</code> will return "hello (0.3)".
+     */
+    @Override
+    public String toString() {
+        String status = "";
+        if (wasPlaced()) {
+            status = renderedPlace.x + "," + renderedPlace.y;
+        }
+        else if (wasSkipped()) {
+            status = skippedBecause.toString();
+        }
+        if (status.length() != 0) {
+            status = " [" + status + "]";
+        }
+        return word + " (" + weight + ")" + status;
+    }
+
+    /**
+     * Compares Words based on weight only. Words with equal weight are arbitrarily sorted.
+     * @param w
+     */
+    @Override
+    public int compareTo(Word w) {
+        if (w.weight < weight) {
+            return -1;
+        }
+        else if (w.weight > weight) {
+            return 1;
+        }
+        else return 0;
+    }
+    
+    // Note: these are only so we can delegate to EngineWord for getShape().
+    private EngineWord engineWord;
+    void setEngineWord(EngineWord engineWord) {
+    	this.engineWord = engineWord;
+    }
+    
+
+    // These are down here, because it comes from the EngineWord, *not* from the Fonter, Angler, etc.
+    /**
+     * Gets the width, in pixels, of the java.awt.Shape that will be rendered for 
+     * this Word, based on the Font, Angle, and Size for this Word.
+     * If that all hasn't been figured out yet, then this returns 0.
+     * @return The width in pixels of this Word's Shape, or 0, if it hasn't 
+     * been rendered yet.
+     * @see #getRenderedHeight()
+     */
+    public float getRenderedWidth() {
+    	if (engineWord == null) return 0.0f;
+    	return (float)engineWord.getShape().getBounds2D().getWidth();
+    }
+
+    /**
+     * Gets the height, in pixels, of the java.awt.Shape that will be rendered for 
+     * this Word, based on the Font, Angle, and Size for this Word.
+     * If that all hasn't been figured out yet, then this returns 0.
+     * @return The height in pixels of this Word's Shape, or 0, if it hasn't 
+     * been rendered yet.
+     * @see #getRenderedWidth()
+     */
+    public float getRenderedHeight() {
+    	if (engineWord == null) return 0.0f;
+    	return (float)engineWord.getShape().getBounds2D().getHeight();
+    }
+}