Beeldherkennings API

switch to English

Alle modellen zijn ook beschikbaar via een publiekelijk beschikbare API. De API heeft de volgende endpoints:

https://museum.identify.biodiversityanalysis.nl/apiroot
https://museum.identify.biodiversityanalysis.nl/api/models beschikbare modellen
https://museum.identify.biodiversityanalysis.nl/api/selector/identify identificatie middels model
https://museum.identify.biodiversityanalysis.nl/api/selector/classesklassen in model

https://museum.identify.biodiversityanalysis.nl/api/selector/report &

https://museum.identify. ... /selector/report/confusion_matrix

modelrapportage

Let er op bij aanroep van endpoints géén afsluitende slash toe te voegen.De aanroep van bijvoorbeeld  https://museum.identify.biodiversityanalysis.nl/api/  geeft een foutmelding (‘The requested URL was not found on the server’).

Root endpoint

Basisinformatie over de API

URL: https://museum.identify.biodiversityanalysis.nl/api

Parameters: geen; Methods: GET, POST

Endpoint ‘models’

Geeft een overzicht van de beschikbare modellen en hoe ze te benaderen.

URL: https://museum.identify.biodiversityanalysis.nl/api/models 

Parameters: geen; Methods:     GET, POST

Endpoint ‘identifify’

Endpoint om een afbeelding mee te identificeren.

URL:          https://museum.identify.biodiversityanalysis.nl/api/selector/identify

waarbij selector  de waarde van ‘selector’ van een van de modellen uit het model-endpoint is.

Parameters: image= (als multipart/form-data); Methods: POST

Voorbeeldaanroep met cURL:

curl -XPOST -F "image=@bruce.jpg" https://museum.identify.biodiversityanalysis.nl/api/haaien_roggen_eieren/identify

De response bevat een veld ‘predictions’, dat op zijn beurt een JSON-encoded lijst van voorspellingen van wat er op de geüploade afbeelding staat. Iedere voorspelling bestaat uit een klasse en de waarschijnlijkheid dat het die klasse betreft (als fractie van 1). De API geeft altijd de voorspellingen voor alle klassen in het model terug, aflopend geordend op waarschijnlijkheid.

Endpoint ‘classes’

Geeft een alfabetisch overzicht van alle klassen die een model bevat (‘herkend’).

URL: https://museum.identify.biodiversityanalysis.nl/api/selector/classes

waarbij selector  de waarde van ‘selector’ van een van de modellen uit het model-endpoint is.

Parameters: geen; Methods: GET, POST

Endpoints ‘report’

Levert een rapport met een reeks kerngetallen m.b.t. de performance van een model.

URLs:

waarbij selector  de waarde van ‘selector’ van een van de modellen uit het model-endpoint is.

Parameters: geen; Methods: GET, POST

Report

https://museum.identify.biodiversityanalysis.nl/api/selector/report

Response bevat een aantal karakteristieken van het betreffende model:

class_listKlassen in het model (naam; indexnummer)
classification_report.modelAccuracy van het model. Precision, recall en F1-score voor het hele model (gemiddelde en gewogen gemiddelde). Support (aantal afbeeldingen waarmee het model getraind werd).
classification_report.classesPrecision, recall en F1-score en support voor de iedere  klasse. De indexnummers verwijzen terug naar de indexnummers uit de class_list.
top_kAantal malen dat de correcte identificatie in de top 1, top 3 of top 5 van identificaties zat, voor het hele model. De top 1 is altijd gelijk aan het gewogen gemiddelde van de recall van het hele model.
top_k_per_classIdem per klasse, maar dan uitgedrukt als aantal afbeeldingen. Het aantal in de top 1, gedeeld door de support voor die klasse, is altijd gelijk aan de recall van die klasse.

Confusion matrix

https://museum.identify.biodiversityanalysis.nl/api/selector/report/confusion_matrix

Geeft de confusion matrix van de identificaties gedaan op de training set. De output bevat ook een uitleg hoe de confusion matrix te interpreteren.

 

Autorisatie

Een aantal modellen is om inhoudelijke redenen niet publiekelijk toegankelijk. Deze zijn herkenbaar aan de tag ‘restricted’ in de output van het models-endpoint. Neem voor gebruik van deze modellen contact op met Naturalis. Heeft u toestemming om de bijbehorende endpoints te gebruiken, dan heeft u als het goed is een gebruikersnaam en wachtwoord gekregen voor toegang. De autorisatie is geïmplementeerd als Basic Authorization. Voorbeeld implementatie met behulp van cURL, als u de gebruikersnaam ‘mijn_naam’ en wachtwoord ‘geheim’ hebt gekregen:

curl -u "mijn_naam:geheim" https://museum.identify.biodiversityanalysis.nl/api/vogeleieren/classes

of

curl https://mijn_naam:geheim@museum.identify.biodiversityanalysis.nl/api/vogeleieren/classes