diff --git a/docs/guides/layers.md b/docs/guides/layers.md index 596f01480..f55b57df9 100644 --- a/docs/guides/layers.md +++ b/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` diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index cdb6b8132..bc2e46fdc 100644 --- a/docs/howtos/layers/image.md +++ b/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 diff --git a/docs/howtos/layers/labels.md b/docs/howtos/layers/labels.md index badc22cd7..3710e63de 100644 --- a/docs/howtos/layers/labels.md +++ b/docs/howtos/layers/labels.md @@ -46,6 +46,7 @@ layer: * fill bucket * color picker * pan/zoom mode + * transform mode * Controls * label * opacity @@ -256,6 +257,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` diff --git a/docs/howtos/layers/points.md b/docs/howtos/layers/points.md index 366150640..6913637dc 100644 --- a/docs/howtos/layers/points.md +++ b/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 diff --git a/docs/howtos/layers/shapes.md b/docs/howtos/layers/shapes.md index 03b85f09d..8aa116d1a 100644 --- a/docs/howtos/layers/shapes.md +++ b/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) diff --git a/docs/howtos/layers/surface.md b/docs/howtos/layers/surface.md index 24219575e..058f7c70a 100644 --- a/docs/howtos/layers/surface.md +++ b/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` diff --git a/docs/howtos/layers/tracks.md b/docs/howtos/layers/tracks.md index 10c900f60..3045a9ad9 100644 --- a/docs/howtos/layers/tracks.md +++ b/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` 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` 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` 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" diff --git a/docs/howtos/layers/vectors.md b/docs/howtos/layers/vectors.md index 25c3f91df..e4c6a781d 100644 --- a/docs/howtos/layers/vectors.md +++ b/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 diff --git a/docs/images/pan-zoom-tool.png b/docs/images/pan-zoom-tool.png index 01bdbb9b6..075fa86e9 100644 Binary files a/docs/images/pan-zoom-tool.png and b/docs/images/pan-zoom-tool.png differ diff --git a/docs/images/transform-tool.png b/docs/images/transform-tool.png new file mode 100644 index 000000000..3488d5701 Binary files /dev/null and b/docs/images/transform-tool.png differ