deploy: napari/docs@a7359fe

napari · Dec 19, 2023 · 319e383 · 319e383
1 parent 04328f2
commit 319e383
Show file tree

Hide file tree

Showing 320 changed files with 7,362 additions and 4,494 deletions.
diff --git a/dev/.buildinfo b/dev/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 674c500bcf616bed392b6a4cc5d7565e
+config: ef533a35fd9eeda111a4a65ed0ffc4e4
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/dev/.doctrees/developers/architecture/app_model.doctree b/dev/.doctrees/developers/architecture/app_model.doctree
diff --git a/dev/.doctrees/developers/architecture/dir_organization.doctree b/dev/.doctrees/developers/architecture/dir_organization.doctree
diff --git a/dev/.doctrees/developers/architecture/index.doctree b/dev/.doctrees/developers/architecture/index.doctree
diff --git a/dev/.doctrees/developers/architecture/napari_models.doctree b/dev/.doctrees/developers/architecture/napari_models.doctree
diff --git a/dev/.doctrees/developers/documentation/docs_template.doctree b/dev/.doctrees/developers/documentation/docs_template.doctree
diff --git a/dev/.doctrees/developers/index.doctree b/dev/.doctrees/developers/index.doctree
diff --git a/dev/.doctrees/developers/testing.doctree b/dev/.doctrees/developers/testing.doctree
diff --git a/dev/.doctrees/environment.pickle b/dev/.doctrees/environment.pickle
diff --git a/dev/.doctrees/gallery/action_manager.doctree b/dev/.doctrees/gallery/action_manager.doctree
diff --git a/dev/.doctrees/gallery/sg_execution_times.doctree b/dev/.doctrees/gallery/sg_execution_times.doctree
diff --git a/dev/.doctrees/gallery/surface_multi_texture.doctree b/dev/.doctrees/gallery/surface_multi_texture.doctree
diff --git a/dev/.doctrees/guides/app_model.doctree b/dev/.doctrees/guides/app_model.doctree
diff --git a/dev/.doctrees/guides/index.doctree b/dev/.doctrees/guides/index.doctree
diff --git a/dev/.doctrees/guides/magicgui.doctree b/dev/.doctrees/guides/magicgui.doctree
diff --git a/dev/.doctrees/guides/napari_models.doctree b/dev/.doctrees/guides/napari_models.doctree
diff --git a/dev/.doctrees/guides/preferences.doctree b/dev/.doctrees/guides/preferences.doctree
diff --git a/dev/.doctrees/howtos/layers/image.doctree b/dev/.doctrees/howtos/layers/image.doctree
diff --git a/dev/.doctrees/howtos/layers/labels.doctree b/dev/.doctrees/howtos/layers/labels.doctree
diff --git a/dev/.doctrees/howtos/layers/points.doctree b/dev/.doctrees/howtos/layers/points.doctree
diff --git a/dev/.doctrees/howtos/layers/shapes.doctree b/dev/.doctrees/howtos/layers/shapes.doctree
diff --git a/dev/.doctrees/howtos/layers/surface.doctree b/dev/.doctrees/howtos/layers/surface.doctree
diff --git a/dev/.doctrees/howtos/layers/vectors.doctree b/dev/.doctrees/howtos/layers/vectors.doctree
diff --git a/dev/.doctrees/sg_execution_times.doctree b/dev/.doctrees/sg_execution_times.doctree
diff --git a/dev/.doctrees/tutorials/fundamentals/getting_started.doctree b/dev/.doctrees/tutorials/fundamentals/getting_started.doctree
diff --git a/dev/.doctrees/tutorials/fundamentals/quick_start.doctree b/dev/.doctrees/tutorials/fundamentals/quick_start.doctree
diff --git a/dev/.doctrees/tutorials/fundamentals/viewer.doctree b/dev/.doctrees/tutorials/fundamentals/viewer.doctree
diff --git a/dev/_images/2028cec28ca0de8a004303fa2c53325facc182199f599ac776b7a6ed6e9cc0ad.png b/dev/_images/2028cec28ca0de8a004303fa2c53325facc182199f599ac776b7a6ed6e9cc0ad.png
diff --git a/dev/_images/bb7a2622b422e001f6d175bba18782f518eece62a9c7c8ebe03fb466a1f2a21b.png b/dev/_images/bb7a2622b422e001f6d175bba18782f518eece62a9c7c8ebe03fb466a1f2a21b.png
diff --git a/dev/_images/preferences-reset.png b/dev/_images/preferences-reset.png
diff --git a/dev/_images/sphx_glr_3D_paths_001.png b/dev/_images/sphx_glr_3D_paths_001.png
diff --git a/dev/_images/sphx_glr_3D_paths_thumb.png b/dev/_images/sphx_glr_3D_paths_thumb.png
diff --git a/dev/_images/sphx_glr_3Dimage_plane_rendering_001.png b/dev/_images/sphx_glr_3Dimage_plane_rendering_001.png
diff --git a/dev/_images/sphx_glr_3Dimage_plane_rendering_thumb.png b/dev/_images/sphx_glr_3Dimage_plane_rendering_thumb.png
diff --git a/dev/_images/sphx_glr_add-points-3d_001.png b/dev/_images/sphx_glr_add-points-3d_001.png
diff --git a/dev/_images/sphx_glr_add-points-3d_thumb.png b/dev/_images/sphx_glr_add-points-3d_thumb.png
diff --git a/dev/_images/sphx_glr_add_3D_image_001.png b/dev/_images/sphx_glr_add_3D_image_001.png
diff --git a/dev/_images/sphx_glr_add_3D_image_thumb.png b/dev/_images/sphx_glr_add_3D_image_thumb.png
diff --git a/dev/_images/sphx_glr_add_grayscale_image_001.png b/dev/_images/sphx_glr_add_grayscale_image_001.png
diff --git a/dev/_images/sphx_glr_add_grayscale_image_thumb.png b/dev/_images/sphx_glr_add_grayscale_image_thumb.png
diff --git a/dev/_images/sphx_glr_add_vectors_image_001.png b/dev/_images/sphx_glr_add_vectors_image_001.png
diff --git a/dev/_images/sphx_glr_add_vectors_image_thumb.png b/dev/_images/sphx_glr_add_vectors_image_thumb.png
diff --git a/dev/_images/sphx_glr_affine_transforms_001.png b/dev/_images/sphx_glr_affine_transforms_001.png
diff --git a/dev/_images/sphx_glr_affine_transforms_thumb.png b/dev/_images/sphx_glr_affine_transforms_thumb.png
diff --git a/dev/_images/sphx_glr_custom_key_bindings_001.png b/dev/_images/sphx_glr_custom_key_bindings_001.png
diff --git a/dev/_images/sphx_glr_custom_key_bindings_thumb.png b/dev/_images/sphx_glr_custom_key_bindings_thumb.png
diff --git a/dev/_images/sphx_glr_custom_mouse_functions_001.png b/dev/_images/sphx_glr_custom_mouse_functions_001.png
diff --git a/dev/_images/sphx_glr_custom_mouse_functions_thumb.png b/dev/_images/sphx_glr_custom_mouse_functions_thumb.png
diff --git a/dev/_images/sphx_glr_dask_nD_image_001.png b/dev/_images/sphx_glr_dask_nD_image_001.png
diff --git a/dev/_images/sphx_glr_dask_nD_image_thumb.png b/dev/_images/sphx_glr_dask_nD_image_thumb.png
diff --git a/dev/_images/sphx_glr_dynamic-projections-dask_001.png b/dev/_images/sphx_glr_dynamic-projections-dask_001.png
diff --git a/dev/_images/sphx_glr_dynamic-projections-dask_002.png b/dev/_images/sphx_glr_dynamic-projections-dask_002.png
diff --git a/dev/_images/sphx_glr_dynamic-projections-dask_thumb.png b/dev/_images/sphx_glr_dynamic-projections-dask_thumb.png
diff --git a/dev/_images/sphx_glr_layers_001.png b/dev/_images/sphx_glr_layers_001.png
diff --git a/dev/_images/sphx_glr_layers_thumb.png b/dev/_images/sphx_glr_layers_thumb.png
diff --git a/dev/_images/sphx_glr_mixed-dimensions-labels_001.png b/dev/_images/sphx_glr_mixed-dimensions-labels_001.png
diff --git a/dev/_images/sphx_glr_mixed-dimensions-labels_thumb.png b/dev/_images/sphx_glr_mixed-dimensions-labels_thumb.png
diff --git a/dev/_images/sphx_glr_mouse_drag_callback_001.png b/dev/_images/sphx_glr_mouse_drag_callback_001.png
diff --git a/dev/_images/sphx_glr_mouse_drag_callback_thumb.png b/dev/_images/sphx_glr_mouse_drag_callback_thumb.png
diff --git a/dev/_images/sphx_glr_nD_image_001.png b/dev/_images/sphx_glr_nD_image_001.png
diff --git a/dev/_images/sphx_glr_nD_image_thumb.png b/dev/_images/sphx_glr_nD_image_thumb.png
diff --git a/dev/_images/sphx_glr_nD_labels_001.png b/dev/_images/sphx_glr_nD_labels_001.png
diff --git a/dev/_images/sphx_glr_nD_labels_thumb.png b/dev/_images/sphx_glr_nD_labels_thumb.png
diff --git a/dev/_images/sphx_glr_nD_points_001.png b/dev/_images/sphx_glr_nD_points_001.png
diff --git a/dev/_images/sphx_glr_nD_points_thumb.png b/dev/_images/sphx_glr_nD_points_thumb.png
diff --git a/dev/_images/sphx_glr_nD_points_with_features_001.png b/dev/_images/sphx_glr_nD_points_with_features_001.png
diff --git a/dev/_images/sphx_glr_nD_points_with_features_thumb.png b/dev/_images/sphx_glr_nD_points_with_features_thumb.png
diff --git a/dev/_images/sphx_glr_nD_shapes_001.png b/dev/_images/sphx_glr_nD_shapes_001.png
diff --git a/dev/_images/sphx_glr_nD_shapes_thumb.png b/dev/_images/sphx_glr_nD_shapes_thumb.png
diff --git a/dev/_images/sphx_glr_nD_shapes_with_text_001.png b/dev/_images/sphx_glr_nD_shapes_with_text_001.png
diff --git a/dev/_images/sphx_glr_nD_shapes_with_text_thumb.png b/dev/_images/sphx_glr_nD_shapes_with_text_thumb.png
diff --git a/dev/_images/sphx_glr_nD_vectors_001.png b/dev/_images/sphx_glr_nD_vectors_001.png
diff --git a/dev/_images/sphx_glr_nD_vectors_thumb.png b/dev/_images/sphx_glr_nD_vectors_thumb.png
diff --git a/dev/_images/sphx_glr_paint-nd_001.png b/dev/_images/sphx_glr_paint-nd_001.png
diff --git a/dev/_images/sphx_glr_paint-nd_thumb.png b/dev/_images/sphx_glr_paint-nd_thumb.png
diff --git a/dev/_images/sphx_glr_points-over-time_001.png b/dev/_images/sphx_glr_points-over-time_001.png
diff --git a/dev/_images/sphx_glr_points-over-time_thumb.png b/dev/_images/sphx_glr_points-over-time_thumb.png
diff --git a/dev/_images/sphx_glr_spherical_points_001.png b/dev/_images/sphx_glr_spherical_points_001.png
diff --git a/dev/_images/sphx_glr_spherical_points_thumb.png b/dev/_images/sphx_glr_spherical_points_thumb.png
diff --git a/dev/_images/sphx_glr_swap_dims_001.png b/dev/_images/sphx_glr_swap_dims_001.png
diff --git a/dev/_images/sphx_glr_swap_dims_thumb.png b/dev/_images/sphx_glr_swap_dims_thumb.png
diff --git a/dev/_images/sphx_glr_to_screenshot_001.png b/dev/_images/sphx_glr_to_screenshot_001.png
diff --git a/dev/_images/sphx_glr_to_screenshot_thumb.png b/dev/_images/sphx_glr_to_screenshot_thumb.png
diff --git a/dev/_sources/guides/app_model.md → ...rces/developers/architecture/app_model.md b/dev/_sources/guides/app_model.md → ...rces/developers/architecture/app_model.md
@@ -1,3 +1,5 @@
+(app-model)=
+
 # napari's application model
 
 ```{important}
@@ -260,7 +262,7 @@ Some Points
 
 The fact that `injected_func` may now be called without parameters allows it to
 be used easily as a command in a menu, or bound to a keybinding.  It is up to
-`napari` to determine what providers it will make available, and what type hints
+napari to determine what providers it will make available, and what type hints
 plugins/users may use to request dependencies.
 
 ## Motivation & Future Vision

diff --git a/dev/_sources/developers/architecture/dir_organization.md b/dev/_sources/developers/architecture/dir_organization.md
@@ -0,0 +1,96 @@
+(napari-directory-organization)=
+
+# napari directory organization
+
+The majority of the napari code lives in
+[`napari/`](https://github.com/napari/napari/tree/main/napari). The main
+folders are:
+
+```
+napari/
+├── _app_model/
+├── _qt/
+├── _tests/
+├── _vendor/
+├── _vispy/
+├── benchmarks/
+├── components/
+├── errors/
+├── layers/
+├── plugins/
+├── qt/
+├── resources/
+├── settings/
+└── utils/
+```
+
+* Folders beginning with `_` represent private code, that is not part of the public
+  API.
+  * Similarly, files beginning with `_` within folders are not considered part
+    of the public API.
+* Information on organization of test files can be found in [](test-organization).
+
+Notable folders in the root directory:
+
+* [`examples/`](https://github.com/napari/napari/tree/main/examples) folder
+  contains the source [examples gallery](https://napari.org/gallery) files.
+  The code in these files are executed and outputs captured when building the gallery.
+  See [](docs_contributing_guide) for details on napari` documentation.
+* [`.github/`](https://github.com/napari/napari/tree/main/.github) contains
+  our [GitHub Actions](https://docs.github.com/en/actions)
+  [continuous integration (CI)](https://en.wikipedia.org/wiki/Continuous_integration)
+  workflows. The majority of our CI workflows are run using GitHub Actions.
+
+## Qt separation
+
+[Qt](https://doc.qt.io/) is a C++ framework to build graphical user interfaces (GUIs)
+that is available in Python from a number of libraries, such as
+[PyQt5](https://www.riverbankcomputing.com/static/Docs/PyQt5/).
+Napari uses Qt to build its GUI, but we want to remain flexible to offer other GUI
+frameworks (such as a web-based GUI) in the future. Therefore,
+we try to confine code that directly imports Qt (currently the only supported GUI
+backend) to the folders `_qt/` and `_vispy/`. Sometimes this means that
+code needs to be split in order to place the Qt part inside `_qt/`. For example,
+some of the `Action` menu items in the **View** menu require Qt. These live in
+`napari/_qt/_qapp_model/qactions/_view.py` while the `Action` menu items that
+do not require Qt live in `napari/_app_model/actions/_view_actions.py`.
+Notice how the folder structure inside `_qt/` tries to mirror the structure of
+`napari/`, with 'q' being added to the start of folders and files (e.g., `_app_model`
+is named `_qapp_model` inside `_qt/`).
+
+## Folder summary
+
+* `_app_model/` - the code here relates to [app-model](app-model) and defines
+  menu item `Actions`, providers and processors and context keys. Any Qt parts
+  live in `napari/_qt/_qapp_model`.
+* `_qt/` - here we define all the visual elements of napari including layer controls,
+  menus, vispy canvas and dialogs. Any code that directly imports GUI also lives here.
+* `_vendor/` - code vendored from other projects. This may have been because we only
+  wanted to use a small part of a library and did not want to add another dependency.
+  We may also have wanted to use changes in an upstream package before it has
+  been released.
+* `_vispy/` - code here defines how layers and their metadata are displayed on the
+  canvas (the canvas is a vispy object onto which you can draw 'visuals').
+* `benchmarks/` - benchmarking code, mostly for checking the performance of layers.
+  It is is executed in CI and is run every Sunday. See
+  [`.github/workflows/benchmarks.yml`](https://github.com/napari/napari/tree/main/.github/workflows/benchmarks.yml)
+  for CI workflow details. The benchmarks can also be run locally.
+* `components/` - code that defines all components of the napari viewer, including the
+  layerlist, dimensions and camera.
+* `errors/` - custom napari errors (that inherit from built-in errors) are defined
+  here. Currently we only have reader related custom errors.
+* `layers/` - defines the classes, utilities, keybinding and mouse binding for
+  each [layer type](using-layers).
+* `plugins/` - the code here deals with registering, activating and deactivating
+  plugins. It also handles ingesting plugin contributions to achieve the desired
+  effect in viewer (e.g., widget contributions should add a widget to the napari
+  viewer).
+  Code that defines the specification for each plugin contribution, the plugin
+  manifest and defines plugin manager (a class that manages the currently installed
+  plugins and their contribitions) lives in its own repo:
+  [`npe2`](https://github.com/napari/npe2).
+* `qt/` - public utilities that directly rely on Qt, such as the progress bar
+  and the [thread worker](multithreading-in-napari).
+* `resources/` - stores icons for buttons in the viewer.
+* `settings/` - code that defines and manages napari user settings.
+* `utils/` - commonly used classes and functions imported in variety of places.
diff --git a/dev/_sources/developers/architecture/index.md b/dev/_sources/developers/architecture/index.md
@@ -0,0 +1,13 @@
+(architecture-index)=
+
+# napari architecture guide
+
+These pages provide a guide to the napari software architecture
+and is aimed at contributors who would like a better understanding of the napari
+code base. For advanced napari usage documentation, see [](explanations).
+
+- [](napari-directory-organization): Guide to the napari directory organization.
+- [](napari-model-event): Explains napari python models and how they are
+  connected to Qt classes and Vispy classes.
+- [](app-model): Explains the napari application model, a declarative schema for
+  keeping track of commands, menus and keybindings of the napari GUI.
diff --git a/dev/_sources/guides/napari_models.md → .../developers/architecture/napari_models.md b/dev/_sources/guides/napari_models.md → .../developers/architecture/napari_models.md
@@ -1,14 +1,16 @@
-# Napari models and events
+(napari-model-event)=
+
+# napari models and events
 
 This document explains the links between the three main components of napari:
-python models, Qt classes and vispy classes, with code examples. This knowledge
+Python models, Qt classes and vispy classes, with code examples. This knowledge
 is not necessary to use napari and is more aimed at developers interested in
 understanding the inner workings of napari. This document assumes you're
 familiar with basic usage of napari.
 
 The three main components:
 
-* python models describing components in the napari application - these are able
+* Python models describing components in the napari application - these are able
   to operate without the GUI interface and do not have any dependencies on user
   interface classes
     * this code lives in `napari/components` (utility objects) and
@@ -19,19 +21,19 @@ The three main components:
 * vispy classes that handle rendering
     * the code for this is private and lives in `napari/_vispy`
 
-The separation of the python models from viewer GUI code allows:
+The separation of the Python models from viewer GUI code allows:
 
 * analysis plugins to be developed without worrying about the GUI
   aspect
 * napari to have the option to move away from the rendering backend currently
   used
 * tests to be easily run headlessly
-* the python models to be run headlessly (see
+* the Python models to be run headlessly (see
   [Running napari headlessly](../howtos/headless) for more)
 
 ## Python models and events
 
-Commonly, python models in napari are classes that store information about their
+Commonly, Python models in napari are classes that store information about their
 state as an attribute and are the "source of ground truth". When these
 attributes are changed an "event" needs to be emitted such that relevant
 observers of the model (such as other classes) can take the appropriate
@@ -174,7 +176,7 @@ the Python model, which gets updated directly when a field is changed via the
 GUI.
 
 For example, below is a code snippet showing the `QtDims` class instantiating
-with a reference to the python class `Dims` and registering the callback
+with a reference to the Python class `Dims` and registering the callback
 `_update_display`:
 
 ```python

diff --git a/dev/_sources/developers/testing.md b/dev/_sources/developers/testing.md
@@ -26,6 +26,8 @@ Unit tests are at the base of the pyramid because they are the easiest to write
 the quickest to run. The time and effort to implement and maintain tests increases
 from unit tests to integration and functional tests.
 
+(test-organization)=
+
 ## Test organization
 
 All of `napari` tests are located in folders named `_tests`. We keep our unit

diff --git a/dev/_sources/gallery/action_manager.rst b/dev/_sources/gallery/action_manager.rst
@@ -42,9 +42,9 @@ Action manager
     application, not part of the napari viewer model. If your use case
     requires access to qt_viewer, please open an issue to discuss.
       layer_buttons = viewer.window.qt_viewer.layerButtons
-    calling <function register_action at 0x7fc5280f70a0>
-    calling <function bind_shortcut at 0x7fc5280f7130>
-    calling <function bind_button at 0x7fc5280f7250>
+    calling <function bind_button at 0x7f8136761ea0>
+    calling <function register_action at 0x7f8136760dc0>
+    calling <function bind_shortcut at 0x7f8136761ab0>