The classic use-case is a user (human) using Cytomine and updating the database content with the web client. But we can run too software (algorithms, scripts,..) that modifies the platform data.
A software (Software) is a program with some parameters (SoftwareParameter). Before being executed, the Software must be link with a project (SoftwareProject).
Each time a software is running, a job (Job) is created. We can provide a value (JobParameter) for each software parameters. The job interacts with the platform using the REST API. This means that the job must authenticate himself. That's why we create a new user (UserJob) that inherits authorities from the real user that runs the software.
There are a number of different ways to run a software:
- Using the web interface and its form in the Job section.
Using an external script with a third party client (Python, Java,...).
- Using the web interface with pre-filled form in the UI
Using the last case, a JobTemplate needs to be defined in the project. Its simply a Job with preset/automatically set parameters.
Each time a user draw/click on an annotation, he may trigger the software execution.
Package main classes
Application that modifies Cytomine data
|SoftwareParameter||A parameter that can be set for the software||Software software|
|SoftwareProject||A link between a software and a project||Software software|
|Job||A software execution (a run)||Software software|
|UserJob||The user created for a job. This user inherits authorities from the user that executes the software.|
|JobParameter||The value for a software parameter for a specific Job||SoftwareParameter softwareParameter|
|JobData||A uploaded data created by a job. |
The file may be store into the database (JobDataBinaryValue) or in the filesystem (String dir + filename).
String dir + filename
|JobTemplate||A job template is a job with pre-filled parameters. It can be used to quickly run a job inside a ROI.||String name|
|JobTemplateAnnotation||A ROI link with a JobTemplate. This will trigger the execution of the Job on the ROI.||JobTemplate jobTemplate|
You need to create a Software. For each parameters, create a SoftwareParameter.
To be executed, the software needs to be link with at least one project (SoftwareProject).
When the software will be run, this will create a Job. Cytomine will execute the software. That's why the platform must have a service defining what to do to run the software.
This service extends AbstractJobService and its two abstract methods:
The execute method may compute the command to run the software with all its parameters.
For more details, you can get the documentation for user who wants to add new software.
Software Launch Form
A user friendly way to run a Job would be to use the Software Launch Form. By opening a project, you simply needs to go to “Jobs” panel, choose your software and click on “Run Job”.
The view simply browse each SoftwareParameter (not those set by the server) and add a new form input.
Parameter type may be String, Number, Date, Boolean, List, Domain or a ListDomain. SoftwareParameter may have default_value or may be mandatory.
The Domain and ListDomain is a particular type: a Cytomine resource (project, image, annotation...). In the backend, Domain is the same as Number because we only store and give the domain id to the software (not full JSON domain). The big difference is the web interface. Its not user-friendly to ask for an image id or a term id. For (List)Domain, we provide a select box with a search engine (see picture above).
To build this Domain view, a SoftwareParameter needs three properties:
- url: Cytomine url to get the resource list. If the form has a term input, it could be “/api/project/$currentProject$/term.json”. The $currentProject$ will be replaced by current project id by the webapp.
- uri_print_attribut: the domain attribut to print in the select. If you print a term selection, its better to print the “name” attribute than the id.
- uri_sort_attribut: the domain attribute used for the sort in the select. Generally same value as the uri_print_attribut value or the “created” attribute.
The Software result_name attribute is used to define the result page in the web client. Each new software may have a custom result view. For example, a software that suggests term for annotation may have a specific view with confusion matrice, the list of best and worst predictions,... A usefull view is “DownloadFiles”, which provide a way to download file uploaded by the job. The JobResultView view (located: web-app/application/views/processing/JobResultView.js) is responsible for the result page initialization.
Sometimes we just need to run software on a particular image ROI. In this case, running software from the job panel could be too heavy.
For example, we have a software “countAnnotation” counting the number of annotations with term X inside a ROI (annotation). The software simply get the annotation location and count all annotations having X inside this location. The parameters to provide in the job launch form will be:
annotation: ROI, the id of the annotation.
term: The id of the term X.
It could be difficult to retrieve the annotation id and heavy to set the good term for each execution. Furthermore, for each execution, the user needs to temporaly leave the "Image explore" view to go to the "Jobs" tab.
That's why we provide the JobTemplate concept. Its a shortcut to launch software on an annotation from the "Image explore" view. By simply opening the image and clicking on the ROI, you will be able to launch a software with pre-filled parameters.
The JobTemplate is a software Job with pre-filled parameters that you can easily run on an annotation.
As a reminder,
- a SoftwareParameter: a possible parameter for the software execution.
Example: parameter name “annotation” with type “Long” and mandatory
a JobParameter: a parameter value for a SoftwareParameter and a Software execution (Job).
Example: software parameter “annotation” will have “10” for the Job 123
If we want to create a shorcut for our “countAnnotation”, we need:
- The Software “countAnnotation” with the two SoftwareParameter: “term”, “annotation”. The software for a JobTemplate must have a parameter: “annotation”. Cytomine will automaticaly set the annotation id in the job parameter “annotation”
- The JobTemplate “countAnnotationX” with a JobParameter for the SoftwareParameter “term” set to term x id. The SoftwareParameter “annotation” will be automaticaly set.
The “Jobs Template” panel should be available on the web interface. You need to select an annotation on the image, to select a JobTemplate (here: countAnnotationX, in the picture above: computeAdenocarcinomesStat) on the panel and click on the “Launch” button. This will create a JobTemplateAnnotation instance and Cytomine will do following step:
- Init a Job with the prefilled parameters (term),
- Set the annotation id for the parameter “annotation”,
- Run the job like a normal “job”