-
Notifications
You must be signed in to change notification settings - Fork 21
API: Moving from v1 to v2
The v1 of the landmarker.io API had some deficiencies that have been addressed in a revised specification - v2. v2 of the client and server was rolled out on 7th January 2015.
Only the landmark specification itself has changed - the rest of the API is left unchanged. Due to the breaking change the root of the API has been bumped from ap1/v1 to ap1/v2.
landmarker.io's v1 format was built on the concept of unique landmark groups. Each group had it's own set of points and connectivity - and no connectivity could exist between groups. Furthermore, each landmark belonged to exactly one group.
This markup makes a lot of sense for the restricted setting that landmarker.io was designed for. However, menpo (the library that landmarker.io's server component depends on) has a more flexible landmarking model. In this model a landmark definition (confusingly also called a LandmarkGroup) contains one master ordered set of points with optional connectivity information. Sub groups (known as Labels) are then taken from the master point set. In this definition a point can exist in many Labels, and connectivity is permitted between Labels.
Two important goals are on the horizon for landmarker.io, one is to be available as an IPython widget from inside Menpo, and second is to have a predictive mode that utilises menpo on the server to do interesting things to aid annotators. As we aim to bring menpo and the landmarker closer together, the difference in the annotation formats becomes an increasing pain.
v2 of the LJSON format (the format used directly to communicate annotations between the server and client component of landmarker.io) addresses this gap by adopting the menpo annotation model.
It means you are still using a v1 landmarkerio-server. Updating the landmarking format in landmarker.io caused lots of breaking changes to the codebase, so the client available at www.landmarker.io assumes it is talking to a v2 server. To give people already using the landmarker a chance to upgrade, for a limited time only the landmarker will check to see if a v1 endpoint is available. If it is it will redirect you to www.landmarker.io/v1, a freeze of the landmarker before the v2 changes. This version of the tool prominently displays the legacy message.
Any updates and improvements to landmarker.io and the server will only be happening on top of this v2 client, so you are encouraged to update your landmarker.io server at your earliest convenience.
Just get the latest version of our conda package by activating your landmarker conda environment and then running
(lmio) > conda install -c menpo landmarkerio
Note that you will have to 'upgrade' any ljson files you have to the new format. You only need to do this once. landmarkerio ships with a command line utility for this purpose - just run:
lmioconvert ./some/path
to recursively update all LJSON files found in place to the new standard. Please please make a backup of your landmarks before running the tool - you have been warned!
Yes, for now the template format is the same as it was before. This template format is no longer powerful enough to do everything that the new landmarker can handle (e.g. one point in multiple groups) but we will update the template specification to something based on YAML down the line.