With minimal effort, DarkHelp can be used from within shell scripts to analyze images and return predictions.

Note: Before trying this out, first run the DarkHelp CLI tool in the "normal" interactive mode as described in DarkHelp CLI Tool and Parameters. Once that works correctly, then test it with the -j flag to generate the JSON output.

When you run the DarkHelp CLI Tool with the -j or –json command line switch, three things will happen:

The interactive GUI window normally created using OpenCV is skipped, and DarkHelp will automatically process all the image and video files as quickly as it can without waiting for user input.
The results are stored in a JSON structure which is output to STDOUT once DarkHelp has finished running.
The JSON results will be saved to a file called output.json once DarkHelp has finished running.

Note: Darknet itself outputs a large amount of text to both STDOUT and STDERR while it runs. For this reason, it is normally easier to use the file output.json than to parse the output.

If you need to parse the Darknet and DarkHelp output to get the JSON, you'll need to do the following:

Combine STDOUT and STDERR into a single output stream.
Use a tool such as sed to find where the JSON output starts, and only keep the JSON portion of the output.

The solution you'll want to use when scripting with DarkHelp would be similar to this one:

# note how we combine STDOUT and STDERR and then pipe the results through sed

DarkHelp -j driving.cfg driving_best.weights driving.names *.jpg 2>&1 | sed -e '1,/JSON OUTPUT/ d'

The JSON output will be similar to this:

{
    "file": [
        {
            "count": 3,
            "duration": "164 milliseconds",
            "filename": "pets.jpg",
            "original_height": 375,
            "original_width": 500,
...etc...

The JSON structure contains an array with an entry for every image that was processed.

Let's look at a full example, followed by an explanation of each line:

DarkHelp -j driving.cfg driving_best.weights driving.names *.jpg 2>&1 | sed -e '1,/JSON OUTPUT/ d'
 
{
    "file": [
        {
            "count": 1,
            "duration": "178 milliseconds",
            "filename": "cujo.jpg",
            "original_height": 293,
            "original_width": 269,
            "prediction": [
                {
                   "all_probabilities": [
                        {
                            "class": 0,
                            "name": "dog",
                            "probability": 0.9390020966529846
                        }
                    ],
                    "best_class": 0,
                    "best_probability": 0.9390020966529846,
                    "name": "dog 94%",
                    "original_point": {
                        "x": 0.4825710654258728,
                        "y": 0.33033615350723267
                    },
                    "original_size": {
                        "height": 0.48039382696151733,
                        "width": 0.6355597376823425
                    },
                    "rect": {
                        "height": 141,
                        "width": 171,
                        "x": 44,
                        "y": 26
                    }
                }
            ],
            "resized_height": 293,
            "resized_width": 269,
            "type": "image/jpeg"
        }
    ],
    "network": {
        "cfg": "driving.cfg",
        "loading": "229 milliseconds",
        "names": "driving.names",
        "weights": "driving_best.weights"
    },
    "settings": {
        "force_greyscale": false,
        "hierarchy": 0.5,
        "include_percentage": true,
        "nms": 0.44999998807907104,
        "resize": "640x480",
        "threshold": 0.5
    }
}

Name	Example	Meaning
["file"][#]	...	Array of images and videos that were processed.
["file"][#]["count"]	"count" : 1	The number of predictions that were made for this image.
["file"][#]["duration"]	"duration": "178 milliseconds"	How long it took for Darknet to analyze this image.
["file"][#]["filename"]	"filename": "other_dog.jpg"	The filename which was analyzed.
["file"][#]["original_height"]	"original_height": 293	The height of the image prior to it being resized (in case `-b` is used).
["file"][#]["original_width"]	"original_width": 269	The width of the image prior to it being resized (in case `-b` is used).
["file"][#]["prediction"][#][...]	...	The same fields as what is documented in DarkHelp::PredictionResult. For example, see DarkHelp::PredictionResult::rect and DarkHelp::PredictionResult::all_probabilities.
["file"][#]["resized_height"]	"resized_height": 293	The height of the image after it has been resized (in case `-b` is used).
["file"][#]["resized_width"]	"resized_width": 269	The width of the image after it has been resized (in case `-b` is used).
["file"][#]["type"]	"image/jpeg"	The mimetype for the given file. Should be `image/`... or `video/`...
["network"]["cfg"]	"cfg": "driving.cfg"	The name of the neural network's .cfg file.
["network"]["loading"]	"loading": "229 milliseconds"	How long it took for the entire neural network to finish loading.
["network"]["names"]	"names": "driving.names"	The filename that contains a text string for each class in the neural network.
["network"]["weights"]	"weights": "driving_best.weights"	The filename that contains the neural network's binary data.
["settings"]["force_greyscale"]	"force_greyscale": false	Whether images are forced to greyscale prior to calling darknet.
["settings"]["hierarchy"]	"hierarchy": 0.5	Hierarchy threshold to use. See DarkHelp::Config::hierarchy_threshold.
["settings"]["include_percentage"]	"include_percentage": true	Whether the name given to each prediction includes the percentage. See DarkHelp::Config::names_include_percentage.
["settings"]["nms"]	"nms": 0.44999998807907104	Non-maximal suppression threshold. See DarkHelp::Config::non_maximal_suppression_threshold.
["settings"]["resize"]	"resize": "640x480"	Images are resized to this prior to calling DarkHelp::NN::predict(). See DarkHelp::resize_keeping_aspect_ratio().
["settings"]["threshold"]	"threshold": 0.5	Prediction threshold. See DarkHelp::Config::threshold.

Note: This example does not show every field. Run DarkHelp with -j to see the JSON output for details.

The DarkHelp CLI tool always returns zero. When using -j, you'll need to parse the JSON structure to find out if something didn't work correctly.

For example, this is part of what you'd see if an image does not exist:

{
    "file": [
        {
            "error": "Failed to read the image \"testing.jpg\".",
            "filename": "testing.jpg"
        }
    ]
}