# Getting Started
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
# Welcome to the Open Source DIY Hyperspectral Imager Library
This Python library is licensed under the [Apache v2
License](https://www.apache.org/licenses/LICENSE-2.0). The documentation
is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by/3.0/au/">Creative
Commons Attribution 3.0 Australia License</a>.
Documentation can be found here: <https://openhsi.github.io/openhsi/>.
## Install
`pip install openhsi`
or
`conda install -c conda-forge openhsi`
The source code can be found on
[GitHub](https://github.com/openhsi/openhsi). To install a development
version see [Contributing](contributing.html).
## Requirements
- Python 3.7+
Depending on your camera sensor, install:
- Ximea SDK (See https://www.ximea.com/support/wiki/apis/Python)
- FLIR Spinnaker SDK with the python package (See
https://www.flir.com/products/spinnaker-sdk/)
- LUCID SDK (See https://thinklucid.com/downloads-hub/)
> [!NOTE]
>
> A descriptive installation guide on Linux platforms can be found at
> https://openhsi.github.io/openhsi/tutorial_installing_linux.html
## Development and Contributions
This whole software library, testing suite, documentation website, and
PyPI/conda package was developed in Jupyter Notebooks using
[nbdev](https://nbdev.fast.ai/).
> [!NOTE]
>
> We have moved to `nbdev2` which uses Quarto to generate this
> documentation site.
<!-- :::{.callout-important}
This library is under active development and new features are still being added.
::: -->
## Citation
If OpenHSI has been useful for your research, please acknowledge the
project in your academic publication. The OpenHSI paper has been
published in MDPI Remote Sensing and can be accessed at
<https://doi.org/10.3390/rs14092244>.
@article{mao2022openhsi,
title={OpenHSI: A Complete Open-Source Hyperspectral Imaging Solution for Everyone},
author={Mao, Yiwei and Betters, Christopher H and Evans, Bradley and Artlett, Christopher P and Leon-Saval, Sergio G and Garske, Samuel and Cairns, Iver H and Cocks, Terry and Winter, Robert and Dell, Timothy},
journal={Remote Sensing},
volume={14},
number={9},
pages={2244},
year={2022},
publisher={MDPI}
}
## How to use
> [!TIP]
>
> For more detailed instructions, please see the tutorials in the
> sidebar of the documentation site.
### Taking a single hyperspectral datacube
The example shown here uses a *simulated* camera for testing purposes.
Replace `SimulatedCamera` with the appropriate Python class for your own
camera to work with real hardware. For example, use `LucidCamera`
imported from `openhsi.cameras` inplace of `SimulatedCamera`.
``` python
from openhsi.capture import *
with SimulatedCamera(img_path="assets/rocky_beach.png", n_lines=1024, processing_lvl = 3,
json_path="assets/cam_settings.json",pkl_path="assets/cam_calibration.pkl") as cam:
cam.collect()
fig = cam.show(plot_lib="matplotlib",robust=True)
```
The RGB representation is made using selected bands for red, green, and
blue. These bands can be customised along with options for displaying
the image without outliers affecting the colour scale/contrast. The
example flag used here is `robust` which takes the 2-98% percentile.
There is also the `hist_eq` flag which performs histogram equalisation.
If none of these flags are set, then the colour scale uses the min and
max value.
``` python
fig.opts(fig_inches=7,title="simulated hyperspectral datacube")
```
> [!TIP]
>
> For more information on how to use this library, check out our [Quick
> Start Guide](https://openhsi.github.io/openhsi/tutorial_camera.html).
## Hardware cameras
The hardware consists of a collimator tube with a slit (1) mounted in a
3D printed housing (2). A diffraction grating (3) is used to split the
incoming light into its component colours to be detected on the camera
sensor (4).
We have the following implementations in `openhsi.cameras`:
- `WebCamera`
- `XimeaCamera`
- `LucidCamera`
- `FlirCamera`
These all have the same interface so in principle, these OpenHSI cameras
can be used interchangeably as long as you have the right calibration
files.
## Frequently Asked Questions
**I’m having trouble with the software install. Do you have a guide?**
Check out our [Linux Installation
Guide](https://openhsi.github.io/openhsi/tutorial_installing_linux.html)
and [Windows Installation
Guide](https://openhsi.github.io/openhsi/tutorial_installing_windows.html).
**Where can I get a quick overview of what `openhsi` can do?**
Our [Quick Start
Guide](https://openhsi.github.io/openhsi/tutorial_camera.html) is the
best place to start. The sidebar also includes documentation for each
software module in more detail.
**The OpenHSI camera is a pushbroom sensor and requires motion to scan a
2D space. What kind of motion should I apply?**
Any motion that allows you to scan a 2D space is okay. This can be from
translating the camera is space or from applying a rotation. (or both
translation and rotation) The developers of `openhsi` has flown the
OpenHSI camera on a drone which sweeps across an area of interest in
multiple overlapping swaths. You can fly this camera on other platforms,
vehicles, etc…
**How fast should I move the camera?**
It’ll depend on what your case is. This answer assumes you want square
pixels. Assuming the cross-track (scan line) spatial resolution is 0.42
mrad in the field of view, and your altitude is 120 m, the ground sample
distance is:
GSD $\approx$ 0.00042 $\times$ 120 (using the small angle approximation)
= 5 cm
Assuming your frame rate is 98 FPS at your desired processing level, and
you want to get square pixels, you want to be flying at speed
$v$ = 98 $\times$ 0.05 = 4.9 m/s
If you fly faster/slower than this, your datacube will appear to be
stretched spatially.
Raw data
{
"_id": null,
"home_page": "https://github.com/openhsi/openhsi",
"name": "openhsi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Open Hyperspectral Imager",
"author": "Yiwei Mao, et al.",
"author_email": "yiwei.mao@sydney.edu.au",
"download_url": "https://files.pythonhosted.org/packages/47/b2/edab5d9e4575b274b4071e88794d4ce159ced4e09f9ed8b18654158d202f/openhsi-0.3.1.tar.gz",
"platform": null,
"description": "# Getting Started\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n# Welcome to the Open Source DIY Hyperspectral Imager Library\n\n\n\nThis Python library is licensed under the [Apache v2\nLicense](https://www.apache.org/licenses/LICENSE-2.0). The documentation\nis licensed under a\n<a rel=\"license\" href=\"http://creativecommons.org/licenses/by/3.0/au/\">Creative\nCommons Attribution 3.0 Australia License</a>.\n\nDocumentation can be found here: <https://openhsi.github.io/openhsi/>.\n\n## Install\n\n`pip install openhsi`\n\nor\n\n`conda install -c conda-forge openhsi`\n\nThe source code can be found on\n[GitHub](https://github.com/openhsi/openhsi). To install a development\nversion see [Contributing](contributing.html).\n\n## Requirements\n\n- Python 3.7+\n\nDepending on your camera sensor, install:\n\n- Ximea SDK (See https://www.ximea.com/support/wiki/apis/Python)\n\n- FLIR Spinnaker SDK with the python package (See\n https://www.flir.com/products/spinnaker-sdk/)\n\n- LUCID SDK (See https://thinklucid.com/downloads-hub/)\n\n> [!NOTE]\n>\n> A descriptive installation guide on Linux platforms can be found at\n> https://openhsi.github.io/openhsi/tutorial_installing_linux.html\n\n## Development and Contributions\n\nThis whole software library, testing suite, documentation website, and\nPyPI/conda package was developed in Jupyter Notebooks using\n[nbdev](https://nbdev.fast.ai/).\n\n> [!NOTE]\n>\n> We have moved to `nbdev2` which uses Quarto to generate this\n> documentation site.\n\n<!-- :::{.callout-important}\n This library is under active development and new features are still being added.\n ::: -->\n\n## Citation\n\nIf OpenHSI has been useful for your research, please acknowledge the\nproject in your academic publication. The OpenHSI paper has been\npublished in MDPI Remote Sensing and can be accessed at\n<https://doi.org/10.3390/rs14092244>.\n\n @article{mao2022openhsi,\n title={OpenHSI: A Complete Open-Source Hyperspectral Imaging Solution for Everyone},\n author={Mao, Yiwei and Betters, Christopher H and Evans, Bradley and Artlett, Christopher P and Leon-Saval, Sergio G and Garske, Samuel and Cairns, Iver H and Cocks, Terry and Winter, Robert and Dell, Timothy},\n journal={Remote Sensing},\n volume={14},\n number={9},\n pages={2244},\n year={2022},\n publisher={MDPI}\n }\n\n## How to use\n\n> [!TIP]\n>\n> For more detailed instructions, please see the tutorials in the\n> sidebar of the documentation site.\n\n### Taking a single hyperspectral datacube\n\nThe example shown here uses a *simulated* camera for testing purposes.\nReplace `SimulatedCamera` with the appropriate Python class for your own\ncamera to work with real hardware. For example, use `LucidCamera`\nimported from `openhsi.cameras` inplace of `SimulatedCamera`.\n\n``` python\nfrom openhsi.capture import *\n\nwith SimulatedCamera(img_path=\"assets/rocky_beach.png\", n_lines=1024, processing_lvl = 3,\n json_path=\"assets/cam_settings.json\",pkl_path=\"assets/cam_calibration.pkl\") as cam:\n cam.collect()\n fig = cam.show(plot_lib=\"matplotlib\",robust=True)\n```\n\nThe RGB representation is made using selected bands for red, green, and\nblue. These bands can be customised along with options for displaying\nthe image without outliers affecting the colour scale/contrast. The\nexample flag used here is `robust` which takes the 2-98% percentile.\nThere is also the `hist_eq` flag which performs histogram equalisation.\nIf none of these flags are set, then the colour scale uses the min and\nmax value.\n\n``` python\nfig.opts(fig_inches=7,title=\"simulated hyperspectral datacube\")\n```\n\n> [!TIP]\n>\n> For more information on how to use this library, check out our [Quick\n> Start Guide](https://openhsi.github.io/openhsi/tutorial_camera.html).\n\n## Hardware cameras\n\n![](assets/openhsi_cam.png \"The hardware consists of a collimator tube with a slit (1) mounted in a 3D printed housing (2). A diffraction grating (3) is used to split the incoming light into its component colours to be detected on the camera sensor (4).\")\n\nThe hardware consists of a collimator tube with a slit (1) mounted in a\n3D printed housing (2). A diffraction grating (3) is used to split the\nincoming light into its component colours to be detected on the camera\nsensor (4).\n\nWe have the following implementations in `openhsi.cameras`:\n\n- `WebCamera`\n- `XimeaCamera`\n- `LucidCamera`\n- `FlirCamera`\n\nThese all have the same interface so in principle, these OpenHSI cameras\ncan be used interchangeably as long as you have the right calibration\nfiles.\n\n## Frequently Asked Questions\n\n**I\u2019m having trouble with the software install. Do you have a guide?**\n\nCheck out our [Linux Installation\nGuide](https://openhsi.github.io/openhsi/tutorial_installing_linux.html)\nand [Windows Installation\nGuide](https://openhsi.github.io/openhsi/tutorial_installing_windows.html).\n\n**Where can I get a quick overview of what `openhsi` can do?**\n\nOur [Quick Start\nGuide](https://openhsi.github.io/openhsi/tutorial_camera.html) is the\nbest place to start. The sidebar also includes documentation for each\nsoftware module in more detail.\n\n**The OpenHSI camera is a pushbroom sensor and requires motion to scan a\n2D space. What kind of motion should I apply?**\n\nAny motion that allows you to scan a 2D space is okay. This can be from\ntranslating the camera is space or from applying a rotation. (or both\ntranslation and rotation) The developers of `openhsi` has flown the\nOpenHSI camera on a drone which sweeps across an area of interest in\nmultiple overlapping swaths. You can fly this camera on other platforms,\nvehicles, etc\u2026\n\n**How fast should I move the camera?**\n\nIt\u2019ll depend on what your case is. This answer assumes you want square\npixels. Assuming the cross-track (scan line) spatial resolution is 0.42\nmrad in the field of view, and your altitude is 120 m, the ground sample\ndistance is:\n\nGSD $\\approx$ 0.00042 $\\times$ 120 (using the small angle approximation)\n= 5 cm\n\nAssuming your frame rate is 98 FPS at your desired processing level, and\nyou want to get square pixels, you want to be flying at speed\n\n$v$ = 98 $\\times$ 0.05 = 4.9 m/s\n\nIf you fly faster/slower than this, your datacube will appear to be\nstretched spatially.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Library to calibrate, trigger and capture data cubes for the open source hyperspectral camera.",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/openhsi/openhsi"
},
"split_keywords": [
"open",
"hyperspectral",
"imager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f13106532e480bc0f449f86e556d5f0a5810520c08ac6386ae29783af100a4d",
"md5": "02bbbd30fd17c06bb6fb4e69446ee1c2",
"sha256": "e6814dc27f59454d7e6e14a4686fceb90ae332c651353f3aeebf3ecb7f12db31"
},
"downloads": -1,
"filename": "openhsi-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02bbbd30fd17c06bb6fb4e69446ee1c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 62003,
"upload_time": "2024-03-13T06:39:35",
"upload_time_iso_8601": "2024-03-13T06:39:35.836597Z",
"url": "https://files.pythonhosted.org/packages/2f/13/106532e480bc0f449f86e556d5f0a5810520c08ac6386ae29783af100a4d/openhsi-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "47b2edab5d9e4575b274b4071e88794d4ce159ced4e09f9ed8b18654158d202f",
"md5": "7f5e3a2e048e61d4750baad48a01feaa",
"sha256": "33f9761eb035e7d634fa4f4b830cd058a84b452135b0b9cc961b8488f6f70cb9"
},
"downloads": -1,
"filename": "openhsi-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "7f5e3a2e048e61d4750baad48a01feaa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 59621,
"upload_time": "2024-03-13T06:39:38",
"upload_time_iso_8601": "2024-03-13T06:39:38.206380Z",
"url": "https://files.pythonhosted.org/packages/47/b2/edab5d9e4575b274b4071e88794d4ce159ced4e09f9ed8b18654158d202f/openhsi-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-13 06:39:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openhsi",
"github_project": "openhsi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "openhsi"
}
JSON
