#default_exp docs.api
API¶
A simple but flexible API to define annotation tasks¶
Ipyannotator provides a simple API (application programming interface) which is based on three steps describing general tasks in the data annotation process. These are denoted as the explore, create, and improve phase.
These three steps in conjuction with domain-specific annotation types, define the inputs and outputs of the annotation process, providing a very flexible and extendable API to set up annotation tasks.
API example¶
The following code examples illustrate the main actions around which the Ipyannotator API is built.
Please keep in mind that Ipyannotator aims to be flexible enought so that these generic aspects can be extented to much complexer and domain-specific tasks and interfaces.
To set up Ipyannotator in Jupyter Notebook the library has to be imported with three main components: the pair of input/output data, the settings structure, and the generic annotator module. The following example uses the InputImage/OutputImageLabel associated with the image classification task. It imports the settings pointing to a folder called ‘data’ and configures the annotator module with the entries. Once the annotator module is configured it can be used to call the explore, create and improve steps.
from pathlib import Path
from ipyannotator.base import Settings
from ipyannotator.annotator import Annotator
from ipyannotator.mltypes import InputImage, OutputImageLabel
input = InputImage(image_dir='images', image_width=200, image_height=200)
output = OutputImageLabel(label_dir='labels', label_width=30, label_height=30)
settings = Settings(project_path=Path('data'))
annotator = Annotator(input, output, settings)
For a full investigation of image classification task check our tutorial.
API Reference¶
Detailed information about Ipyannotator API. To see usage please check Ipyannotator tutorials.
To use Ipyannotator API it’s necessary to import the Annotator class by using from ipyannotator.annotator import Annotator.
The pairs of input/output available are listed on the Input/Output Types section.
When working with the Annotator class the input type is always required, but the output type has a NoOutput default option that returns an annotator to explore the input images. NoOutput usage can be found on the Bounding Box Annotator Tutorial.
Actions¶
Once the API is configured the following actions are available.
Annotator.explore[source]
Annotator.explore(k=-1)
Visualize the existing annotated dataset.
To explore a part of dataset set k - number of classes to display;
By default explore all (k == -1)
Annotator.create[source]
Annotator.create()
Create new annotated dataset from scratch.
If the result path already exists a warning will be displayed to avoid overriding datasets
Annotator.improve[source]
Annotator.improve()
Improve existing annotated dataset.
Every annotator has a particular way of improving its datasets. Some annotators allows label deleting other changing its properties.
Settings¶
The final piece of the configuration to access the Ipyannotator API is the Settings class that can be imported using from ipyannotator.base import Settings. Ipyannotator Settings class allow users to customize the folder structure to get the images, read annotations and store results, but also provides a default folder structure:
user_project
│ annotation.json
│
└───images
│ │ 00001.png
│ │ 00002.png
│ │ ...
│
└───results
│ annotations.json
class Settings[source]
Settings(project_path:Path=Path('user_project'),project_file:Optional[Path]=None,image_dir:str='images',label_dir:Optional[str]=None,result_dir:Optional[str]=None,im_width:int=50,im_height:int=50,label_width:int=50,label_height:int=50,n_cols:int=3,n_rows:Optional[int]=None) ::tuple
Holds Ipyannotator API settings
project_path: parent directory of the project_file and image_dir
project_file: json file with annotations
image_dir: directory that stores all images to be explored
label_dir: directory that hold the image labels (if any)
result_dir: directory to store the annotation results
im_width: size of the images from image_dir
im_height: height of the images from image_dir
label_width: width of the labels from labels_dir
label_height: height of the labels from labels_dir
n_cols: number of columns displayed at the right menu
n_rows: number of rows displayed at the right menu