What's this?

This is a platform for managing an image dataset. It's designed to make it easy for anyone to upload images, annotate them, and for people who need images to search for them. There's also a JSON API for automating tasks. It's also free software under the GNU AGPLv3.

Querying for pictures

The query format is based on YAML and used to query for pictures in the system.

Structure

The root can have 3 keys:

want and exclude are lists of rules. Each rule is a dictionary with a single key (this is to allow multiple rules of the same kind). Accepted rules are:

ordering, offset and limit can be specified as query parameters in the URL. ordering can be one of date-desc, date-asc, title-asc, title-desc, number-regions-desc, number-regions-asc, random. offset and limit are integers that specify the number of images to skip and the maximum number of images to return, respectively.

Example

# Restrictions for queried images
want:
   # This means that the image must contain both rules, so both a cat and a dog
   - has_object: ["Cat (Felis catus)"]
   - has_object: ["Dog (Canis lupus familiaris)"]
   # Or we can put them in a list to mean that the image can contain any of the
   # objects in the list
   - has_object: ["Grass", "Flower"]
   # So the image must contain a cat and a dog, as well as either grass or
   # a flower
   # The following rule restricts the images to those with a certain source,
   # like a camera or a drawing; omitting this rule means that the images can
   # be of any source
   - nature: ["photo", "computer-3d-art"]
   # The following rule restricts the images to those with a certain licence
   - licence: ["CC-BY-1.0", "CC-BY-2.0", "CC-BY-3.0", "CC-BY-4.0", "CC0-1.0",
               "Unlicense", "WTFPL", "MIT", "BSD-2-Clause", "BSD-3-Clause",
               "Apache-2.0", "X-informal-attribution", "X-informal-do-anything",
               "X-public-domain-old", "X-public-domain"]
# Prohibitions for queried images
exclude:
   # This means that the image must not contain any of the objects in the list
   - has_object: ["Human"]
   # This excludes images uploaded before the given date
   - before_date: 1546300800
   # This requires images to have a minimum resolution
   - below_width: 800
   - below_height: 600
# In summary, we want images that contain both a cat and a dog, either a grass
# or a flower, but not a human, taken after 2019-01-01, must be a photo or a
# 3D render, must carry one of certain permissive licences and have a resolution
# of at least 800x600 pixels.

You will get a list of JSON dictionaries with the following keys:

If you query the endpoint /api/picture/<id>/ you will also get:

This is done to avoid processing ratings when they aren't needed.

Raw annotation data format

The client sends raw data for image annotations in a JSON format which is a list of shapes. Each shape is a dictionary with the following keys:

The server sends the same data back to the client, to use to show the existing annotations for an image.

Example

[
   {
       "type": "bbox",
       "shape": {"x": 0.1, "y": 0.1, "w": 0.5, "h": 0.5},
       "object": "Cat (Felis catus)"
   },
   {
       "type": "polygon",
       "shape": [{"x": 0, "y": 0}, {"x": 1, "y": 0}, {"x": 0, "y": 1}],
       "object": "Slice of pizza margherita"
   },
   {
       "type": "point",
       "shape": {"x": 0.5, "y": 0.5},
       "object": "Cat (Felis catus) - left eye"
   }
]

Authenticating with the API

Your HTTP client must support cookies.

POST to /api/login with a JSON body containing keys username and password.

POST to /api/logout to clear the session; you can also just delete the cookie on your own.

User registration isn't supported by the API to prevent spam; use the HTML form.

Uploading from the API

You can upload pictures from the API if you're logged in. POST to /api/upload with a form data containing a key json with the value being a JSON dictionary with title, description, origin_url, licence (list of IDs), nature (ID), and a file file that is your image. The JSON can also have a key annotations if you want to prefill them — check above for the format.

/api/picture/<id>/update allows you to pass title, description, origin_url, licence_ids and nature_id in a JSON body to change an existing picture.

Other endpoints

/api/licence/ provides a dictionary of the licences with the keys being the ID and the value being another dictionary with keys title, free (whether it respects the Four Freedoms) and pinned which indicates if it is at the top of the list.

/api/licence/<id>/ provides more details for the particular licence, including id, title, description, info_url which links to a page with information about the licence, legalese_url which links to the actual legal text, free, pinned and logo_url.

/api/nature/ provides a dictionary of natures of the form id: description.

/api/user/ provides information about users with the key being the name and the value being a dictionary with the admin boolean. It uses offset and limit.

/api/user/<username>/ provides a dictionary with the user's id, admin status and joined date.

POST to /api/picture/<id>/rate with a JSON body with a key rating will put a star rating on the picture. To delete the rating call it with a false value.

/api/gallery/<id> will give metadata about the gallery in JSON: id, title, description, owner and users. To get the pictures you can use a query.

POST to /api/gallery/<id>/edit with keys title and description in JSON to update the gallery metadata.

POST to /api/new-gallery creates a new gallery with keys title and description in the JSON.

POST to /api/gallery/<id>/add-picture with a JSON dictionary containing a key picture_id will add the picture. /api/gallery/<id>/add-picture will do the reverse.

POST to /api/gallery/<id>/users/add with a JSON dictionary containing a key username will trust an user, /api/gallery/<id>/users/remove will do the reverse.