jupyter_firefly_extensions

JupyterLab扩展，用于使用Firefly渲染FITS文件和显示表格、图像和图表。

概述

这些扩展向JupyterLab添加以下功能

• 从文件浏览器打开FITS文件，并在标签页中查看。
• 在标签页中启动完整的Firefly查看器（通过启动器或命令面板）。
• 在笔记本中使用FireflyClient启动Firefly标签页，并使用FireflyClient Python API向其发送数据（表格、图像、图表）。

先决条件

• JupyterLab ^4.0.0 - 这些扩展将在其中运行。如果您使用的是JupyterLab<4，请检查过去版本。

• firefly_client ^2.1.1 - 可以使用pip install firefly-client进行安装。

• Firefly服务器 - 您可以通过从https://hub.docker.com/r/ipac/firefly获取的Firefly Docker镜像本地运行它。

• astropy ^3.0.0 - （可选）用于示例笔记本的便利性。

• nodejs ^18.0.0 - 仅在执行开发安装时需要。

如果您已安装conda并正在设置新环境，可以使用以下命令：

conda create -n jl-ff-ext -c conda-forge python jupyterlab firefly-client astropy
conda activate jl-ff-ext

非常重要：首先设置Firefly URL - 3种方法

在运行jupyter_firefly_extensions之前，您必须提供指向Firefly服务器的URL，以下任一方法均可：

• 将以下行添加到您的~/.jupyter/jupyter_config.py中

  c.Firefly.url = 'http://localhost:8080/firefly'
  

或者

• 将以下行添加到您的~/.jupyter/jupyter_config.json中的根对象下。

  "Firefly": {
    "url": "http://localhost:8080/firefly"
  }
  

或者

• 使用启动jupyter lab的shell中的环境变量。

  在bash中

  export FIREFLY_URL=http://localhost:8080/firefly
  

  在tcsh中

  setenv FIREFLY_URL http://localhost:8080/firefly
  

注意：如果您的配置已按上述方式设置在多个地方，则优先级顺序为：环境变量 > jupyter_config.json > jupyter_config.py

安装

在满足先决条件的环境中，

pip install jupyter-firefly-extensions

打开JupyterLab（使用jupyter lab）以开始使用这些扩展 - 请参阅示例了解如何使用。

开发安装

首先

如果正在开发firefly_client，请确保已克隆firefly_client仓库（https://github.com/Caltech-IPAC/firefly_client），然后在目录内执行pip install -e .。

请确保您已安装nodejs >=18.0.0，或虚拟环境中。它是构建TS/JS源所必需的。在conda环境中，您可以使用conda install nodejs进行安装。

然后

git clone https://github.com/Caltech-IPAC/jupyter_firefly_extensions
cd jupyter_firefly_extensions

# Install package in development mode (changes in python source will reflect automatically)
pip install -e .

# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite

# Enable the server extension
jupyter server extension enable jupyter_firefly_extensions

# Build extension TS/JS source
jlpm run build

# Alternatively, watch TS/JS source so that changes in it reflect automatically on lab
jlpm watch

有用的命令

• jupyter server extension list - 显示服务器扩展列表

• jupyter lab extension list - 显示lab扩展列表

• jupyter lab - 运行jupyter lab

• jlpm <任何yarn命令> - JupyterLab提供的锁定版本yarn

  注意：避免使用yarn <yarn命令>，因为它可能会使用全局安装的yarn，其版本可能与jlpm不同（例如，v1而不是v3），这可能导致package.json安装中断。

要删除扩展

pip uninstall jupyter-firefly-extensions

示例

examples目录包含几个示例笔记本，用于演示扩展功能。当使用示例时，应复制目录及其内容到其他位置，以避免jupyter lab重建。

• slate-demo-explicit.ipynb、slate-demo-explicit2.ipynb - 使用FireflyClient Python API演示打开Firefly标签页并向其发送数据
• 其他笔记本演示了不再受支持的widget功能，因此它们将无法工作。

除此之外，您还可以使用此扩展来显示fits图像。在jupyter lab的文件浏览器中，只需单击.fits文件即可在新标签页中显示图像。

故障排除

• 如果您使用的是本地Firefly服务器并且遇到图像渲染问题，请检查控制台以查找有关无法加载'firefly-thread.worker.js'的错误消息。如果是这种情况，您可以使用gradle clean清理现有的Firefly构建，然后在开发环境中（而不是本地环境，即默认环境）构建和部署它，使用gradle -Penv=dev firefly:bAD。然后，重新加载Jupyter Lab浏览器标签页（并清空缓存）。您不应再看到该控制台错误，并且图像应正确渲染。

• 如果jlpm run build（或jlpm watch）由于缺少/不兼容的包而失败，请运行jlpm（相当于yarn）来根据package.json更新/解决依赖项。如果它更新了yarn.lock，请确保提交并推送它。