webknossos.administration.task
¶
Task
¶
Data class containing information about a WEBKNOSSOS task
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.
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)
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
¶
TaskStatus
¶
TaskType
¶
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': 'Any', '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': 'Any', '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)
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)
- Get Help
- Community Forums
- Email Support