Contribution guide
Download the complete guide with schematics here
Implementing an Augmenta library (addon, module, node, object...) for your usual tool is pretty easy and should be done according to the guidelines below.
This document describes some specifications about the basic features each Augmenta library should offer. It ensures that users won't be lost when changing from one tool to another and allows code to be easily ported.
The name of the library should be following the naming convention of your tool. For example "ofxAugmenta" for OpenFrameworks, "AugmentaP5" for Processing... If there is no convention for naming the library, you can simply append the name of your technology, like "AugmentaUnity".
If needed, you can add the prefix "Augmenta" or "au" to specify that an object is linked to Augmenta.
The following guidelines must be applied when creating a new library for a tool. Following those guideline will help achieve a good working result faster and avoid bugs. Nevertheless, those are recommendations, feel free to adapt if needed.
The different classes that should be implemented are the following:
- AugmentaObject : Contains all the Augmenta data of one object received in the OSC messages (cf Augmenta protocol). If possible, has a Draw() function that displays all info (centroid, bounding box, pid, etc.).
- AugmentaScene : Contains all the Augmenta data about the scene received in the OSC messages (cf Augmenta protocol). The most important info that will be used is the scene width/height sent by Augmenta.
- Main Object : The main object should have the name of the library. The instance of this object in the example code can be named augmentaReceiver or auReceiver. It should contain an AugmentaScene and an array (or equivalent) of AugmentaObject representing all the objects in the scene. It should listen for incoming OSC messages (default port should be 12000) and start listening right away. It should have tools like isConnected() to check if the port has already been successfully bound by the lib, or reconnect() to connect to a new OSC port on the fly. The main object will handle the OSC messages and should provide helper functions as described below.
The main object listens to four specific OSC messages: /scene: sent around 30 times per second to update the scene info, /object/enter: a new object entered the scene, /object/update: an object already present has been updated, /object/leave: an object already present is about to leave the scene. The scene info must be stored into the AugmentaScene object. Every “object” message leads to either adding, updating or removing an AugmentaObject in the array containing all the objects present in the scene.
The messages are sent using the UDP protocol, thus messages can be lost. This means that when you write a library you have to add safety mechanisms. If an update message is sent for an object that doesn’t exist (check its id), it should be created. Also, if an AugmentaObject has not been updated for a certain amount of time, it is considered missing and should be removed. Set the number of frames, or seconds, with a setTimeOut() function (with default 120 frames/3 seconds for example).
The main object (the receiver) should expose several functions:
- A function to get all AugmentaObject, allowing to easily iterate over every Augmenta object. This function could be called getObjectsArray() for example.
- The two methods: getNewestObject() and getOldestObject(). They both return the AugmentaObject which has the (respectively) smallest / greatest “age” value, or null if no one is in the scene. The oldest object is usually the most used, because you often want the first object that has entered the scene to keep interacting even if something else entered after it. It can also prevent noise from disturbing the experience.
- The library should register and call the following callback methods, which should be triggered at every similar OSC event (or when a person is artificially added/removed). It provides the AugmentaObject as an argument.
void objectEntered (AugmentaObject o) {
print(“Object entered: "+ o.pid );
};
void objectUpdated (AugmentaObject o) {
print(“Object updated: "+ o.pid );
};
void objectWillLeave (AugmentaObject o) {
print(“Object left: "+ o.pid );
};
These functions can then be used by the user to define specific behaviours for each event.
The library should contain use case examples of the library. It should at least contain a minimalist example with no external library dependencies (except an OSC parsing library if needed). This example should simply display a point for each AugmentaObject and a point of a different color for the oldest/newest object. The draw() function of the AugmentaObject should be used to draw all data so the user can quickly test the library.
Other examples should contain:
- an easy way of changing the OSC port through GUI and ideally the window size.
- a visual feedback to warn if the OSC port could not be opened
- a toggle button to enable a debug view drawing all the data with the draw() method
Some other nice example:
- Syphon/Spout output
- 3D bounding box drawing
- Assets example (audio/sprites or others)
- Nice visual effects examples
- Nice use case examples
- TUIO support
When you start working on your library, addon or plugin, or even when it is not fully ready, do not hesitate to contact us at contact@augmenta-tech.com so we can add it to the official repositories and documentation and help you share it with the world.