Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add basic layer modes description, including transform button #420

Merged
merged 11 commits into from
Jul 11, 2024
Merged

Add basic layer modes description, including transform button #420

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e854031
Add basic layer modes description ('pan_zoom' and 'transform')
dalthviz May 8, 2024
7f6656f
Add info about pan/zoom and transform mode button for layers specific…
dalthviz May 9, 2024
d18eede
Simplify base modes description
dalthviz May 9, 2024
2271ba0
Merge branch 'main' into transform_mode_button
dalthviz May 20, 2024
fc76967
Apply suggestions from code review
dalthviz May 21, 2024
be5ac4b
Add shortcuts to transform and pan/zoom descriptions
dalthviz May 22, 2024
c28832f
Apply suggestions from code review
dalthviz Jun 6, 2024
477a87d
Merge branch 'main' into transform_mode_button
dalthviz Jun 6, 2024
e0996b5
Update pan-zoom tool image
dalthviz Jun 6, 2024
5b38511
Merge branch 'main' into transform_mode_button
dalthviz Jun 7, 2024
b692b67
Merge branch 'main' into transform_mode_button
jni Jul 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/guides/layers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,32 @@ currently supported by napari, check out the
introduction, check out the
[Layer list section in the napari viewer tutorial](layer-list).

(layer_mode)=
## Layer mode

All our layers support a `mode` property that changes the way you interact
with the layer from the viewer. These modes are accesible via the layer controls
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
widget top buttons and via shortcuts (pressing a number from `1` to the number of
modes available for the layer). Depending on the layer type, more modes could be
available. Currently, there are two base modes:
dalthviz marked this conversation as resolved.
Show resolved Hide resolved

* Pan and zoom
![image: Pan/zoom](../images/pan-zoom-tool.png)
psobolewskiPhD marked this conversation as resolved.
Show resolved Hide resolved

The `pan_zoom` mode allows you to pan around and zoom in/out the layer. It's
the default mode selected.
dalthviz marked this conversation as resolved.
Show resolved Hide resolved

* Transform
![image: Transform](../images/transform-tool.png)

The `transform` mode allows you to translate, rotate, and scale the layer
graphically. To reset the transformation, you can Option/Alt-click the transform
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
button over the layer controls (a confirmation dialog will open to confirm
the reset).

For a more detailed description of layer modes available check each
[layer how-to guide](using-layers).

## Layer visibility

All our layers support a visibility toggle that allows you to set the `visible`
Expand Down
32 changes: 25 additions & 7 deletions docs/howtos/layers/image.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,37 @@ For more information about layers, refer to [Layers at a glance](../../guides/la

The GUI contains following tools in the `layer controls` panel for the `image`
layer:
* Opacity
* Contrast Limits
* Auto-contrast
* Gamma
* Colormap
* Blending
* Interpolation

* Buttons
* Pan/zoom
* Transform
* Controls
* Opacity
* Contrast Limits
* Auto-contrast
* Gamma
* Colormap
* Blending
* Interpolation

Before we can use any of the GUI `layer controls`, we must load an image.
1. Start napari.
2. Click `File` > `Open Sample` > `napari builtins` > `Cells (3D+2Ch)` or any
sample image of your choice.

### Buttons

* `Pan/zoom` ![image: Pan/zoom tool](../../images/pan-zoom-tool.png) is the default mode
of the layer and supports panning and zooming. Press the `1` key when the layer is selected
to use this mode.

* `Transform` ![image: Transform](../../images/transform-tool.png) enables you to
rotate, scale, or translate the layer. To reset the transformation,
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
you can Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset). Press the `2` key when the layer is selected to use this mode.

### Controls

The GUI controls may be adjusted as follows:

* `opacity` is adjusted by moving the circle along the slider until the image
Expand Down
9 changes: 9 additions & 0 deletions docs/howtos/layers/labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ layer:
* fill bucket
* color picker
* pan/zoom mode
* transform mode
* Controls
* label
* opacity
Expand Down Expand Up @@ -256,6 +257,14 @@ pan and zoom is selected, editing the layer is not possible. Once you click on
one of the editing tools, pan and zoom is turned off. Return to pan and zoom
mode by pressing the `6` key when the `labels layer` is selected.

### Transform mode

This mode is represented by ![image: Transform](../../images/transform-tool.png) in the
`layer controls` panel. It enables you to rotate, scale, or translate the layer.
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
To reset the transformation, you can Option/Alt-click the transform button (a
confirmation dialog will open to confirm the reset). Enable this mode by pressing
the `7` key when the `labels layer` is selected.

### Creating a new `labels layer`

Create a brand-new empty `labels layer` by clicking the `New labels layer`
Expand Down
9 changes: 9 additions & 0 deletions docs/howtos/layers/points.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@ layer:
* Add points
* Select points
* Pan/zoom
* Transform
* Controls
* Opacity
* Point size
Expand Down Expand Up @@ -125,6 +126,14 @@ layer:
options are supported only when viewing a layer using 2D rendering. Return to
pan and zoom mode by pressing the `4` key when the points layer is selected.

* **Transform**
![image: Transform](../../images/transform-tool.png)

Use this tool to rotate, scale, or translate the layer. To reset the transformation,
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
you can Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset). Enable this mode by pressing the `5` key when the points layer
is selected.

### Controls

* Opacity
Expand Down
10 changes: 9 additions & 1 deletion docs/howtos/layers/shapes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,7 @@ are used. i.e. You can't remove a vertex before you have created a shape.
* Select vertices
* Select shapes
* Pan/zoom
* Transform
* Move to back
* Move to front
* Add ellipses
Expand Down Expand Up @@ -171,13 +172,20 @@ are used. i.e. You can't remove a vertex before you have created a shape.
than one shape, select one, hold down the shift key and select the rest.

* **Pan/zoom**
![image: Select shapes](../../images/pan-zoom-tool.png)
![image: Pan/zoom](../../images/pan-zoom-tool.png)

Use this tool to pan around the image or zoom in. Pan and zoom functionality
is disabled when using the adding and editing tools. Temporarily re-enable pan
and zoom by pressing and holding the spacebar. This feature can be useful if
you want to move around the shapes layer as you edit it.

* **Transform**
![image: Transform](../../images/transform-tool.png)

Use this tool to rotate, scale, or translate the layer. To reset the transformation,
you can Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 6 and 7 keyboard shortcuts are also valid here.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @melissawm thanks for the review! You mean changing this to be something like:

 Use this tool to rotate, scale, or translate the layer. To activate the tool, you can
 press `7`. To reset the transformation, you can Option/Alt-click the transform
 button (a confirmation dialog will open to confirm the reset).

?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes - and add the information about the keyboard shortcut to the pan/zoom tool as well if you can. Thanks!


* **Move to back**
![image: Move to back](../../images/shape-move-to-back.png)

Expand Down
37 changes: 23 additions & 14 deletions docs/howtos/layers/surface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,20 +77,29 @@ viewer.close()
Once you have created a `surface` layer programmatically, the following GUI
controls are available in the viewer:

* Opacity - use this slider control to assign opacity from 0 to 1.00 where 0 is
transparent and 1.00 is completely opaque.
* Contrast Limits - click and slide the dots on either end of the slider bar to
adjust upper and lower contrast limits.
* Auto-contrast - choose once or continuous.
* Gamma - Click on the oval on the gamma slider bar and adjust it to any value
between 0.20 and 2.00. Gamma correction or gamma is a nonlinear operation used
to encode and decode luminance or tristimulus values in video or still image
systems.
* Colormap - select a value from the dropdown list.
* Blending - Choose `opaque`, `translucent`, `translucent no depth`, or
`additive` from the dropdown. Refer to the [Blending layers](blending-layers)
section of _Layers at a glance_ for an explanation of each type of blending.
* Shading - Choose `none`, `flat`, or `smooth` from the dropdown.
* **Buttons**
* Pan/zoom - ![image: Pan/zoom tool](../../images/pan-zoom-tool.png) is the default
mode of the layer and supports panning and zooming. Press the `1` key when the
layer is selected to use this mode.
* Transform - ![image: Transform](../../images/transform-tool.png) enables you to
rotate, scale, or translate the layer. To reset the transformation, you can
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset). Press the `2` key when the layer is selected to use this mode.
* **Controls**
* Opacity - use this slider control to assign opacity from 0 to 1.00 where 0 is
transparent and 1.00 is completely opaque.
* Contrast Limits - click and slide the dots on either end of the slider bar to
adjust upper and lower contrast limits.
* Auto-contrast - choose once or continuous.
* Gamma - Click on the oval on the gamma slider bar and adjust it to any value
between 0.20 and 2.00. Gamma correction or gamma is a nonlinear operation used
to encode and decode luminance or tristimulus values in video or still image
systems.
* Colormap - select a value from the dropdown list.
* Blending - Choose `opaque`, `translucent`, `translucent no depth`, or
`additive` from the dropdown. Refer to the [Blending layers](blending-layers)
section of _Layers at a glance_ for an explanation of each type of blending.
* Shading - Choose `none`, `flat`, or `smooth` from the dropdown.

## Arguments of `view_surface` and `add_surface`

Expand Down
65 changes: 37 additions & 28 deletions docs/howtos/layers/tracks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,34 +92,43 @@ napari.run()

## GUI controls for the `tracks` layer

* Color by - there is a dropdown for this but at present the only choice is
`track_id`.
* Colormap - choose a colormap from the dropdown. These are explained in
[the colormaps section](./surface.md#working-with-colormaps) of
_Using the surface layer_.
* Blending - choose `opaque`, `translucent`, `translucent no depth`, `minimum`
or `additive` from the dropdown. Refer to the
[Blending layers](blending-layers) section of _Layers at a glance_ for an
explanation of each type of blending.
* Opacity - click and hold the circle on the opacity slider bar and adjust it to
any value between 0.00 (clear) and 1.00 (completely opaque).
* Tail width - adjusting the tail width gives the track the appearance of being
narrower or wider. At the minimum value, the track looks like a one-pixel
line.
* Tail length - adjusting the tail length gives the track the appearance of
being shorter or longer. At the minimum value, it looks something like a
dotted line, at the maximum value it almost looks like an unbroken line.
* Head length - Adjusting the head length gives the track the appearance of
being longer. If it is adjusted to the maximum value, the tracks look like
stripes. At the minimum value, the tracks flash across the canvas and
disappear before starting again.
* Tail - check this box to see the tracks. If it is not checked, you will not be
able to see the tracks at all.
* Show ID - check this box to display a previously assigned `track_id` label for
each track. Assigning values to `track_id` is explained in
[Tracks data](#tracks-data) below.
* Graph - check this box to display a previously created graph as explained in
[](#arguments-of-view_tracks-and-add_tracks).
* **Buttons**
* Pan/zoom - ![image: Pan/zoom tool](../../images/pan-zoom-tool.png) is the default
mode of the layer and supports panning and zooming. Press the `1` key when the
layer is selected to use this mode.
* Transform - ![image: Transform](../../images/transform-tool.png) enables you to
rotate, scale, or translate the layer. To reset the transformation, you can
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset). Press the `2` key when the layer is selected to use this mode.
* **Controls**
* Color by - there is a dropdown for this but at present the only choice is
`track_id`.
* Colormap - choose a colormap from the dropdown. These are explained in
[the colormaps section](./surface.md#working-with-colormaps) of
_Using the surface layer_.
* Blending - choose `opaque`, `translucent`, `translucent no depth`, `minimum`
or `additive` from the dropdown. Refer to the
[Blending layers](blending-layers) section of _Layers at a glance_ for an
explanation of each type of blending.
* Opacity - click and hold the circle on the opacity slider bar and adjust it to
any value between 0.00 (clear) and 1.00 (completely opaque).
* Tail width - adjusting the tail width gives the track the appearance of being
narrower or wider. At the minimum value, the track looks like a one-pixel
line.
* Tail length - adjusting the tail length gives the track the appearance of
being shorter or longer. At the minimum value, it looks something like a
dotted line, at the maximum value it almost looks like an unbroken line.
* Head length - Adjusting the head length gives the track the appearance of
being longer. If it is adjusted to the maximum value, the tracks look like
stripes. At the minimum value, the tracks flash across the canvas and
disappear before starting again.
* Tail - check this box to see the tracks. If it is not checked, you will not be
able to see the tracks at all.
* Show ID - check this box to display a previously assigned `track_id` label for
each track. Assigning values to `track_id` is explained in
[Tracks data](#tracks-data) below.
* Graph - check this box to display a previously created graph as explained in
[](#arguments-of-view_tracks-and-add_tracks).

## Arguments of `view_tracks` and `add_tracks`

Expand Down
57 changes: 32 additions & 25 deletions docs/howtos/layers/vectors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,29 +85,38 @@ Before you can use the GUI to manipulate vectors, you must load a vector layer.
Please refer to [A simple example](#a-simple-example) to add a `vectors` layer
first, then explore the editing options the GUI provides.

* Opacity - click and hold the circle on the opacity slider bar and adjust it to
any value between 0.00 (clear) and 1.00 (completely opaque).
* Width - adjusting the width makes the vectors appear thicker or thinner. Use
the + and - buttons on either side of the width bar to adjust width or click
on the number in the middle of the bar and enter a value. The minimum value is
0.10.
* Length - adjusting the length makes the vector longer or shorter. Use the +
and - buttons on either side of the length bar to adjust length or click on
the number in the middle of the bar and enter a value. The minimum value is
0.10.
* Blending - `blending` has the options of `opaque`, `translucent`,
`translucent no depth`, `minimum`, or `additive` in the dropdown. Refer to the
[Blending layers](blending-layers) section of _Layers at a glance_ for an
explanation of each type of blending.
* Edge color mode - select `direct`, `cycle`, or `colormap` from the dropdown.
* Direct (default mode) allows each vector to be set arbitrarily.
* Cycle allows the color to be set via a color cycle over an attribute.
* Colormap allows the color to be set via a color map over an attribute.
* Edge color - click the thumbnail next to `edge color:` to select or create a
color from the pallette.
* Out of slice - if this box is checked, `out of slice` is on or true. If this
box is not checked, `out of slice` is off or false. If it is on or true,
vectors slightly out of slice are rendered.
* **Buttons**
* Pan/zoom - ![image: Pan/zoom tool](../../images/pan-zoom-tool.png) is the default
mode of the layer and supports panning and zooming. Press the `1` key when the
layer is selected to use this mode.
* Transform - ![image: Transform](../../images/transform-tool.png) enables you to
rotate, scale, or translate the layer. To reset the transformation, you can
dalthviz marked this conversation as resolved.
Show resolved Hide resolved
Option/Alt-click the transform button (a confirmation dialog will open to
confirm the reset). Press the `2` key when the layer is selected to use this mode.
* **Controls**
* Opacity - click and hold the circle on the opacity slider bar and adjust it to
any value between 0.00 (clear) and 1.00 (completely opaque).
* Width - adjusting the width makes the vectors appear thicker or thinner. Use
the + and - buttons on either side of the width bar to adjust width or click
on the number in the middle of the bar and enter a value. The minimum value is
0.10.
* Length - adjusting the length makes the vector longer or shorter. Use the +
and - buttons on either side of the length bar to adjust length or click on
the number in the middle of the bar and enter a value. The minimum value is
0.10.
* Blending - `blending` has the options of `opaque`, `translucent`,
`translucent no depth`, `minimum`, or `additive` in the dropdown. Refer to the
[Blending layers](blending-layers) section of _Layers at a glance_ for an
explanation of each type of blending.
* Edge color mode - select `direct`, `cycle`, or `colormap` from the dropdown.
* Direct (default mode) allows each vector to be set arbitrarily.
* Cycle allows the color to be set via a color cycle over an attribute.
* Colormap allows the color to be set via a color map over an attribute.
* Edge color - click the thumbnail next to `edge color:` to select or create a
color from the pallette.
* Out of slice - if this box is checked, `out of slice` is on or true. If this
box is not checked, `out of slice` is off or false. If it is on or true,
vectors slightly out of slice are rendered.

### Vector starting position

Expand Down Expand Up @@ -159,8 +168,6 @@ Set the width of all the vectors in a layer using the `layer.width` property.

Set the color of all the vectors in a layer using the `layer.edge_color` property.

Pan and zoom are not available on the vectors layer.

## Vectors data

The input data to the `vectors` layer must be an `Nx2xD` NumPy array
Expand Down
Binary file added docs/images/transform-tool.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading