The GML Field Recorder Challenge has been extended by two months until Nov. 1. All entries should be emailed to challenge[at]graffitimarkuplanguage[dot]com before this date.

The GML Field Recorder Challenge is a friendly competition to create an easily reproducible DIY device for unobtrusively recording graffiti motion data during a graffiti writer’s normal practice in the city. For full details go to http://www.graffitimarkuplanguage.com/challenges/gml-field-recorder-challenge/

To record GML, you can use a GmlRecorder object.
The simplest constructor of this object takes a single argument which is a 3D vector giving information about the drawing surface.
For instance, if you’re drawing on a flat screen which size is 800×600, creating a new GmlRecorder will look like this:

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

// Declare a GML recorder object
GmlRecorder recorder;

void setup() {
	Vec3D screen = new Vec3D(800, 600, 0);
	recorder = new GmlRecorder(screen);
}

The recorder has 3 different methods that you have to use to record a stroke.
When the drawing of a stroke starts, you have to call the beginStroke method which takes a single argument being a unique ID that you will use when adding points and at the end of the stroke.
Having an ID allows you to draw several strokes in the meantime when needed without messing up points and strokes

recorder.beginStroke(666);


When adding points to a stroke, you need to use a minim of two arguments.
First argument is the unique ID we mentionned above.
Second argument is the coordinates of the point, which have to fit within 0 and 1.
Each value between 0 and 1 has to be the ratio of the point’s coordinates on each axis.
If you screen vector is 800x600x100 and the current coordinates of your point are 400,400, 25, then your point coordinates will be 0.5, 0.66, 0.25

recorder.addPoint(666, new Vec3D(0.5, 0.66, 0.25));


When the drawing of the stroke ends, just call this method with the ID

recorder.endStroke(666);


The recorder handles a Gml object and a temporary stroke list in parallel.
When a stroke ends, it is moved from the temporary list to the Gml object.

Alternatively, you can use the endStrokes() method which will stop all recordings in one shot:

recorder.endStrokes();


Advanced beginStroke

If you intend to work with several layers, you can call the beginStroke method with an extra parameter to store this info along with the stroke information.

recorder.beginStroke(666, 1);


Note: there is a third parameter that you can use which will be covered when we’ll talk about brushes later on.

Advanced GmlPoints

The recorder also has addPoint methods which will accept more complex GmlPoint
addPoint(int sessionID, Vec3D v, final float time);
Takes a 3rd argument to store time information

addPoint(int sessionID, Vec3D v, final float time, final float pressure, final Vec3D rotation, final Vec3D direction);
Takes even more arguments

• Time
• Pressure: think spray can of flow pen
• Rotation: orientation of the tool (ie: spray can)
• Direction: direction of the tool (between two points)

The recorder also includes several useful methods:


recorder.clear()
// Removes all strokes, the Gml ones and the temporary ones.



recorder.removeLastStroke(layer)
// Removes the last stroke from the given layer



recorder.getStrokes()
// Retrieves a list of GmlStrokes (both Gml strokes and temporary strokes)



recorder.getGml()
// Returns a copy of the Gml object used by the recorder



recorder.setGml(gml);
// Will replace the recorder's gml file with this one.
// Can be used to continue drawing from an existing Gml file.


Optimizing recording

Your recording device may send way more points than needed to render a stroke correctly.
If you want to limit the number of points, you may add limitations to the GmlRecorder by adding two extra arguments:


float minimumStrokeLength = 0.01f; // Default value when omitted
float minimumPointsDistance = 0.001f; // Default value when omitted
recorder = new GmlRecorder(screen, minimumStrokeLength, minimumPointsDistance);


By doing so:
When a stroke ends, it will only be recorded in the Gml object if longer than the value you defined.
When adding a point to a stroke, it will only be added if the distance between this point and the last point of the stroke is greater than the value you defined.

These values can be adjusted afterward by calling these two methods with a float argument
recorder.setMinStrokeLength();
recorder.setMinPointsDistance();

Recording with devices

It is handy to use a protocol like OSC or TUIO for recording purpose.
Once you have your recorder understanding such protocol, it means that you can interface with any device or installation which can send OSC or TUIO messages.
It also means that you’ll be able to record several strokes in the meantime.

You can check the two examples provided with the library

• GmlOscRecorder
• GmlTuioRecorder

• The simple way : the execution of your sketch will hang until the file is loaded.
• The threaded way : won’t block your sketch.

In both cases, the result of the parsing will be stored in a Gml object

Simple way

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

// Declare a Gml object
    Gml gml;

void setup() {
    // Loads the gml file into the Gml object
    gml = GmlParsingHelper.getGml(sketchPath+"/sample.gml.xml", false);
}

void draw() {
    // Do things with your gml object
}

The parsing is done through the GMLParsingHelper’s getGml static method.

This method has two arguments:

• The path to you gml file
• A boolean (true, false) to force a normalization of the file.

Normalization means that GML4U will attempt to remove any inconsistency in the stroke points coordinates to make them fit within a 0 -> 1 range.
If omitted (ie: getGml(sketchPath+”/sample.gml.xml”)), the second parameter defaults to true.

Threaded way

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

// Declare a Gml object and GmlParser
Gml gml;
GmlParser parser;

void setup() {
    // Create and start the thread with a 500ms waiting time, a name and a reference to your sketch (this)
    parser = new GmlParser(500, "myParser", this);
    parser.start();
    parser.parse(sketchPath+"/sample.gml.xml", false);
}

void draw() {
    if (null != gml) {
        // Do things with your gml Object
    }
}

// Callback function used by the GmlParser to send the result of the parsing
public void gmlEvent(GmlEvent event) {
    if (event instanceof GmlParsingEvent) {
        GmlParsingEvent parsingEvent = event;
        gml = parsingEvent.gml;
    }
}

Explainations

When the GmlParser is created, il will try to find a public gmlEvent method with a GmlEvent argument.
If missing or incorrect, depending on your log level (something that we will see later on), the GmlParser will log an error and nothing more will happen.
This gmlEvent method will be called at the end of the parsing.
This method takes a generic argument, which is the GmlEvent class.
This is generic to keep a single entry point and avoid the need to have as many callbacks as event types.
To know which event type was returned, you have to test it using the instanceof comparator against one
of the expected classes extending GmlEvent.
Here, we’re expecting a GmlParsing event, so we test if this is correct and create a copy of it to get
the results.

if (event instanceof GmlParsingEvent) {
    GmlParsingEvent parsingEvent = event;
    gml = parsingEvent.gml;
}

This can also be achieved by casting the GmlEvent to a GmlParsingEvent but to me it’s less readable.

if (event instanceof GmlParsingEvent) {
   gml = ((GmlParsingEvent) event).gml;
}

• The simple way : the execution of your sketch will hang until the file is saved.
• The threaded way : won’t block your sketch.

Simple way

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

// Gml object
Gml gml;

void setup() {
	gml = new Gml();
}

void draw() {
	// Add strokes, ... to your Gml object
}

void keyPressed() {
	if (key == 's' || key == 'S') {
		GmlSavingHelper.save(gml, sketchPath+"/gml.xml");
	}
}

The saving is done through the GMLSavingHelper’s save() static method.
This method has two arguments:
- The Gml object to be saved
- The path where is should be saved

Threaded way

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

// Declare a Gml object and GmlParser
Gml gml;
GmlSaver saver;

void setup() {
	// Create and start the thread with a 500ms waiting time, a name and a reference to your sketch (this)
	saver = new GmlSaver(500, "mySaver", this);
	saver.start();
}

void draw() {
	// Add strokes, ... to your Gml object
}

void keyPressed() {
	if (key == 's' || key == 'S') {
		saver.save(gml, sketchPath+"/gml.xml");
	}
}

// Callback function used by the GmlSaver to send the result of the saving
public void gmlEvent(GmlEvent event) {
	if (event instanceof GmlSavingEvent) {
		GmlSavingEvent savingEvent = event;
		boolean result = savingEvent.successful;
		String location = savingEvent.location;
		println((result ? "Succeeded" : "Failed")+ " saving Gml file to " + location);
	}
}

Explainations
When the GmlSaver is created, il will try to find a public gmlEvent method with a GmlEvent argument.
If missing or incorrect, depending on your log level (something that we will see later on), the GmlSaver will log an error and nothing more will happen.
This gmlEvent method will be called at the end of the saving.
This method takes a generic argument, which is the GmlEvent class.
This is generic to keep a single entry point and avoid the need to have as many callbacks as event types.
To know which event type was returned, you have to test it using the instanceof comparator against one of the expected classes extending GmlEvent.
Here, we’re expecting a GmlSaving event, so we test if this is correct and create a copy of it to get the results.

if (event instanceof GmlParsingEvent) {
	if (event instanceof GmlSavingEvent) {
		GmlSavingEvent savingEvent = event;
		boolean result = savingEvent.successful;
		String location = savingEvent.location;
		println((result ? "Succeeded" : "Failed") + " saving Gml file to " + location);
	}
}

As seen before for the GmlParsingEvent, this can also be achieved by casting the GmlEvent to a GmlSavingEvent

if (event instanceof GmlSavingEvent) {
	boolean result = ((GmlSavingEvent) event).successful;
	String location = ((GmlSavingEvent) event).location;
	println((result ? "Succeeded" : "Failed")+ " saving Gml file to " + location);
}

You can attach a brush info to give more info about a GmlStroke.
This basically allows you to store information about the tool used to draw and thus reuse this info when you’ll redraw what you captured.


GmlBrush brush = new GmlBrush();

This constructor without arguments will create a new GmlBrush using the default brush from GML4U (curve).
You can add as many parameter to it, just knowing it only accepts 6 kind of object:

Vec3D
String
Integer
Float
Long
Color

When adding a parameter, you have to give it a name (String) that you can use later on when you want to retrieve a specific parameter.


brush.set("alpha", 128);
brush.set("cap", "fat");


When retrieving a parameter, you’ll have to know his type and cast it to get the correct value because the brush’s get method returns generic objects.


String capType = (String) brush.get("cap");
int alphaChannel = (int) brush.get("alpha");


When saving as a GML file, your brush information will be automatically saved to the correct format. Same thing when loading the saved file.

There are already a few predefined brushes that you can use without having to create custom ones.

You can get a list of pre-existing brushes through the GmlBrushManager

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

GmlBrushManager brushManager = new GmlBrushManager();

void setup() {
	for (String styleId : brushManager.getStyles()) {
		println(styleId);
	}
}

At the time being, you should get this as output:

GML4U_STYLE_CURVES0000
GML4U_STYLE_BOXES0000
GML4U_STYLE_MESH0000

Forcing styles

(Maybe take a look at the “Drawing Gml” tutorial first)
You may bypass the GmlStroke brush information by explicitely passing a style information to the GmlBrushManager’s draw method.

By default, the GmlBrushManager contains a certain number of predefined GmlStrokeDrawers.
You can make reference those styles using one of these parameters:
GML4U_STYLE_CURVES0000
GML4U_STYLE_BOXES0000
GML4U_STYLE_MESH0000

So, if you want to use boxes rather than a simple curve stroke, you can call the GmlBrushManager with an extra parameter.

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

GmlBrushManager brushManager = new GmlBrushManager();
Gml gml;

void setup() {
	// ie: Load a Gml file
}

void draw() {
	brushManager.draw(g, gml, 600, "GML4U_STYLE_BOXES0000");
}

Here is another example which allows you to loop through all the registered styles easily using the + and – keys while your sketch is running.

import gml4u.brushes.*;
import gml4u.recording.*;
import gml4u.test.*;
import gml4u.utils.*;
import gml4u.drawing.*;
import gml4u.events.*;
import gml4u.model.*;

GmlBrushManager brushManager = new GmlBrushManager();
Gml gml;
int currentStyle = 0;

void setup() {
	// ie: Load a Gml file
}

void draw() {
	brushManager.draw(g, gml, 600, GmlBrushManager.get(currentStyle);
}

void keyPressed() {
	if (key == '-') {
		currentStyle--;
		if (currentStyle < 0) currentStyle = GmlBrushManager.size()-1;
	}
	else if (key == '+') {
		currentStyle++;
		if (currentStyle == GmlBrushManager.size()) currentStyle = 0;
		}
	}
}