Skip to content

Commit 82a739e

Browse files
laura-borghesi-lum00ndaron1337
laura-borghesi-lum00n
and
daron1337
authored
Tools docs (#419)
* feat: init tools doc * added new docs tools pt * segmentation docs * default and custom tools doc * fix default docs * tool initialization doc * dvTools * dvTools doc implementation * version * overlay tool * interacting doc --------- Co-authored-by: daron1337 <[email protected]>
1 parent 0f66ed4 commit 82a739e

File tree

10 files changed

+1368
-34
lines changed

10 files changed

+1368
-34
lines changed

‎docs/.vuepress/config.js

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,8 +112,20 @@ export default {
112112
text: "Interaction Tools",
113113
children: [
114114
{
115-
text: "Main Tools",
116-
link: "/api/modules/tools/tools.md"
115+
text: "Initialize and manage Tools",
116+
link: "/api/modules/tools/initialization.md"
117+
},
118+
{
119+
text: "Default and Custom Tools",
120+
link: "/api/modules/tools/default.md"
121+
},
122+
{
123+
text: "Segmentation Tools",
124+
link: "/api/modules/tools/segmentation.md"
125+
},
126+
{
127+
text: "DvTools",
128+
link: "/api/modules/tools/dvTools.md"
117129
}
118130
]
119131
},

‎docs/api/interacting.md

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,64 @@
1-
<div style="text-align: center;">
1+
<div align="center">
22
<img src="https://assets.pokemon.com/assets/cms2/img/pokedex/full/246.png" alt="Larvitar" height="200" />
33
</div>
44

5-
Coming soon...
5+
# CornerstoneTools
66

7-
<br></br>
7+
[CornerstoneTools](https://github.com/cornerstonejs/cornerstoneTools) is a powerful library designed for creating, managing, and utilizing interactive tools in medical imaging applications. Built on top of the Cornerstone framework, it provides a collection of tools for annotations, measurements, and more. Larvitar supports the integration of custom tools, allowing developers to extend its functionality to meet specific requirements.
88

9-
<div style="text-align: center;">
9+
## Key Features
10+
11+
### Annotation Tools
12+
13+
Annotation tools allow users to add information directly to images for reference or analysis. Examples include:
14+
15+
- **Length Tool:** Measures the distance between two points.
16+
- **Angle Tool:** Calculates angles between intersecting lines.
17+
- **Text Annotation Tool:** Adds descriptive labels or comments on specific areas of the image.
18+
19+
These tools are vital for medical professionals to document findings, mark regions of interest (ROIs), and collaborate effectively.
20+
21+
### Segmentation Tools
22+
23+
Segmentation tools help divide medical images into meaningful regions, such as organs or abnormalities. These tools are commonly used in diagnostics and surgical planning:
24+
25+
- **Brush Tool:** Allows users to paint areas of interest for segmentation.
26+
- **Threshold Tool:** Automatically segments regions based on intensity values.
27+
- **Freehand Tool:** Enables precise manual segmentation by drawing custom shapes.
28+
29+
By isolating specific areas, segmentation provides a clearer understanding of the image data.
30+
31+
### Interaction Tools
32+
33+
Interaction tools enhance the user's ability to navigate and manipulate medical images:
34+
35+
- **Zoom Tool:** Magnifies the image for a detailed view.
36+
- **Pan Tool:** Moves the image within the viewport for better positioning.
37+
- **Window Level Tool:** Adjusts the brightness and contrast of the image for better visualization of features.
38+
39+
These tools ensure users can efficiently explore the image and focus on specific details.
40+
41+
### Custom Tools
42+
43+
Larvitar allows developers to create custom tools tailored to their specific imaging workflows. These tools can be:
44+
45+
- Configured with custom behavior.
46+
- Registered to handle specific user interactions.
47+
- Integrated seamlessly with Cornerstone-enabled applications.
48+
49+
## How It Works
50+
51+
1. **Tool Registration:**
52+
Tools are registered with `registerExternalTool` to make them available within the application. Developers can define their own tools or use the prebuilt ones provided by the library.
53+
54+
2. **Usage in Imaging:**
55+
Tools operate directly on the imaging data rendered in the registered viewport.
56+
57+
3. **Tool Configuration:**
58+
Tools are configured to handle user input events like mouse clicks, drags, and scrolls. Custom configurations allow fine-tuning the behavior for specific imaging requirements.
59+
60+
<br/><br/>
61+
62+
<div align="center">
1063
<img src="https://press.r1-it.storage.cloud.it/logo_trasparent.png" alt="D/Vision Lab" height="200" />
11-
</div>
64+
</div>

‎docs/api/modules/tools/default.md

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
<div style="text-align: center;">
2+
<img src="https://assets.pokemon.com/assets/cms2/img/pokedex/full/246.png" alt="Larvitar" height="200" />
3+
</div>
4+
5+
## Introduction: default Tools
6+
7+
In `default.ts` the list of Larvitar default tools is exported as `DEFAULT_TOOLS`, along with their default configuration, that extendes the cornerstoneTools configuration with these properties:
8+
9+
- **Name:** String representing the tool's name.
10+
- **Viewports:** Specifies the viewports targeted by the tool (`"all"` or an array of specific viewports).
11+
- **Configuration:** Configuration options defined as an object.
12+
- **Options:** Additional options defined as an object.
13+
- **Class:** The corresponding Cornerstone tool library class (e.g., `"LengthTool"` for the length measurement tool).
14+
- **Sync:** Synchronization behavior for the tool.
15+
- **Cleanable:** if true, this tool will be removed when calling `"no tools"`,
16+
- **DefaultActive:** if true, this tool will be activated when calling `addDefaultTools`,
17+
- **Shortcut:** keyboard shortcut [not implemented],
18+
- **Type:** tool category inside Larvitar (one of: `"utils", "annotation", "segmentation", "overlay"`),
19+
- **Description:** a string that describes the tool (eg to be shown in a tooltip)
20+
21+
These tools are either cornerstone-customized tools or fully custom tools (e.g., `watershedSegmentationTool`) and can be added to the viewport through `addDefaultTools`.
22+
23+
### Example: Tool Definition
24+
25+
```typescript
26+
Zoom: {
27+
name: "Zoom",
28+
viewports: "all",
29+
configuration: {
30+
invert: false,
31+
preventZoomOutsideImage: false,
32+
minScale: 0.01,
33+
maxScale: 25.0
34+
},
35+
options: {
36+
mouseButtonMask: 2,
37+
supportedInteractionTypes: ["Mouse", "Touch"],
38+
defaultStrategy: "default" // can be 'default', 'translate' or 'zoomToCenter'
39+
},
40+
cleanable: false,
41+
class: "ZoomTool",
42+
defaultActive: true,
43+
description: "Zoom image at mouse position",
44+
shortcut: "ctrl-z",
45+
type: "utils"
46+
}
47+
```
48+
49+
### Example: Default Tools Activation
50+
51+
```typescript
52+
store.addViewport("viewer");
53+
initializeCSTools();
54+
addDefaultTools();
55+
setToolActive("Wwwc"); //explicitly set the active tool. If not, default active is StackScroll
56+
```
57+
58+
## Introduction: custom Tools
59+
60+
User can add custom tools calling `registerExternalTool`. The tool will be registered in the dvTools object and in `DEFAULT_TOOLS` array. If done **before** adding the tools with `addDefaultTools`, the tool will be added automatically along with the default ones. Otherwise, the user can simply add its tool using `addTool`.
61+
62+
### Example: Custom Tools Registration
63+
64+
```typescript
65+
initializeCSTools();
66+
store.addViewport("viewer");
67+
registerExternalTool("customTool");
68+
addTool("customTool"); //or directly use addDefaultTools();
69+
setToolActive("customTool");
70+
```
71+
72+
## API Reference
73+
74+
### `getDefaultToolsByType`
75+
76+
Gets available tools by type, which is useful for populating menus.
77+
78+
#### Syntax
79+
80+
```typescript
81+
getDefaultToolsByType(type: NonNullable<ToolConfig["type"]>): ToolConfig[]
82+
```
83+
84+
#### Parameters
85+
86+
| Parameter | Type | Description |
87+
| --------- | ------------------------------- | ------------------------------------------------------------- |
88+
| `type` | NonNullable<ToolConfig["type"]> | The type of tool to filter and return from the list of tools. |
89+
90+
#### Returns
91+
92+
`ToolConfig[]` – An array of tool configurations that match the specified type.
93+
94+
### `setDefaultToolsProps`
95+
96+
Overrides the default properties of tools.
97+
98+
#### Syntax
99+
100+
```typescript
101+
setDefaultToolsProps(newProps: Partial<ToolConfig>[]): void
102+
```
103+
104+
#### Parameters
105+
106+
| Parameter | Type | Description |
107+
| ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
108+
| `newProps` | Partial<ToolConfig [] > | An array of objects representing the properties to be overridden for the default tools. The "name" property is mandatory for each object. |
109+
110+
#### Returns
111+
112+
`void` – The function does not return a value. It directly modifies the DEFAULT_TOOLS object with the new properties.
113+
114+
### `registerExternalTool`
115+
116+
Overrides the default properties of tools.
117+
NOTE:
118+
119+
- if toolName is already existent in `DEFAULT_TOOLS`, it will ovverride the tool
120+
- toolClass must be a valid cornerstone tool
121+
122+
#### Syntax
123+
124+
```typescript
125+
registerExternalTool(toolName: string, toolClass: any): void
126+
```
127+
128+
#### Parameters
129+
130+
| Parameter | Type | Description |
131+
| ----------- | ------ | -------------------- |
132+
| `toolName` | string | The name of the tool |
133+
| `toolClass` | string | The tool class |
134+
135+
#### Returns
136+
137+
`void` – The function does not return a value. It directly modifies the DEFAULT_TOOLS and dvTools objects with the new tool.
138+
139+
```typescript
140+
dvTools[toolClass.name] = toolClass;
141+
DEFAULT_TOOLS[toolName] = {
142+
name: toolName,
143+
class: toolClass.name,
144+
viewports: "all",
145+
configuration: {},
146+
options: { mouseButtonMask: 1 },
147+
defaultActive: false
148+
};
149+
```
150+
151+
### `addDefaultTools`
152+
153+
Add all default tools, as listed in `DEFAULT_TOOLS`
154+
155+
#### Syntax
156+
157+
```typescript
158+
addDefaultTools(elementId: string): void
159+
```
160+
161+
#### Parameters
162+
163+
| Parameter | Type | Description |
164+
| ---------- | ------ | ------------------------------------------------------------------------------ |
165+
| `toolName` | string | The id of the cornerstone Enabled Element on which the tools will be activated |
166+
167+
#### Returns
168+
169+
`void`
170+
171+
## Constants
172+
173+
### `dvTools`
174+
175+
Contains a set of custom tools that are used for various processing tasks. The tools are accessible by their respective names and can be extended or modified as needed.
176+
177+
#### Syntax
178+
179+
```typescript
180+
const dvTools: {
181+
[key: string]: any;
182+
} = {
183+
...,
184+
OverlayTool: OverlayTool
185+
};
186+
```
187+
188+
### `DEFAULT_STYLE`
189+
190+
specifies the default visual settings for tools, such as line width, colors, font family, font size, and background color. These can be customized to fit the application's design needs.
191+
192+
#### Syntax
193+
194+
```typescript
195+
const DEFAULT_STYLE: ToolStyle = {
196+
width: 1,
197+
color: "#02FAE5",
198+
activeColor: "#00FF00",
199+
fillColor: "#0000FF",
200+
fontFamily: "Roboto",
201+
fontSize: 18,
202+
backgroundColor: "rgba(1, 1, 1, 0.7)"
203+
};
204+
```
205+
206+
### `DEFAULT_SETTINGS`
207+
208+
defines the default behavior of tools, such as whether mouse and touch interactions are enabled, SVG cursors are shown, and whether global tool synchronization is active. It also includes settings like auto-resizing viewports and line dash styles.
209+
210+
#### Syntax
211+
212+
```typescript
213+
const DEFAULT_SETTINGS: ToolSettings = {
214+
mouseEnabled: true,
215+
touchEnabled: true,
216+
showSVGCursors: true,
217+
globalToolSyncEnabled: false,
218+
autoResizeViewports: true,
219+
lineDash: [4, 4]
220+
};
221+
```
222+
223+
### `DEFAULT_MOUSE_KEYS`
224+
225+
configures default interactions for the tools. It includes mouse button mappings (e.g., shift + left mouse button for zoom), right mouse button bindings, and keyboard shortcuts. These defaults can be customized to change the behavior of the tools.
226+
227+
#### Syntax
228+
229+
```typescript
230+
const DEFAULT_MOUSE_KEYS: ToolMouseKeys = {
231+
debug: true, // log changes
232+
mouse_button_left: {
233+
shift: "Zoom",
234+
ctrl: "Pan",
235+
default: "Wwwc"
236+
},
237+
mouse_button_right: {
238+
shift: "Zoom",
239+
ctrl: "Pan",
240+
default: "Wwwc"
241+
},
242+
keyboard_shortcuts: {
243+
// alt key + letter
244+
KEY_R: "Rotate",
245+
KEY_A: "Angle",
246+
KEY_L: "Length"
247+
}
248+
};
249+
```
250+
251+
<br></br>
252+
253+
<div style="text-align: center;">
254+
<img src="https://press.r1-it.storage.cloud.it/logo_trasparent.png" alt="D/Vision Lab" height="200" />
255+
</div>
256+
```

0 commit comments

Comments
 (0)