A guide to contribute to the Augmenta project https://github.com/Theoriz/Augmenta

1. Tom Duchêne :: David-Alexandre Chanel
Augmenta contribution guide
https://github.com/Theoriz/Augmenta/wiki

2. Introduction
Implementing an Augmenta library (or addon, module, node,
object…) for your usual tool is pretty easy !
This document is here to give some specifications about the
basic features each Augmenta library should offer.
It ensures that users won’t be lost when changing from one
technology to another, and allows code to be easily ported.
Let’s start coding !

3. General
• The repository must contain a clear step by step and noob proof
Readme.md file (ex : https://github.com/Theoriz/AugmentaP5)
• It must contain the lib and the examples following the
specifications of this doc
• It must be as clear and commented as possible so the community
can help maintain it in a good shape : )
• The lib must not be dependent of any other external lib except
OSC (if it’s not native)

4. Naming and conventions
• The name of the lib should be “Augmenta”, in the fashion of the
technology it is implemented for (“ofxAugmenta” for
OpenFrameworks, “AugmentaP5” for processing, etc.).
If there is no convention for naming the libraries, you can simply append the name of
the technology (AugmentaUnity for example)
• If needed, you can add the prefix “Augmenta” or “au” to specify
that an object is linked to Augmenta
• For everything else, use the code conventions of the technology
you’re using

5. Objects
Here are the different objects (or classes) that should be implemented :
• The object containing the Augmenta data for one person should be
called AugmentaPerson
• The object containing the Augmenta data of the whole scene
should be called AugmentaScene
• The main object should have the name of the lib. The instance of this
object in the example code can be called augmentaReceiver,
auReceiver or simply receiver

6. AugmentaPerson
• Contains all the Augmenta data of one person sent in the OSC
messages (see next slide)
• If possible, has a draw() function that displays all info (centroid,
bounding box, id, etc.)

7. AugmentaPerson data
/au/personEntered args0 arg1 ...
/au/personWillLeave args0 arg1 …
/au/personUpdated args0 arg1 …
Where args are :
0: pid (int)
1: oid (int)
2: age (int)
3: centroid.x (float 0-1)
4: centroid.y (float 0-1)
5: velocity.x (float 0-1)
6: velocity.y (float 0-1)
7: depth (float)
8: boundingRect.x (float 0-1)
9: boundingRect.y (float 0-1)
10: boundingRect.width (float 0-1)
11: boundingRect.height (float 0-1)
12: highest.x (float 0-1)
13: highest.y (float 0-1)
14: highest.z (float 0-1)
// Personal ID ex : 42th person to enter has pid=41
// Ordered ID ex : 3rd person still present has oid=2
// Time on stage (in frame number)
// Position projected to the ground
// Speed and direction vector
// Distance to sensor (in m) (not implemented)
// Top view bounding box
// Highest point placement
// Height of the person (not implemented)
OSC messages sent for each detected person :
Data protocol is up-to-date here :
https://github.com/Theoriz/Augmenta/wiki

8. AugmentaScene
• Contains all the Augmenta data of the scene sent in the OSC
message sent each frame (see next slide)
• The most important info we’ll use is the scene’s width/height sent by
Augmenta

9. AugmentaScene data
/au/scene args0 arg1 …
Where args are :
0: currentTime (int)
1: percentCovered (float 0-1)
2: numPeople (int)
3: averageMotion.x (float 0-1)
4: averageMotion.y (float 0-1)
5: scene.width (int)
6: scene.height (int)
7: scene.depth (int)
OSC message sent each frame to describe the
scene :
Data protocol is up-to-date here :
https://github.com/Theoriz/Augmenta/wiki

10. Main object
• Contains an AugmentaScene and an array (or vector, etc.) of
AugmentaPerson representing all the people in the scene.
• It should be created with a given OSC port (or with default 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 provide three use
paradigms to the users (see next slides)

11. Handle the OSC messages
• The main object listens to four specific OSC messages :
– /au/scene : sent everyframe to update the scene info
– /au/personEntered : a new person entered the scene
– /au/personUpdated :a person already present has been updated
– /au/personWillLeave :a person already present is about to leave the scene
• The scene info is directly stored into the AugmentaScene object
• Every “person” message leads to either adding / updating / removing an
AugmentaPerson in the array containing all the people present in the scene
(Warning : If an update message is sent for a person that doesn’t exist, it must
be created)
• For safety reasons, if an AugmentaPerson has not been updated for a certain
number of frames, it is considered missing and must be removed. Set the
number of frames with a setTimeOut() function (default 120).

12. Paradigm #1
After having handled the OSC messages, there are three paradigms to
implement in the main object. Here is the first one (iterative looping) :
• The user may want to simply iterate over all the people in the scene
• Then we have to provide a way to get the AugmentaPeople
array/vector/etc. containing all the AugmentaPerson
• The function can be named getPeopleArray() for example

13. Paradigms #2
• The second paradigm is dataflow/event oriented
• The lib 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 AugmentaPerson as an argument.
void personEntered (AugmentaPerson p) {
print(“Person entered : "+ p.pid );
};
void personUpdated (AugmentaPerson p) {
print(“Person updated : "+ p.pid );
};
void personWillLeave (AugmentaPerson p) {
print(“Person left : "+ p.pid );
};
• The user can simply implement those methods in his code to get notified
when a change occurs and get the person related to it.

14. Paradigms #3
• The third paradigm is especially useful when only one user is supposed
to interact, or for quick prototyping.
• The lib must implement the two following methods :
getNewestPerson() and getOldestPerson()
• They both return the AugmentaPerson which has the (respectively)
smallest / greatest “age” value, or null if no one is in the scene.
• The oldest person is the most used, because you often want the first
person that has entered the scene to keep interacting even if someone
else came after him. It also prevent noise from disturbing the
experience.

15. Examples
The repository must contain some examples following those
guidelines :
• It must contain a minimalistic example with no external
libraries dependency (no external GUI, no Syphon, nothing)
– The example should simply display a point for each AugmentaPerson and
a point of a different color for the oldest/newest person
– The draw() function of the AugmentaPerson should be used to draw all
data so the user can quickly test the lib

16. Examples
The other examples should contain :
• A graphical easy way of changing the OSC port (and ideally the
window size)
• An implementation of the isConnected() method to warn in the
graphical interface if the port is already bound (draw the OSC
port in green if OK, red if not connected)
• The autoSize feature, which resizes the output texture or window
to the correct size of the current frame (contained in
AugmentaScene).
• A toggle button to enable a debug view drawing all the data
with the draw() method

17. Examples
Some other “Nice to have” options for examples :
• Syphon/spout output
• 3D bounding box drawing
• Assets example (audio/sprites or others)
• Nice visual effects examples
• Nice use case examples
• TUIO support

18. Share !
When you start working on your library / addon / plugin or even
when it’s fully ready, don’t hesitate to contact us so we can add
it to the official repos/documentation and give you our warmest
thanks for contributing to this exciting project !
contact@theoriz.com
https://github.com/Theoriz/Augmenta