Merge pull request #170 from SenteraLLC/refactor/config

Refactor/config

Author: TrevorBurgoyne

api_spec.md

@@ -34,19 +34,42 @@ The constructor is used to specify the configuration for an "annotation session"
 
 ```javascript
 class ULabel({
+    // Required arguments
     container_id: string,
     image_data: string | string[],
     username: string,
     submit_buttons: function | ULabelSubmitButton[],
     subtasks: object,
+    // Optional arguments
     task_meta: object,
     annotation_meta: object,
     px_per_px: number,
     initial_crop: InitialCrop,
     initial_line_size: number,
     instructions_url: string,
-    config_data: object,
-    toolbox_order: AllowedToolboxItem[]
+    toolbox_order: AllowedToolboxItem[],
+    default_keybinds = {
+        "annotation_size_small": string,
+        "annotation_size_large": string,
+        "annotation_size_plus": string,
+        "annotation_size_minus": string,
+        "annotation_vanish": string
+    },
+    distance_filter_toolbox_item: FilterDistanceConfig,
+    change_zoom_keybind: string,
+    create_point_annotation_keybind: string,
+    default_annotation_size: number,
+    delete_annotation_keybind: string,
+    keypoint_slider_default_value: number,
+    filter_annotations_on_load: boolean,
+    switch_subtask_keybind: string,
+    toggle_annotation_mode_keybind: string,
+    create_bbox_on_initial_crop: string,
+    toggle_brush_mode_keybind: string,
+    toggle_erase_mode_keybind: string,
+    increase_brush_size_keybind: string,
+    decrease_brush_size_keybind: string,
+    n_annos_per_canvas: number
 })
 ```
 
@@ -284,57 +307,11 @@ The line width with which new annotations are drawn initially. Units are pixels
 
 URL to a page that gives annotation instructions.
 
-### `config_data`
-
-*object* -- An object to configure much of ULabel's behaviors.
+### `toolbox_order`
+An array of numbers that defines the vertical order of items in the toolbox. At least one item must be included in the array. Any excluded items will not be displayed in the toolbox.
 
+The supported toolbox items are:
 ```javascript
-{
-    default_toolbox_item_order: AllowedToolboxItem[],
-
-    default_keybinds = {
-        "annotation_size_small": string,
-        "annotation_size_large": string,
-        "annotation_size_plus": string,
-        "annotation_size_minus": string,
-        "annotation_vanish": string
-    },
-
-    distance_filter_toolbox_item: FilterDistanceConfig,
-
-    change_zoom_keybind: string,
-
-    create_point_annotation_keybind: string,
-
-    default_annotation_size: number,
-    
-    delete_annotation_keybind: string,
-    
-    keypoint_slider_default_value: number,
-
-    filter_annotations_on_load: boolean,
-    
-    switch_subtask_keybind: string,
-    
-    toggle_annotation_mode_keybind: string,
-
-    create_bbox_on_initial_crop: string,
-
-    annotation_gradient_default: boolean
-
-    toggle_brush_mode_keybind: string
-
-    toggle_erase_mode_keybind: string
-
-    increase_brush_size_keybind: string
-
-    decrease_brush_size_keybind: string
-
-    n_annos_per_canvas: number // Default is 100. Setting higher for jobs with a large number annotations may help performance.
-}
-```
-With the following custom definitions.
-```Javascript
 enum AllowedToolboxItem {
     ModeSelect,       // 0
     ZoomPan,          // 1
@@ -347,7 +324,27 @@ enum AllowedToolboxItem {
     FilterDistance,   // 8
     Brush             // 9
 }
+```
+You can access the AllowedToolboxItem enum by calling the static method:
+```javascript
+const AllowedToolboxItem = ULabel.get_allowed_toolbox_item_enum();
+```
 
+### `default_keybinds`
+Keybinds can be set to control the annotation session. The default values are:
+```javascript
+{
+    "annotation_size_small": "s",
+    "annotation_size_large": "l",
+    "annotation_size_plus": "=",
+    "annotation_size_minus": "-",
+    "annotation_vanish": "v"
+}
+```
+
+### `distance_filter_toolbox_item`
+Configuration object for the `FilterDistance` toolbox item with the following custom definitions:
+```javascript
 type DistanceFromPolyline = {
     distance: number // distance in pixels
 }
@@ -374,7 +371,49 @@ type FilterDistanceConfig = {
     // since it will not update the filter/overlay until polyline moves/edits are complete.
 }
 ```
-Where all `config_data` properties are optional.
+
+### `change_zoom_keybind`
+Keybind to change the zoom level. Must be a letter, and the lowercase version of the letter will set the zoom level to the `initial_crop`, while the capitalized version will show the full image. Default is `r`.
+
+### `create_point_annotation_keybind`
+Keybind to create a point annotation at the mouse location. Default is `c`. Requires the active subtask to have a `point` mode.
+
+### `default_annotation_size`
+Default size of annotations in pixels. Default is `6`.
+
+### `delete_annotation_keybind`
+Keybind to delete the annotation that the mouse is hovering over. Default is `d`.
+
+### `keypoint_slider_default_value`
+Default value for the keypoint slider. Must be a number between 0 and 1. Default is `0`.
+
+### `filter_annotations_on_load`
+If true, the annotations will be filtered on load based on the `keypoint_slider_default_value`. Default is `true`.
+
+### `switch_subtask_keybind`
+Keybind to switch between subtasks. Default is `z`.
+
+### `toggle_annotation_mode_keybind`
+Keybind to toggle between annotation and selection modes. Default is `u`.
+
+### `create_bbox_on_initial_crop`
+Keybind to create a bounding box annotation around the `initial_crop`. Default is `f`. Requires the active subtask to have a `bbox` mode.
+
+### `toggle_brush_mode_keybind`
+Keybind to toggle brush mode for polygon annotations. Default is `g`. Requires the active subtask to have a `polygon` mode.
+
+### `toggle_erase_mode_keybind`
+Keybind to toggle erase mode for polygon annotations. Default is `e`. Requires the active subtask to have a `polygon` mode.
+
+### `increase_brush_size_keybind`
+Keybind to increase the brush size. Default is `]`. Requires the active subtask to have a `polygon` mode.
+
+### `decrease_brush_size_keybind`
+Keybind to decrease the brush size. Default is `[`. Requires the active subtask to have a `polygon` mode.
+
+### `n_annos_per_canvas`
+The number of annotations to render on a single canvas. Default is `100`. Increasing this number may improve performance for jobs with a large number of annotations.
+
 
 ## Display Utility Functions
 

changelog.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented here.
 ## [unreleased]
 
 Nothing yet.
+## [0.13.0] - Sept 26th, 2024
+- Fix bug where the `filter_annotations_on_load = true` option would not work as expected. 
+  - The `keypoint_slider_default_value` option was not being properly multiplied by 100 internally.
+- Move several config argument defaults into the configuration class instead of in the ULabel constructor.
+- Add `get_allowed_toolbox_item_enum()` static method to ULabel.
+#### Breaking Changes
+- Changed default for `filter_annotations_on_load` from `false` to `true`.
+- Deprecated the `default_toolbox_item_order` argument in the ULabel constructor. Use `toolbox_order` instead.
+- Deprecated `config_data` argument in the ULabel constructor. Instead, pass all configuration options as keyword arguments directly to the ULabel constructor.
+  - For now, the `config_data` argument will still work, but may be removed in a future release.
 
 ## [0.12.5] - Sept 26th, 2024
 - Fix release workflow using actions on `node` 16, which is now deprecated.

demo/multi-class.html

@@ -80,6 +80,7 @@
                 }
             };
 
+            const AllowedToolboxItem = ULabel.get_allowed_toolbox_item_enum();
             // Initial ULabel configuration
             let ulabel = new ULabel({
                 "container_id": "container",
@@ -106,26 +107,6 @@
                         "color": "green",
                         "row_number": 1,
                     },
-                    // {
-                    //     "name": "Submit",
-                    //     "hook": on_submit,
-                    //     "size_factor": 0.9,
-                    //     "row_number": 2,
-                    // },
-                    // {
-                    //     "name": "Reject",
-                    //     "hook": () => { console.log("Reject"); },
-                    //     "size_factor": 0.9,
-                    //     "color": "red",
-                    //     "row_number": 2,
-                    // },
-                    // {
-                    //     "name": "Approve",
-                    //     "hook": () => { console.log("Approve"); },
-                    //     "size_factor": 0.9,
-                    //     "color": "green",
-                    //     "row_number": 2,
-                    // },
                     {
                         "name": "Skip",
                         "hook": () => { console.log("Skip"); },
@@ -136,22 +117,19 @@
                 ],
                 "subtasks": subtasks,
                 "initial_line_size": 2,
-                "config_data": {
-                    "default_toolbox_item_order": [
-                        7, // SubmitButtons
-                        0, // ModeSelect
-                        // 1, // ZoomPan
-                        2, // AnnotationResize
-                        3, // AnnotationID
-                        4, // Recolor Active
-                        5, // ClassCounter
-                        6, // KeypointSlider
-                        8, // FilterDistance
-                        // 9, // Brush
-                    ],
-                    "toggle_brush_mode_keybind": "f",
-                    "create_bbox_on_initial_crop": "|",
-                }
+                "toolbox_order": [
+                    AllowedToolboxItem.SubmitButtons,
+                    AllowedToolboxItem.ModeSelect,
+                    AllowedToolboxItem.ZoomPan,
+                    AllowedToolboxItem.AnnotationID, 
+                    AllowedToolboxItem.ClassCounter,
+                    AllowedToolboxItem.AnnotationResize, 
+                    AllowedToolboxItem.KeypointSlider,  
+                    AllowedToolboxItem.FilterDistance,
+                    AllowedToolboxItem.RecolorActive,
+                ],
+                "toggle_brush_mode_keybind": "f",
+                "create_bbox_on_initial_crop": "|",
             });
             // Wait for ULabel instance to finish initialization
             ulabel.init(function () {

demo/row-filtering-example.html

@@ -13,9 +13,6 @@
 
     <!-- ULabel Usage -->
     <script>
-        /* global $ */
-        /* global ULabel */
-
         $(window).on("load", function () {
 
             function on_submit(annotations) {
@@ -718,7 +715,7 @@
                 }
             ]
 
-            let subtasks = {
+            const subtasks = {
                 "plants": {
                     "display_name": "Plants",
                     "classes": [
@@ -754,21 +751,36 @@
                 }
             };
 
+            const AllowedToolboxItem = ULabel.get_allowed_toolbox_item_enum();
             // Initial ULabel configuration
             let ulabel = new ULabel({
                 "container_id": "container",
                 "image_data": "https://ulabel.s3.us-east-2.amazonaws.com/cs-demo-0.png",
                 "username": "DemoUser",
                 "submit_buttons": on_submit,
                 "subtasks": subtasks,
-                "toolbox_order": [0, 1, 3, 6, 8, 2, 7, 4, 5],
-                "config_data": {
-                    "distance_filter_toolbox_item": {
-                        "show_overlay": true,
-                        // "disable_multi_class_mode": true,
-                        // "filter_during_polyline_move": false,
-                    }
-                }
+                "toolbox_order": [
+                    AllowedToolboxItem.ModeSelect,
+                    AllowedToolboxItem.ZoomPan,
+                    AllowedToolboxItem.AnnotationID, 
+                    AllowedToolboxItem.ClassCounter, 
+                    AllowedToolboxItem.KeypointSlider,  
+                    AllowedToolboxItem.FilterDistance,
+                    AllowedToolboxItem.AnnotationResize,
+                    AllowedToolboxItem.SubmitButtons,
+                    AllowedToolboxItem.RecolorActive,
+                ],
+                "distance_filter_toolbox_item": {
+                    "default_values": {
+                        "closest_row": {
+                            "distance": 200, // px
+                        }
+                    },
+                    "show_overlay": true,
+                    // "disable_multi_class_mode": true,
+                    // "filter_during_polyline_move": false,
+                },
+                "keypoint_slider_default_value": 0.2,
             });
             // Wait for ULabel instance to finish initialization
             ulabel.init(function () {

dist/ulabel.js

@@ -1,5 +1,5 @@
 import { ULabelAnnotation } from "./src/annotation";
-import { AllowedToolboxItem } from "./src/configuration";
+import { AllowedToolboxItem, Configuration } from "./src/configuration";
 import { FilterDistanceOverlay } from "./src/overlays";
 import { ULabelSubtask } from "./src/subtask";
 import { Toolbox } from "./src/toolbox";
@@ -150,12 +150,22 @@ export type InitialCrop = {
     width: number;
 }
 
+export type ImageData = {
+    spacing: {
+        x: number,
+        y: number,
+        z: number,
+        units: string
+    },
+    frames: string[]
+}
+
 export type ULabelSubtasks = { [key: string]: ULabelSubtask };
 
 export class ULabel {
     subtasks: ULabelSubtask[];
     state: any;
-    config: any;
+    config: Configuration;
     toolbox: Toolbox;
     color_info: {[key: number]: string}
     valid_class_ids: number[];
@@ -203,6 +213,7 @@ export class ULabel {
     public toggle_delete_class_id_in_toolbox(): void;
     public change_brush_size(scale_factor: number): void;
     public remove_listeners(): void;
+    static get_allowed_toolbox_item_enum(): AllowedToolboxItem;
     static process_classes(ulabel_obj: any, arg1: string, subtask_obj: any);
     static build_id_dialogs(ulabel_obj: any);
 

dist/ulabel.min.js

@@ -1,7 +1,7 @@
 {
   "name": "ulabel",
   "description": "An image annotation tool.",
-  "version": "0.12.5",
+  "version": "0.13.0",
   "main": "dist/ulabel.js",
   "module": "dist/ulabel.js",
   "scripts": {