das element CLI - command line tool

This is the command line tool from das-element for classification of image, sequence and movie files.

You can deploy it on your render farm to use it in a post-render process for labeling of elements.

How To

Simple usage

classifier {file}

classifier /path/to/file.#.exr

# result:
{"/path/to/file.#.exr": [{"label": "fire", "description": "rapid oxidation of a material", "value": "Q3196"}]}

Valid file paths are …

single file (single image or movie file):
- /path/to/file.exr
- /path/to/file.mov
sequence of files
- /path/to/sequence.#.exr
- /path/to/sequence.%04d.exr
directory
- the software will crawl the folder structure to find any media files or sequences

Multiple files

You can pass multiple file paths to the software.
classifier {file1} {file2} {file3}

classifier /path/to/files.#.exr /path/to/another/file.mov

# result:
{"/path/to/files.#.exr": [{"label": "fire", "description": "rapid oxidation of a material", "value": "Q3196"}],
"/path/to/another/file.mov": [{"label": "torch", "description": "stick with a flaming end used as a source of light", "value": "Q327954"}]}

Multiple results

Get the top X predicted categories by using the flag: --top {number}

classifier -top 3 /path/to/file.mov

# result:
{"/path/to/file.mov": [
      {"label": "torch", "description": "stick with a flaming end used as a source of light", "value": "Q327954"},
      {"label": "fire", "description": "rapid oxidation of a material", "value": "Q3196"},
      {"label": "flame", "description": "visible, gaseous part of a fire", "value": "Q235544"}
]}

Python Example

Here is an example code snippet that you could use in your python code.

# print the top 3 label predictions for a given file path

import json
import subprocess

path = '/path/to/file.mov'
command = ['./classifier', '--top', '3', path]
process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
output, error = process.communicate()

if process.returncode != 0:
    print('Something went wrong: {} - Error: {}'.format(path, error))
else:
    result = json.loads(output)
    for path, predictions in result.items():
        wikidata_ids = [item['value'] for item in  predictions]  # list of IDs from wikidata
        readable_labels = [item['label'] for item in predictions]  # list of human readable labels
        print('For path: "{}" predicted the labels: {}'.format(path, ', '.join(readable_labels)))

# result:
# For path: "/path/to/file.mov" predicted the labels: torch, flame, fire

Software info

Get information about the current software version and the categories that can be classified.

classifier --info

key	description
id	the identifier for the class from Wikidata
human-readable	meaningful readable label
synonym	a list of different words for this class

Result Format

For each file path you get an list of predictions for labels.

The result is in JSON format. The default string format is Unicode.

{'/path/to/file.mov': [{
                          'value': 'Q327954',
                          'label': 'torch',
                          'description': 'stick with a flaming end used as a source of light'
                        }]}

key	description
`value`	identifier value - see here for more details
`label`	human readable text of this category
`description`	description text for this category

Flags

These are the flags that can be set

flag	description
`--info`	Shows information the software. List all categories that this version of the model can classify.
`--top {number}`	Get the top X predictions of labels. The first two predictions are probably the most significant ones.
`--debug`	debugging mode

Troubleshooting

issue	solution
MacOS shows unidentified developer for 'ffprobe'	For MacOS you should add the ffprobe to your trusted applications if you want to use the software. We use the ffmpeg and ffprobe build from MacOS from the following source: https://evermeet.cx/ffmpeg/