Add basic layer modes description, including transform button (#420)

# References and relevant issues

Depends on napari/napari#6794

# Description

Adds new content related with layers transform mode and base possible
values (`pan_zoom` and `transform`)


---------

Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com>
Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>
Co-authored-by: Juan Nunez-Iglesias <jni@fastmail.com>

Author: 4 people

docs/guides/layers.md

@@ -28,6 +28,31 @@ 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 accessible via the layer controls
+widget top buttons and via keyboard shortcuts (these shortcuts will vary depending on the layer type). Currently, there are two base modes:
+
+* Pan and zoom
+![image: Pan/zoom](../images/pan-zoom-tool.png)
+
+The `pan_zoom` mode allows you to pan around and zoom in/out the layer. It's
+the default mode selected. Note: zooming with the mouse-wheel should essentially always work!
+
+* Transform
+![image: Transform](../images/transform-tool.png)
+
+The `transform` mode allows you to translate, rotate, and scale the layer
+graphically. Note: While you can transform 3D layers, at present this mode is only usable in 2D viewer display mode.
+To reset the transformation, you can Option/Alt-click the transform
+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`

docs/howtos/layers/image.md

@@ -25,19 +25,38 @@ 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. Note: at present this feature is limited to 2D viewer display mode.
+  To reset the transformation,
+  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

docs/howtos/layers/labels.md

@@ -46,6 +46,7 @@ layer:
     * fill bucket
     * color picker
     * pan/zoom mode
+    * transform mode
 * Controls
     * label
     * opacity
@@ -257,6 +258,15 @@ 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.
+Note: at present this feature is limited to 2D viewer display mode.
+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`

docs/howtos/layers/points.md

@@ -54,6 +54,7 @@ layer:
     * Add points
     * Select points
     * Pan/zoom
+    * Transform
 * Controls
     * Opacity
     * Point size
@@ -125,6 +126,15 @@ 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. 
+  Note: at present this feature is limited to 2D viewer display mode. 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 `5` key when the points layer
+  is selected.
+
 ### Controls
 
 * Opacity

docs/howtos/layers/shapes.md

@@ -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
@@ -171,12 +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.
+  Use this tool to pan around the layer or zoom in. Pan functionality
+  is disabled when using the adding and editing tools; however, zoom using the mouse-wheel will typically continue to work. To activate the tool,
+  you can press `6`. 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. Note: at present this feature is limited to 2D viewer display mode. 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).
 
 * **Move to back**
   ![image: Move to back](../../images/shape-move-to-back.png)

docs/howtos/layers/surface.md

@@ -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. Note: at present this feature is limited to 2D viewer display mode. To reset the transformation, 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**
+  * 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`
 

docs/howtos/layers/tracks.md

@@ -92,33 +92,42 @@ 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.
+* **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. Note: at present this feature is limited to 2D viewer display mode. To reset the transformation, 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**
+  * 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.
 
 ## Tracks data
 
@@ -212,7 +221,7 @@ other high dimensional data.
 ## Changing track width
 
 We can specify the width of the tracks in pixels. The track width can be
-specified via the `tail_width` keyword argument in the `viewer.add_tracks()` and
+specified via the `tail_width` keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and
 `napari.view_tracks()` methods. From a layer that has already been constructed,
 we can set the track width via the `layer.tail_width` property.
 
@@ -245,7 +254,7 @@ Additionally, we can adjust the width of the track in the GUI using the
 We can specify the length of the tails of the tracks in time units. The tail is
 the portion of the track displayed from previous time steps. The track tail
 length can be specified via the `tail_length` keyword argument in the
-`viewer.add_tracks()` and `napari.view_tracks()` methods. From a layer that has
+{meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and `napari.view_tracks()` methods. From a layer that has
 already been constructed, we can set the track width via the `tail_length`
 property.
 
@@ -278,7 +287,7 @@ length" slider in the `tracks` layer controls.
 
 We can color the tracks by mapping colors to the track features defined in
 `Tracks.features`. If we define features and pass them via the `features`
-keyword argument in the `viewer.add_tracks()` and `napari.view_tracks()`
+keyword argument in the {meth}`viewer.add_tracks<napari.Viewer.add_tracks>` and `napari.view_tracks()`
 methods, we can then select the feature we would like to color the tracks by in
 the "color by" dropdown menu in the `tracks` layer controls. We can additionally
 specify the colormap used to map the feature value to color via the "colormap"

docs/howtos/layers/vectors.md

@@ -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. Note: at present this feature is limited to 2D viewer display mode. To reset the transformation, 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**
+  * 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  
 
@@ -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