From 0ccc249499e7682fd52094e284c41bdbd6a43ad7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 5 Dec 2024 20:33:13 -0300 Subject: [PATCH 1/4] Add troubleshooting page --- docs/_toc.yml | 1 + docs/troubleshooting.md | 43 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/troubleshooting.md diff --git a/docs/_toc.yml b/docs/_toc.yml index def47b47..2b52c1bc 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -74,6 +74,7 @@ subtrees: - file: further-resources/glossary - file: further-resources/napari-workshops - file: further-resources/sample_data + - file: troubleshooting - file: gallery - file: release/index subtrees: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..f147c33e --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,43 @@ +# Troubleshooting + +This page collects a few known issues and solutions for common problems that users might encounter when using napari. +If you are facing an error that is not covered by this page, please +[open an issue](https://github.com/napari/napari/issues/new) in the napari repository. + +## Known issues + +### Resetting preferences and settings + +Changing napari versions—or conda envs with different napari versions—can cause issues with settings. These issues can +be solved by resetting the settings back to default using the terminal command: + +```python +napari --reset +``` + +### torch + rosetta + napari crashes Python + +In some cases, when using napari on Mac M1 using Rosetta you may experience crashing when adding layers or using a script. +If you observe this, you can try to run napari using the native arm64 Python interpreter (see [napari#7259](https://github.com/napari/napari/issues/7259). + +### "module napari has no attribute Viewer" + +This may happen when doing an editable install on top of a normal one, or when you have a local file called `napari.py`. + +To fix this, either rename the file or remove all previous napari versions in your environment before installing the editable version. + +### My image renders as all black/all white + +This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking "contras limits", then clicking the "Reset" button in the dialog shown. + +### napari + numba combination doesn't work on admin installs of Windows + +If you have trouble using napari together with numba on Windows, try setting `NUMBA_CACHE_DIR` to an user-accessible location. + +See [napari#7288](https://github.com/napari/napari/issues/7288). + +## FAQ + +### How do I use napari in a remote Jupyter env? + +napari is a native Qt app so it's not possible to do this directly within a Jupyter notebook or JupyterLab tab. However, we are working on documenting options for this workflow. From 310d4586d52914e5c1c1b6fabc3c63d4c2b931c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Thu, 5 Dec 2024 20:59:37 -0300 Subject: [PATCH 2/4] Typo --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f147c33e..045117d6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -28,7 +28,7 @@ To fix this, either rename the file or remove all previous napari versions in yo ### My image renders as all black/all white -This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking "contras limits", then clicking the "Reset" button in the dialog shown. +This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking "contrast limits", then clicking the "Reset" button in the dialog shown. ### napari + numba combination doesn't work on admin installs of Windows From 4cc794dd7dc28998556b600afa5c9c7da373d86e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Tue, 17 Dec 2024 16:39:18 -0300 Subject: [PATCH 3/4] Addressing review comments --- docs/troubleshooting.md | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 045117d6..e33c318b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -1,15 +1,19 @@ # Troubleshooting This page collects a few known issues and solutions for common problems that users might encounter when using napari. -If you are facing an error that is not covered by this page, please -[open an issue](https://github.com/napari/napari/issues/new) in the napari repository. +If you are facing an error that is not covered by this page, please check existing issues on the +[napari repository](https://github.com/napari/napari/issues). If you can't find what you are looking for, +please open a new issue. ## Known issues ### Resetting preferences and settings -Changing napari versions—or conda envs with different napari versions—can cause issues with settings. These issues can -be solved by resetting the settings back to default using the terminal command: +Changing napari versions—updating or downgrading—within an environment can cause issues with settings. These issues can +manifest as napari failing to start. + +Likewise, issues with napari on multiple monitors or with window sizes are also due to settings. These issues can +frequently be solved by resetting the settings back to default using the terminal command: ```python napari --reset @@ -18,7 +22,7 @@ napari --reset ### torch + rosetta + napari crashes Python In some cases, when using napari on Mac M1 using Rosetta you may experience crashing when adding layers or using a script. -If you observe this, you can try to run napari using the native arm64 Python interpreter (see [napari#7259](https://github.com/napari/napari/issues/7259). +If you observe this, you should run napari using the native arm64 Python interpreter (see [napari#7259](https://github.com/napari/napari/issues/7259). ### "module napari has no attribute Viewer" @@ -28,16 +32,23 @@ To fix this, either rename the file or remove all previous napari versions in yo ### My image renders as all black/all white -This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking "contrast limits", then clicking the "Reset" button in the dialog shown. +This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking +"contrast limits", then clicking the "Reset" button in the dialog shown. -### napari + numba combination doesn't work on admin installs of Windows +The contrast limits are the minimum and maximum values displayed by the layer. Any value under the smaller contrast +limit will appear as black, while any value above the larger limit will appear as white. Additionally, when all the +values are near the bottom of the range, the image can still appear black even if there are some very dark but not quite +black pixels there. -If you have trouble using napari together with numba on Windows, try setting `NUMBA_CACHE_DIR` to an user-accessible location. +You can reset the contrast limits by clicking the Auto-Contrast: "Once" button, or, if that fails, right clicking on the +contrast limits to do manual adjustment, including directly editing the numbers shown. When in doubt, you can hover over +the canvas with your image layer selected, and check the status message as you move the mouse around. That will give you +an idea of the range and variability of the data in your layer, helping you set meaningful contrast limits. -See [napari#7288](https://github.com/napari/napari/issues/7288). +### PermissionError when trying to launch napari on Windows -## FAQ +If you have a PermissionError when trying to launch napari on Windows, it could be due to how numba deals with +permissions. Try setting `NUMBA_CACHE_DIR` to an user-accessible location. -### How do I use napari in a remote Jupyter env? +See [napari#7288](https://github.com/napari/napari/issues/7288). -napari is a native Qt app so it's not possible to do this directly within a Jupyter notebook or JupyterLab tab. However, we are working on documenting options for this workflow. From c281d37b4c422841f1ec0ec18893a5300055c7cd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Wed, 18 Dec 2024 17:56:33 -0300 Subject: [PATCH 4/4] Add link to contrast limits docs --- docs/howtos/layers/image.md | 1 + docs/troubleshooting.md | 12 ++---------- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md index ffc43cc9..41c6c38d 100644 --- a/docs/howtos/layers/image.md +++ b/docs/howtos/layers/image.md @@ -349,6 +349,7 @@ we had passed only the colormap it would have been given a default name. The named colormap now appears in the dropdown alongside a thumbnail of the full range of the colormap. +(contrast-limits)= ## Adjusting contrast limits Each image layer gets mapped through its colormap according to values called diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e33c318b..a0aac418 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -33,17 +33,9 @@ To fix this, either rename the file or remove all previous napari versions in yo ### My image renders as all black/all white This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking -"contrast limits", then clicking the "Reset" button in the dialog shown. +"contrast limits", then clicking the "Reset" button in the advanced contrast limits widget shown. -The contrast limits are the minimum and maximum values displayed by the layer. Any value under the smaller contrast -limit will appear as black, while any value above the larger limit will appear as white. Additionally, when all the -values are near the bottom of the range, the image can still appear black even if there are some very dark but not quite -black pixels there. - -You can reset the contrast limits by clicking the Auto-Contrast: "Once" button, or, if that fails, right clicking on the -contrast limits to do manual adjustment, including directly editing the numbers shown. When in doubt, you can hover over -the canvas with your image layer selected, and check the status message as you move the mouse around. That will give you -an idea of the range and variability of the data in your layer, helping you set meaningful contrast limits. +See [](contrast-limits) for more information on contrast limits. ### PermissionError when trying to launch napari on Windows