Issues with the spec doc
oldskool73
Re the spec doc here :
http://fffff.at/gml/
....just thought I'd mention two little things that gave me a few
headaches yesterday when first working with GML...
1) The point time fields in the doc are named 't', but this doesn't
work with any of the existing players. In the end I noticed that all
the GML on 000000book uses the title 'time' instead, so I changed to
that and it works.
2) Being lazy, I copied and pasted from the page and was creating my
gml from that. As Jamie finally spotted, the end 'environment' tag in
the doc has an extra space, and that space being included in my GML
was completely throwing the GraffAnalysis app (but oddly not the
others).
Nothing major, but fixing them up may make it easier for someone else
down the line :)
Cheers,
A
Jamie Wilkinson
I've made a repository for the "Official GML Spec" to track of edits while I bring it up to speed:
http://github.com/jamiew/gml-spec
Will announce on this list when we update anything for further peer review.
Thx for the heads up, you guys rock
-jamie
> --
> -~-~-~-~-~-~>
> GML Mailing List: http://groups.google.com/group/graffiti-markup-language
> Unsubscribe: graffiti-markup-la...@googlegroups.com
toxi
I just heard about this project again due to the recent Obama playa
release and its use of my library, so I thought I'd take a closer look
at the spec again to see if it has drastically changed since the 1st
release. Whilst there're comments in the XML, some key points still
seem to be a bit obscure/not clear to me and so it'd be great to get
some clarification on those. Please don't take my prodding below as
anything but constructive criticism! I'd just like to get a better
understanding of your thinking behind some of the current syntax
constructs and wonder if they couldn't be improved/made more clear...
One of the benefits of XML based formats is legibility for both
machines & humans and semantics should be clear/self-documenting...
<Client> node:
1) What is the role and use case(s) for the data stored in the
<client> node? In my imagination, I'd understand a client to be a
consumer of GML data (e.g. the Obama playa) and if this is so, why
would we need to store its IP, geoloc etc.? The semantics of those
bits in the example documents seem to more indicate the actual
authorship info and references to the tool used to generate the GML,
no?
2) What is the difference between the <permalink> & <uniqueKey> nodes?
A permalink URL is by definition a unique identifier, why need the
other? And what format is the uniqueKey supposed to take? It certainly
doesn't look like GUID (http://en.wikipedia.org/wiki/GUID) or URI -
using the latter would be much preferable, especially if your aiming
at the linked data web...
3) Why are keywords comma separated and not specified as multiple
<keyword> nodes, which would allow parsing them into a list structure
directly and generating the XML from a database easier too?
4) What scope is the <username> value supposed to be valid under? Why
not use the artist's home URL, email address (or SHA1 of the email for
privacy reasons)? E.g. See FOAF for inspiration:
http://xmlns.com/foaf/spec/#term_mbox_sha1sum - Is GML designed to
have a direct dependency on 000000book.com?
5) I'm aware it's easiest to express times in openFrameworks as *nix
timestamp, but I would still propose to rather change this to a more
human friendly format, just as in Atom/RSS formats. My vote would go
to ISO 8601 which comes in different levels of precision, supports
timezones and seems to provide a good compromise between ease of human
& machine parsing... E.g. 20100909T23:14:00Z - http://en.wikipedia.org/wiki/ISO_8601
<Environment> node:
1) Which of the 2 nodes refers to the tag's centroid: <offset> or
<origin>? Here I'd propose to also include (or replace one of them
with) a bounding rect/box node (in normalized coords) so that tags can
be easier scaled & transformed around their bounding rect's centroid.
2) What is the value range of offset/origin? Normalized or screen
space coords?
3) What is the value range of rotations? Degrees or radians?
<Drawing> node:
1) Why is the <brush> considered a child of the <stroke> node if you
imply (via the <spec> node) that brush descriptions are top level
objects (like tags) and will at some point be able to be loaded from a
URL. Since you already have a <tag> top level node (currently slightly
obsolete, see other comment below), it'd make sense to consider moving
<brush> definitions to the same top level and keep the one within
<stroke> to just reference one of those global brushes & override
already set parameters for just that stroke.
2) Why is the <layerAbsolute>/<layerRelative> a property of a brush
and not of a <stroke> directly? It's the strokes which are/can be
layered, no?
3) Again, IMHO the <uniqueID> & <spec> values are semantic duplicates
and I'd refactor the current <uniqueStyleID> node into a URI value
with an option name attribute.
4) Since all other values (coords, vectors) are normalized, why not
keep the colors like this too? Would make it more OpenGL compatible
too... You could also offer a "hex" attribute for 6-digit RGB values
as optional alternative...
<Tag> node:
All GML documents I've seen so far only contain a single tag, so why
have this superfluous <tag> childnode, if <gml> already is your root
node? The <tag> would only make sense if you plan on introducing other
top level elements and/or distributing several tags within one
document (which would break REST principles). Also, for actually being
truly valid XML you should include the <?xml version="1.0"?>
processing instruction as first line...
Last, but not least...
Maybe some of these mentioned slight changes to the overall XML syntax
would make this format a bit friendlier and more flexible/extensible/
future proof. For existing documents the changes to an updated syntax
could be easily automated using a simple XSLT batch process...
Again, I hope these comments are valid & not seen as grating. I'd be +
+grateful for some answers & happy to help with things if needed!
Best,
Karsten.
Theo Watson
Nice to have you on the list and thanks for all the thoughts.
The initial spec was bucket chemistry of sorts so its great to have more eyes on it.
in case you didn't have it this is where we our hashing out the spec
http://piratepad.net/1qjj2eT9Ol
I think some stuff has changed compared to the one on the main site and the main thing being discussed but maybe resolved now is whether the normalized coords should be relative to each other or lose their relative ratios when normalised. You can see a bit of the discussion on the piratepad and also in the pasted thread at the end of my response. Would be interesting to have your thoughts on this matter too.
replies:
> <Client> node:
>
> 1) What is the role and use case(s) for the data stored in the
> <client> node? In my imagination, I'd understand a client to be a
> consumer of GML data (e.g. the Obama playa) and if this is so, why
> would we need to store its IP, geoloc etc.? The semantics of those
> bits in the example documents seem to more indicate the actual
> authorship info and references to the tool used to generate the GML,
> no?
Actually for the most part the client actually is more like content creator or software used to capture the tag.
So this is more in line with 'clients' like Laser Tag, Graffiti Analysis, Fat Tag, Web Marker etc
Having geoloc is nice to be able to say "show me all of the tags recorded within 100 miles of Paris" for example.
> 2) What is the difference between the <permalink> & <uniqueKey> nodes?
> A permalink URL is by definition a unique identifier, why need the
> other? And what format is the uniqueKey supposed to take? It certainly
> doesn't look like GUID (http://en.wikipedia.org/wiki/GUID) or URI -
> using the latter would be much preferable, especially if your aiming
> at the linked data web...
Permalink is actually the link to the tag on 000000book.com eg: http://000000book.com/data/20542
uniqueKey is a key that identifies a particular device or user for the actual software that is capturing the app. eg: iPhone hardware id or a computers ethernet address.
because the uniqueKey can be in lots of different formats it is seen to be a string which can then get hashed server side if needed.
> 3) Why are keywords comma separated and not specified as multiple
> <keyword> nodes, which would allow parsing them into a list structure
> directly and generating the XML from a database easier too?
Good point! :)
> 4) What scope is the <username> value supposed to be valid under? Why
> not use the artist's home URL, email address (or SHA1 of the email for
> privacy reasons)? E.g. See FOAF for inspiration:
> http://xmlns.com/foaf/spec/#term_mbox_sha1sum - Is GML designed to
> have a direct dependency on 000000book.com?
This is a good point - prob be better to generalise it.
With something like
<site>
<domain>000000book.com</domain
<username>theo</username>
</site>
> 5) I'm aware it's easiest to express times in openFrameworks as *nix
> timestamp, but I would still propose to rather change this to a more
> human friendly format,
Is anyone using the timestamp data at the moment? Could be an easy change?
Or even something that is done on upload?
> <Environment> node:
>
> 1) Which of the 2 nodes refers to the tag's centroid: <offset> or
> <origin>? Here I'd propose to also include (or replace one of them
> with) a bounding rect/box node (in normalized coords) so that tags can
> be easier scaled & transformed around their bounding rect's centroid.
Neither :)
Idea was to have this stuff for the iPhone version of Rhonda ( http://rhondaforever.com/ )
<origin> was just meant to be where the world origin was.
<offset> was meant to be any offset or shift that the client wanted to store relative to the origin.
origin in a way is a little redundant but offset I think was meant to be like a gltranslate
a centroid tag and a boundingBox tag in normalized coords would be a good addition.
> 2) Why is the <layerAbsolute>/<layerRelative> a property of a brush
> and not of a <stroke> directly? It's the strokes which are/can be
> layered, no
Yup - should be changed.
> 3) Again, IMHO the <uniqueID> & <spec> values are semantic duplicates
> and I'd refactor the current <uniqueStyleID> node into a URI value
> with an option name attribute.
Cool please feel free to change it on the pirate pad as this is def rough at the moment.
> 4) Since all other values (coords, vectors) are normalized, why not
> keep the colors like this too? Would make it more OpenGL compatible
> too... You could also offer a "hex" attribute for 6-digit RGB values
> as optional alternative...
I am open in regards to this, esp as it isn't being used.
Nice thing about bytes is that it is much more readable due to lack of long floating point values.
but I would be interested to hear others thoughts.
> All GML documents I've seen so far only contain a single tag, so why
> have this superfluous <tag> childnode, if <gml> already is your root
> node? The <tag> would only make sense if you plan on introducing other
> top level elements and/or distributing several tags within one
> document (which would break REST principles). Also, for actually being
> truly valid XML you should include the <?xml version="1.0"?>
> processing instruction as first line...
Well the idea was that we may want to package up a collection of tags in one file.
I think there is still plans to do that, so I think it would be good to keep.
> truly valid XML you should include the <?xml version="1.0"?>
you mean <?gml version="1.0"?> ;)
> For existing documents the changes to an updated syntax
> could be easily automated using a simple XSLT batch process...
Yup that is the plan!
Thanks for all the questions and comments - actually there has been a little bit of discussion about the spec offlist ( by accident ) so I will paste the recent discussions below.
Cheers!
Theo
On 9 Sep 2010, at 21:58, Theo Watson wrote:
> Hi Jerome,
>
> It is solved as we will have screenBounds still be required.
>
> So.....
>
> for
> screenBounds is 1024, 768, 0.0
> screenScale is 1024 in this case.
>
> You have non square coords, ie points are:
>
> x 0-1.0
> y 0.0-0.75
> z 0.0-0.0
>
> 1024 * 1.0 = 1024
> 1024 * 0.75 = 768
> 1024 * 0.0 = 0.0
>
> So you don't actually need to know what the limits are in the normalised x, y and z coords all you need is the screenScale.
> If you need to know the max bounds allowed then you have screenBounds and from that you know which axis is longest and where the center of the screen is.
>
> So this solution should make everyone happy ??
>
>> You don't know what's the z axis ratio.
>
> well if screenBounds is 1024, 768, 200.0 then we know that z can go from 0.0 to 0.19
>
> ----------------------------------------------
> Theo Watson
> http://theowatson.com
> http://openframeworks.cc
> ----------------------------------------------
>
> On 9 Sep 2010, at 21:35, Jerome Saint-Clair wrote:
>
>> Hey heyyyy!!!
>>
>> Sorry guys, but this solution only partially solves this problem.
>> - You have no way to know the original screen ratio. OK, nearly SOLVED
>>
>> These ones remain.
>> - You don't know which axis is the longest one (what if it is z?).
>> - You are not able to know what's the center of the screen.
>> - No direct mapping with OSC, TUIO, (Wiimote?)
>>
>> Plus a new one:
>> You don't know what's the z axis ratio.
>>
>>
>> Jerome
>>
>> -----------------------------------------------------------------
>>
>>
>>
>> On Thu, Sep 9, 2010 at 8:29 PM, Jamie Wilkinson <ja...@jamiedubs.com> wrote:
>>
>> On Sep 9, 2010, at 10:53 AM, Golan Levin wrote:
>>
>> > -- The maximal dimension should go from 0....1.0
>> > -- The minimal dimension should go from 0.... 0.x, where 0 < x <= 1
>> > -- We should add a tag for the aspect ratio, 0.x:1.0, so that tags can be predictively sized without additional data traversal.
>> >
>> > Ummmmm....
>> > g
>>
>> This sounds cool to me I think. We could add an <aspectRatio> tag in addition to the new <boundingRect>
>>
>> Since that's only 1 more tag per file it seems cheap to include both, and easy to calculate when people don't include it.
>>
>> Like, aim to not force people to read & parse all the data before they can draw it correctly...
>
----------------------------------------------
Theo Watson
http://theowatson.com
http://openframeworks.cc
----------------------------------------------
01010101
Apart from the points normalization that we discussed yesterday, and
after reading Toxi's suggestions,
I tried to summarize and reorganize the various screen, environment,
etc ... and come with this proposal.
Maybe the screen/rotation and screen/offset can be replaced in favor
of a camera (like in OPENGL).
I also posted a schema here for better understanding.
http://dl.dropbox.com/u/176277/specs.PNG
<?xml version="1.0" encoding="UTF-8"?>
<gml spec="1.0">
<tag>
<permalink>http://000000book.com/data/156</permalink>
<time>20100909T23:14:00Z</time>
<name>Great top to bottom</name>
<submitter>GDFLGdfgdfjhkdfhk64d6fgd.1g6d46s</submitter><!-- UID -->
<author>Gamil</author>
<location>
<address>29 rue Anatole France, Levallois-Perret, France</address>
<lon>-39.392922</lon>
<lat>53.29292</lat>
</location>
<keywords>
<keyword>graffiti</keyword>
<keyword>France</keyword>
</keywords>
<audio>youraudio.mp3</audio> <!-- path to audio file -->
<background>yourimage.jpg</background> <!-- path to
imagefile -->
<screen>
<bounds>
<!-- for a 1024 * 768 * 200 -->
<x>1</x>
<y>0.75</y>
<z>0.19</z>
</bounds>
<scale>1024</scale>
<up>
<axis>y</axis>
<value>-1</value>
</up>
<centroid>
<x>0.5</x>
<y>0.375</y>
<z>0.95</z>
</centroid>
<realScale>
<value>1000</value>
<units>cm</units>
</realScale>
<rotation>
<x>0</x>
<y>0</y>
<z>0</z>
</rotation>
<offset>
<x>100</x>
<y>-200</y>
<z>300</z>
</offset>
<client>
<!-- -->
</client>
</screen>
<drawing>
<offset>
<x/>
<y/>
<z/>
</offset>
<boundingRect>
<min>
<x>0.1</x>
<y>0.1</y>
<z>0.1</z>
</min>
<max>
<x>0.5</x>
<y>0.5</y>
<z>0.5</z>
</max>
</boundingRect>
<centroid>
<x>0.3</x>
<y>0.3</y>
<z>0.3</z>
</centroid>
<brush id="1">
<name>LaserTagArrowLetters</name>
<spec>http://aurltodescribethebrushspec.com/someSpec.xml</spec>
<color>
<r>1</r>
<g>1</g>
<b>1</b>
<a>1</a>
</color>
<width>10</width>
<speedToWidthRatio>1.5</speedToWidthRatio>
<!-- put 0 for fixed width -->
<dripAmnt>1.0</dripAmnt>
<dripSpeed>1.0</dripSpeed>
<dripVecRelativeToUp>
<!-- what angle do our drips go in relation to our up vector -->
<x>0</x>
<y>1</y>
<z>0</z>
</dripVecRelativeToUp>
</brush>
<stroke>
<layer relative="true" value="-1"/>
<brush>1</brush> <!-- uses the above brush ID -->
<pt>
<pres>0.5</pres> <!-- Optional. Preasure range from 0 to 1 -->
<rot>0.5</rot> <!-- Optional. Rotation range from 0 to 1 for 0 to
2*PI -->
<dir> <!-- Optional Direction -->
<x>0</x> <!-- range from 0 to 1 -->
<y>-0.5</y> <!-- range from 0 to 1 -->
<z>0.5</z> <!-- Optional inside direction. Range from 0 to 1 -->
</dir>
<x>0.1</x>
<y>0.6</y>
<z>0.19</z>
</pt>
</stroke>
</drawing>
</tag>
</gml>
On Sep 10, 10:15 am, Theo Watson <t...@theowatson.com> wrote:
> Hi Toxi,
>
> Nice to have you on the list and thanks for all the thoughts.
> The initial spec was bucket chemistry of sorts so its great to have more eyes on it.
>
>
> read more »
01010101
As the various suggestions break the current sctructure of the GML
spec,
I did a new PiratePad here http://piratepad.net/waWB0nk9Wd
Maybe we can merge later after discussion.
I tried to make everything self explanatory.
If not enough, take a look at http://dl.dropbox.com/u/176277/specs.PNG
Also added a few new optional elements (like duration).
Hope it help,
Jerome
On Sep 10, 11:42 am, 01010101 <jsaintcl...@gmail.com> wrote:
> Hi,
>
> Apart from the points normalization that we discussed yesterday, and
> after reading Toxi's suggestions,
> I tried to summarize and reorganize the various screen, environment,
> etc ... and come with this proposal.
>
> Maybe the screen/rotation and screen/offset can be replaced in favor
> of a camera (like in OPENGL).
>
>
> read more »