Skip to content

webknossos.administration.task

Task

Data class containing information about a WEBKNOSSOS task

bounding_box class-attribute instance-attribute 

bounding_box: BoundingBox | None = None

dataset_id instance-attribute 

dataset_id: str

edit_position instance-attribute 

edit_position: Vec3Int

edit_rotation instance-attribute 

edit_rotation: tuple[float, float, float]

experience instance-attribute 

experience: TaskExperience

project_id instance-attribute 

project_id: str

script_id class-attribute instance-attribute 

script_id: str | None = None

status instance-attribute 

status: TaskStatus

task_id instance-attribute 

task_id: str

task_type instance-attribute 

task_type: TaskType

create classmethod 

create(task_type_id: str | TaskType, project_name: str | Project, needed_experience_domain: str, needed_experience_value: int, starting_position: Vec3IntLike, dataset_id: str | RemoteDataset, dataset_name: str | RemoteDataset | None = None, starting_rotation: Vec3IntLike = Vec3Int(0, 0, 0), instances: int = 1, script_id: str | None = None, bounding_box: BoundingBox | None = None) -> list[Task]

Submits one or more tasks to WEBKNOSSOS based on the specified dataset, starting position, and rotation, and returns the created Task objects.

This method allows you to create annotation or analysis tasks for a given dataset, specifying the required experience, starting position, and other parameters. The dataset can be referenced either by its ID or by passing a RemoteDataset instance. Optionally, a bounding box can be provided to restrict the task area.

Parameters:

  • task_type_id (str | TaskType) –

    The ID of the task type to create, or a TaskType instance.

  • project_name (str | Project) –

    The name of the project to associate the task with, or a Project instance.

  • needed_experience_domain (str) –

    The experience domain required for the task (e.g., "segmentation").

  • needed_experience_value (int) –

    The minimum experience value required for the task.

  • starting_position (Vec3IntLike) –

    The starting position for the task as a Vec3IntLike (x, y, z).

  • dataset_id (str | RemoteDataset) –

    The dataset ID as a string or a RemoteDataset instance.

  • dataset_name (str | RemoteDataset | None, default: None ) –

    (Deprecated) The dataset name as a string or RemoteDataset instance. Prefer using dataset_id.

  • starting_rotation (Vec3IntLike, default: Vec3Int(0, 0, 0) ) –

    The starting rotation for the task as a Vec3IntLike (default: Vec3Int(0, 0, 0)).

  • instances (int, default: 1 ) –

    The number of task instances to create (default: 1).

  • script_id (str | None, default: None ) –

    Optional script ID to associate with the task.

  • bounding_box (BoundingBox | None, default: None ) –

    Optional BoundingBox to restrict the task area.

Returns:

  • list[Task] –

    list[Task]: A list of created Task objects.

Raises:

  • AssertionError –

    If neither dataset_id nor dataset_name is provided.

  • DeprecationWarning –

    If dataset_name is used instead of dataset_id.

Examples:

Create a new segmentation task for a dataset: 

tasks = Task.create(
    task_type_id="segmentation",
    project_name="MyProject",
    needed_experience_domain="segmentation",
    needed_experience_value=10,
    starting_position=(100, 200, 300),
    dataset_id="abc123",
    instances=5
for task in tasks:
    print(task.id)

Create a task with a bounding box and a RemoteDataset: 

bbox = BoundingBox((0, 0, 0), (100, 100, 100))
tasks = Task.create(
    task_type_id=task_type,
    project_name=project,
    needed_experience_domain="proofreading",
    needed_experience_value=5,
    starting_position=(0, 0, 0),
    dataset_id=remote_ds,
    bounding_box=bbox

create_from_annotations classmethod 

create_from_annotations(task_type_id: str | TaskType, project_name: str | Project, base_annotations: list[Annotation], needed_experience_domain: str, needed_experience_value: int, instances: int = 1, script_id: str | None = None, bounding_box: BoundingBox | None = None) -> list[Task]

Create new tasks in WEBKNOSSOS from existing annotations.

This class method submits one or more tasks to WEBKNOSSOS, using a list of base annotations as input. It returns the created Task objects. The method allows specifying the task type, project, required experience, number of task instances, and optionally a script and bounding box.

Parameters:

  • task_type_id (str | TaskType) –

    The ID or TaskType object specifying the type of task to create.

  • project_name (str | Project) –

    The name or Project object specifying the project to which the tasks belong.

  • base_annotations (list[Annotation]) –

    List of Annotation objects to use as the basis for the new tasks. Must not be empty.

  • needed_experience_domain (str) –

    The experience domain required for the task (e.g., "proofreading").

  • needed_experience_value (int) –

    The minimum experience value required for the task.

  • instances (int, default: 1 ) –

    Number of task instances to create (default: 1).

  • script_id (str | None, default: None ) –

    Optional script ID to associate with the task.

  • bounding_box (BoundingBox | None, default: None ) –

    Optional BoundingBox object specifying the spatial extent of the task.

Returns:

  • list[Task] –

    list[Task]: List of created Task objects.

Raises:

  • AssertionError –

    If no base annotations are provided.

Examples:

tasks = Task.create_from_annotations(
    task_type_id="proofreading",
    project_name="MyProject",
    base_annotations=[annotation1, annotation2],
    needed_experience_domain="proofreading",
    needed_experience_value=3,
    instances=2,
    script_id="script_123",
    bounding_box=BoundingBox((0, 0, 0), (100, 100, 100))
for task in tasks:
    print(task.task_id)
Note

Each annotation in base_annotations will be uploaded as a zipped file and associated with the created tasks. The method requires authentication and will raise an error if the user is not authenticated.

delete 

delete() -> None

Deletes this task. WARNING: This is irreversible!

get_annotation_infos 

get_annotation_infos() -> list[AnnotationInfo]

Returns AnnotationInfo objects describing all task instances that have been started by annotators for this task

get_by_id classmethod 

get_by_id(task_id: str) -> Task

Retrieve a Task by its unique identifier.

Fetches the task with the specified ID from the backend, provided the current user is authorized to access it. This method requires authentication.

Parameters:

  • task_id (str) –

    The unique identifier of the task to retrieve.

Returns:

  • Task ( Task ) –

    The Task instance corresponding to the given ID.

Raises:

  • UnexpectedStatusError –

    If the task does not exist or the user is not authorized.

Examples:

Get a task by ID: 

task = Task.get_by_id("task_12345")
print(task.name)

get_list classmethod 

get_list() -> list[Task]

Retrieve all tasks visible to the current user.

Returns a list of all tasks that the authenticated user is authorized to see. This method queries the backend for all available tasks and returns them as a list of Task objects.

Returns:

  • list[Task] –

    list[Task]: List of Task objects the user is authorized to access.

Examples:

Get all tasks for the current user: 

tasks = Task.get_list()
for task in tasks:
    print(task.name)

get_project 

get_project() -> Project

Returns the project this task belongs to

update 

update(remaining_instances: int) -> Task

Update the task with new parameters.

Updates the current task instance on the server with the specified number of remaining instances and other task parameters.

Parameters:

  • remaining_instances (int) –

    The number of remaining instances for this task.

Returns:

  • Task ( Task ) –

    The updated Task object as returned by the server.

Examples:

task = Task.get_by_id("task_id")
updated_task = task.update(remaining_instances=5)
print(updated_task.remaining_instances)

TaskExperience

Data class containing information about the experience needed to work on a task

domain instance-attribute 

domain: str

value instance-attribute 

value: int

TaskStatus

active_instance_count instance-attribute 

active_instance_count: int

finished_instance_count instance-attribute 

finished_instance_count: int

open_instance_count property 

open_instance_count: int

pending_instance_count instance-attribute 

pending_instance_count: int

TaskType

description instance-attribute 

description: str

name instance-attribute 

name: str

settings class-attribute instance-attribute 

settings: dict[str, Any] | None = None

task_type_id instance-attribute 

task_type_id: str

team_id instance-attribute 

team_id: str

team_name instance-attribute 

team_name: str

tracingType class-attribute instance-attribute 

tracingType: str | None = None

create classmethod 

create(name: str, description: str, team: str | Team, tracing_type: Literal['skeleton', 'volume', 'hybrid'] = 'skeleton', settings: dict[str, Any] = {'mergerMode': False, 'magRestrictions': {'min': 1, 'max': 1}, 'somaClickingAllowed': True, 'volumeInterpolationAllowed': False, 'allowedModes': [], 'preferredMode': None, 'branchPointsAllowed': True, 'clippingDistance': 80, 'moveValue': 500, 'displayScalebars': False, 'newNodeNewTree': False, 'centerNewNode': True, 'tdViewDisplayPlanes': 'WIREFRAME', 'tdViewDisplayDatasetBorders': True, 'tdViewDisplayLayerBorders': False, 'dynamicSpaceDirection': True, 'highlightCommentedNodes': False, 'overrideNodeRadius': True, 'particleSize': 5, 'keyboardDelay': 0, 'displayCrosshair': True, 'useLegacyBindings': False, 'fourBit': False, 'interpolation': True, 'segmentationOpacity': 0, 'segmentationPatternOpacity': 40, 'zoom': 0.8, 'renderMissingDataBlack': False, 'loadingStrategy': 'BEST_QUALITY_FIRST', 'clippingDistanceArbitrary': 60, 'moveValue3d': 600, 'mouseRotateValue': 0.001, 'rotateValue': 0.01, 'sphericalCapRadius': 500, 'brushSize': 50}) -> TaskType

Creates a new task type and returns it.

This class method allows you to create a new task type in the system, specifying its name, description, associated team, and tracing type. The created task type is returned as an instance of TaskType.

Parameters:

  • name (str) –

    The name of the new task type. This will be used as the summary for the task type.

  • description (str) –

    A detailed description of the task type.

  • team (str | Team) –

    The team to which this task type will belong. Can be either a team name (str) or a Team object.

  • tracing_type (Literal['skeleton', 'volume', 'hybrid'], default: 'skeleton' ) –

    The tracing type for the task. Must be one of "skeleton", "volume", or "hybrid".

  • settings (dict[str, Any], default: {'mergerMode': False, 'magRestrictions': {'min': 1, 'max': 1}, 'somaClickingAllowed': True, 'volumeInterpolationAllowed': False, 'allowedModes': [], 'preferredMode': None, 'branchPointsAllowed': True, 'clippingDistance': 80, 'moveValue': 500, 'displayScalebars': False, 'newNodeNewTree': False, 'centerNewNode': True, 'tdViewDisplayPlanes': 'WIREFRAME', 'tdViewDisplayDatasetBorders': True, 'tdViewDisplayLayerBorders': False, 'dynamicSpaceDirection': True, 'highlightCommentedNodes': False, 'overrideNodeRadius': True, 'particleSize': 5, 'keyboardDelay': 0, 'displayCrosshair': True, 'useLegacyBindings': False, 'fourBit': False, 'interpolation': True, 'segmentationOpacity': 0, 'segmentationPatternOpacity': 40, 'zoom': 0.8, 'renderMissingDataBlack': False, 'loadingStrategy': 'BEST_QUALITY_FIRST', 'clippingDistanceArbitrary': 60, 'moveValue3d': 600, 'mouseRotateValue': 0.001, 'rotateValue': 0.01, 'sphericalCapRadius': 500, 'brushSize': 50} ) –

    Additional settings for the task type. Information about the task type's configuration options can be found here: https://docs.webknossos.org/webknossos/tasks_projects/tasks.html

Returns:

  • TaskType ( TaskType ) –

    The newly created task type object.

Raises:

  • ValueError –

    If the provided team does not exist or cannot be resolved.

  • ApiException –

    If the API call to create the task type fails.

Examples:

Create a new skeleton tracing task type for a team: 

task_type = TaskType.create(
    name="Neuron Skeleton Tracing",
    description="Trace neuron skeletons for connectomics project.",
    team="NeuroLab",
    tracing_type="skeleton"
print(task_type.id)

delete 

delete() -> None

Deletes the task type.

get_by_id classmethod 

get_by_id(task_type_id: str) -> TaskType

Retrieve a TaskType instance by its unique ID.

This class method fetches the task type corresponding to the given task_type_id from the backend, provided the current user has permission to view it.

Parameters:

  • task_type_id (str) –

    The unique identifier of the task type to retrieve.

Returns:

  • TaskType ( TaskType ) –

    The TaskType instance corresponding to the specified ID.

Raises:

  • UnexpectedStatusError –

    If the task type cannot be found or the user does not have access.

Examples:

Retrieve a task type by ID: 

task_type = TaskType.get_by_id("1234567890abcdef")
print(task_type.name)

get_by_name classmethod 

get_by_name(name: str) -> TaskType

Get a TaskType by its name.

Searches for a task type with the specified name among all available task types visible to the current user. If found, returns the corresponding TaskType object.

Parameters:

  • name (str) –

    The name of the task type to retrieve.

Returns:

  • TaskType ( TaskType ) –

    The task type object with the specified name.

Raises:

  • ValueError –

    If no task type with the given name is found.

Examples:

task_type = TaskType.get_by_name("Segmentation")
print(task_type.id)

get_list classmethod 

get_list() -> list[TaskType]

Retrieve all accessible task types for the current user.

This class method queries the backend for all task types that the authenticated user is authorized to access. It returns a list of TaskType instances corresponding to the available tasks.

Returns:

  • list[TaskType] –

    list[TaskType]: List of all task types accessible to the current user.

Examples:

Get all available task types: 

task_types = TaskType.get_list()
for task_type in task_types:
    print(task_type.name)