Guide To: Ontology Manager

The Ontology Manager allows job owners to create and edit the ontology within an image or text annotation job. The Ontology Manager supports up to 1,000 unique classes for image shapes, video annotation, and text annotation. For pixel labeling jobs, the class limit is 250 unique classes.

When using cml:shapes and cml:video in conjunction with the parameter ontology=”true”, you will be prompted to create an ontology from the design page of the job. In contrast, all text annotation jobs (cml:text_annotation) will require an ontology and you will receive the prompt automatically when adding a text annotation form element. There are two ways to create an ontology:

Creating an ontology via the UI

You can create and edit an ontology using the Ontology Manager within the job. On this page, you’ll see three columns: color, title, and description.

Fig. 1: Ontology Manager

• Color defaults to a randomly selected value, but can be customized using a selector by clicking on the arrow next to the color.
• Title is a required field. This is the name of the class in the ontology; it is what contributors will see when annotating. Be aware, each title must be unique and differ from any other class names.
• Report Value is optional. This is a UUID value that will be placed in the 'report_value' column of the results to be used as a key for the classes in the ontology. This is especially useful for longer, more complex ontologies.
  • Any report values filled in will be displayed in the results JSON.
    • Example: [{"id":"11c91068-73b5-4c32-bc25-d059fe9d4fc4","class":"Car non-occuluded","report_value":"nonoccluded_car","type":"box","coordinates":{"x":263,"y":438,"w":513,"h":368}}]
  • Important note: Report value is currently only supported in ontologies of video annotation, image annotation, and image transcription jobs.
• Description is optional. This gives contributors a brief, inline description of a class. We highly recommend providing a clear and concise description of each class for the best quality results.

Actions within the Ontology Manager:

1. To add a new class, click ‘Add Class’. This will insert another row below the last class created.
2. To delete a class, hover over its row in the table and click the trash icon to the right.
3. If desired, you can nest ontologies (create a hierarchical tree of classes to label) by dragging and dropping.
4. Once you’ve created your ontology, click ‘Save’.
5. To edit the color, title, description, and output value for each class click on the pencil icon

Important Note: Ontologies cannot be updated while a job is running/paused.

Fig 2: Nesting Ontologies with the Ontology Manager

Fig. 3: Nested Ontology

Ontology Manager Settings:

The settings allow you to configure how nesting should behave in the ontology. If you have nesting in your ontology and would like parent classes to act as directories (for an organization, rather than as an annotatable class), you can turn that on under the settings button.

Fig. 4: Ontology Settings

Creating an ontology via CSV/JSON upload

You can also create an ontology by uploading a CSV (for flat ontologies) or JSON (for nested ontologies). To do so, you can follow these steps:

1. Create a UTF-8 encoded CSV with your ontology. You’ll need the following column headers:
• display_color (requires a hex code)
• description
• class_name
2. If you would like to upload a nested ontology as a JSON, the JSON format should follow the example of the file attached at the bottom of this article.
3. Click ‘upload’ from the Ontology Manager.
4. You can either drag your file in or upload it using the file selector. Once you’ve chosen your file, your ontology will be reflected in the UI.
5. If you encounter any file upload errors while uploading the ontology, please reach out to Appen Support (via chat or help@appen.com) and attach the file you are trying to upload.

Fig. 5: CSV with Ontology Data

To see how this ontology will look for contributors, preview the job:

Fig. 6: Preview of the bounding box tool

Moving Ontologies Between Jobs

In some cases, you may need to re-use the same ontology across multiple jobs. The fastest way to achieve this is:

1. Copying the job containing the ontology with no rows.
2. Make any edits to the ontology in the copy as needed.
3. Upload and run new data through the copy.

You may also download the ontology (it will download as a .json file) and upload it to any other job. Uploaded ontologies should always overwrite existing ontologies.