| Name | sonarlight JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | |
| Summary | sonarlight |
| upload_time | 2023-10-30 10:28:36 |
| maintainer | |
| docs_url | None |
| author | Kenneth Thorø Martinsen |
| requires_python | |
| license | |
| keywords |
python
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sonarlight
The `sonarlight` package provides tools for working with Lowrance sonar data in the `.sl2` and `.sl3` formats. The package includes the `Sonar` class for reading and parsing these files, as well as methods for extracting various types of information from the data.
Project home is [https://github.com/KennethTM/sonarlight](https://github.com/KennethTM/sonarlight).
## Installation
To install the `sonarlight` package, simply run:
```
pip install sonarlight
```
The package requires the `numpy` and `pandas` packages to be installed.
## Example data
Small example files of the `.sl2` and `.sl3` formats are provided in the `example_files` folder.
## Usage
Once installed, you can use the `Sonar` class to read and parse sonar data from a `.sl2` or `.sl3` file.
When reading a file with `Sonar()` with argument `clean=True` (default) some light data cleaning is performed including dropping unknown columns and rows and observation where the water depth is 0. Setting `augment_coords=True` performs augmentation of the recorded coordinates as implemented in [SL3Reader](https://github.com/halmaia/SL3Reader). Coordinate augmentation attempts to make up for the reduced precision in the recorded coordinates which are rounded to the nearest meter.
The class contains a few methods for extracting data:
* `Sonar.image()` method to extract the raw sonar image for a specific channel
* `Sonar.sidescan_xyz()` method to extract georeferenced sidescan data as XYZ coordinates
* `Sonar.water()` method to extract the water column part of the the raw sonar imagery for a specific channel
* `Sonar.bottom()` method to extract the bottom (sediment) part of the the raw sonar imagery for a specific channel
* `Sonar.bottom_intensity()` method to extract raw sonar intensity at the bottom
The functionality of the class is showcased below and included in the `example_notebook.ipynb`.
Example of reading a sonar file using the `example_files/example_sl2_file.sl2` file:
```python
from sonarlight import Sonar
#Read data from a '.sl2' or '.sl3' file
sl2 = Sonar('path/to/file.sl2')
#See summary of data and available channels
sl2
#Output:
'''
Summary of SL2 file:
- Primary channel with 3182 frames
- Secondary channel with 3182 frames
- Downscan channel with 3182 frames
- Sidescan channel with 3181 frames
Start time: 2023-09-13 08:20:36.840000
End time: 2023-09-13 08:22:52.770999808
File info: version 2, device 2, blocksize 3200, frame version 8
'''
#View raw data store in Pandas dataframe
sl2.df
#Each row contains metadata and pixel for each recorded frame.
#Pixels are stored in the "frames" column.
#The dataframe can be saved for further processing,
#for example the Parquet file format that supports nested data structues.
sl2.df.to_parquet('sl2.parquet')
#Or to '.csv' file
sl2.df.to_csv("sl2.csv")
#Or to '.csv' file after dropping the "frames" column containing nested arrays
df_csv = sl2.df.copy().drop(["frames"], axis=1)
df_csv.to_csv("sl2.csv")
```
Examples of further processing and plotting (see also `example_notebook.ipynb`):
```python
import matplotlib.pyplot as plt
#Plot route and water depth (meters)
route = sl2.df.query("survey == 'primary'")
plt.scatter(route["longitude"], route["latitude"], c=route["water_depth"], s = 3)
plt.colorbar()
```
```python
#Plot primary channel
prim = sl2.image("primary")
plt.imshow(prim.transpose())
```
```python
#Plot water column (surface to water_depth) from downscan channel
#Individual frames are linearly interpolated of length 'pixels'
downscan_water = sl2.water("downscan", pixels=300)
plt.imshow(downscan_water.transpose())
```
```python
#Plot bottom column (water_depth to max sonar range) from primary channel
#Individual frames are subsetted to match the minimum length of the bottom frames
secondary_bottom = sl2.bottom("secondary")
plt.imshow(secondary_bottom.transpose())
```
```python
#Plot sidescan georeferenced points
#Convert sidescan imagery to XYZ point cloud
#Note that this can result in MANY points, every 10'th point are plotted here
mosaic=sl2.sidescan_xyz()
plt.scatter(mosaic.x[::10],
mosaic.y[::10],
c=mosaic.z[::10],
cmap="cividis", s=0.1)
```
## Ressources
The package is inspired by and builds upon other tools and descriptions for processing Lowrance sonar data, e.g. [SL3Reader](https://github.com/halmaia/SL3Reader) which includes a usefull paper, [python-sllib](https://github.com/opensounder/python-sllib), [sonaR](https://github.com/KennethTM/sonaR), [Navico_SLG_Format notes](https://www.memotech.franken.de/FileFormats/Navico_SLG_Format.pdf), older [blog post](https://www.datainwater.com/post/sonar_numpy/).
## TODO
* Notebook with extended processing examples.
* Improve memory/speed efficiency. The package can process large files (>1 GB) rather snappy but does consume some RAM.
* Coordinate augmentation/correction.
* Parse 3D data.
## Other image examples
Raw data
{
"_id": null,
"home_page": "",
"name": "sonarlight",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python",
"author": "Kenneth Thor\u00f8 Martinsen",
"author_email": "kenneth2810@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/50/f4/bba564407537b075d15d7de89ed6d929d27c66717aa9e447b9d7540904ce/sonarlight-0.1.4.tar.gz",
"platform": null,
"description": "# sonarlight\nThe `sonarlight` package provides tools for working with Lowrance sonar data in the `.sl2` and `.sl3` formats. The package includes the `Sonar` class for reading and parsing these files, as well as methods for extracting various types of information from the data. \n\nProject home is [https://github.com/KennethTM/sonarlight](https://github.com/KennethTM/sonarlight).\n\n## Installation\nTo install the `sonarlight` package, simply run:\n\n```\npip install sonarlight\n```\n\nThe package requires the `numpy` and `pandas` packages to be installed.\n\n## Example data\nSmall example files of the `.sl2` and `.sl3` formats are provided in the `example_files` folder.\n\n## Usage\nOnce installed, you can use the `Sonar` class to read and parse sonar data from a `.sl2` or `.sl3` file.\n\nWhen reading a file with `Sonar()` with argument `clean=True` (default) some light data cleaning is performed including dropping unknown columns and rows and observation where the water depth is 0. Setting `augment_coords=True` performs augmentation of the recorded coordinates as implemented in [SL3Reader](https://github.com/halmaia/SL3Reader). Coordinate augmentation attempts to make up for the reduced precision in the recorded coordinates which are rounded to the nearest meter.\n\nThe class contains a few methods for extracting data:\n\n* `Sonar.image()` method to extract the raw sonar image for a specific channel\n* `Sonar.sidescan_xyz()` method to extract georeferenced sidescan data as XYZ coordinates\n* `Sonar.water()` method to extract the water column part of the the raw sonar imagery for a specific channel\n* `Sonar.bottom()` method to extract the bottom (sediment) part of the the raw sonar imagery for a specific channel\n* `Sonar.bottom_intensity()` method to extract raw sonar intensity at the bottom\n\nThe functionality of the class is showcased below and included in the `example_notebook.ipynb`.\n\nExample of reading a sonar file using the `example_files/example_sl2_file.sl2` file:\n\n```python\nfrom sonarlight import Sonar\n\n#Read data from a '.sl2' or '.sl3' file\nsl2 = Sonar('path/to/file.sl2')\n\n#See summary of data and available channels\nsl2\n\n#Output:\n'''\nSummary of SL2 file:\n\n- Primary channel with 3182 frames\n- Secondary channel with 3182 frames\n- Downscan channel with 3182 frames\n- Sidescan channel with 3181 frames\n\nStart time: 2023-09-13 08:20:36.840000\nEnd time: 2023-09-13 08:22:52.770999808\n\nFile info: version 2, device 2, blocksize 3200, frame version 8\n'''\n\n#View raw data store in Pandas dataframe\nsl2.df\n\n#Each row contains metadata and pixel for each recorded frame.\n#Pixels are stored in the \"frames\" column.\n#The dataframe can be saved for further processing, \n#for example the Parquet file format that supports nested data structues.\nsl2.df.to_parquet('sl2.parquet')\n\n#Or to '.csv' file\nsl2.df.to_csv(\"sl2.csv\")\n\n#Or to '.csv' file after dropping the \"frames\" column containing nested arrays\ndf_csv = sl2.df.copy().drop([\"frames\"], axis=1)\ndf_csv.to_csv(\"sl2.csv\")\n```\n\nExamples of further processing and plotting (see also `example_notebook.ipynb`):\n\n```python\nimport matplotlib.pyplot as plt\n\n#Plot route and water depth (meters)\nroute = sl2.df.query(\"survey == 'primary'\")\nplt.scatter(route[\"longitude\"], route[\"latitude\"], c=route[\"water_depth\"], s = 3)\nplt.colorbar()\n```\n\n\n\n```python\n#Plot primary channel\nprim = sl2.image(\"primary\")\nplt.imshow(prim.transpose())\n```\n\n\n\n```python\n#Plot water column (surface to water_depth) from downscan channel\n#Individual frames are linearly interpolated of length 'pixels'\ndownscan_water = sl2.water(\"downscan\", pixels=300)\nplt.imshow(downscan_water.transpose())\n```\n\n\n\n```python\n#Plot bottom column (water_depth to max sonar range) from primary channel\n#Individual frames are subsetted to match the minimum length of the bottom frames\nsecondary_bottom = sl2.bottom(\"secondary\")\nplt.imshow(secondary_bottom.transpose())\n```\n\n\n\n```python\n#Plot sidescan georeferenced points\n#Convert sidescan imagery to XYZ point cloud\n#Note that this can result in MANY points, every 10'th point are plotted here\nmosaic=sl2.sidescan_xyz()\nplt.scatter(mosaic.x[::10], \n mosaic.y[::10], \n c=mosaic.z[::10], \n cmap=\"cividis\", s=0.1)\n```\n\n\n\n## Ressources\nThe package is inspired by and builds upon other tools and descriptions for processing Lowrance sonar data, e.g. [SL3Reader](https://github.com/halmaia/SL3Reader) which includes a usefull paper, [python-sllib](https://github.com/opensounder/python-sllib), [sonaR](https://github.com/KennethTM/sonaR), [Navico_SLG_Format notes](https://www.memotech.franken.de/FileFormats/Navico_SLG_Format.pdf), older [blog post](https://www.datainwater.com/post/sonar_numpy/).\n\n## TODO\n\n* Notebook with extended processing examples.\n* Improve memory/speed efficiency. The package can process large files (>1 GB) rather snappy but does consume some RAM.\n* Coordinate augmentation/correction.\n* Parse 3D data.\n\n## Other image examples\n\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "sonarlight",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ca3cb0fe9a9d648b5537cce36d2934b6eebcc679e67c5dd4c8eba15292646e6",
"md5": "6378f3248152758f44a22c2be545e8f4",
"sha256": "4fcafad58879435c21d0e9a8c961539dd6b38f4a695397a13403b16c6214297e"
},
"downloads": -1,
"filename": "sonarlight-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6378f3248152758f44a22c2be545e8f4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11645,
"upload_time": "2023-10-30T10:28:34",
"upload_time_iso_8601": "2023-10-30T10:28:34.830822Z",
"url": "https://files.pythonhosted.org/packages/1c/a3/cb0fe9a9d648b5537cce36d2934b6eebcc679e67c5dd4c8eba15292646e6/sonarlight-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "50f4bba564407537b075d15d7de89ed6d929d27c66717aa9e447b9d7540904ce",
"md5": "b9d85d6249df70b34ecc32320624b0b1",
"sha256": "745ea4879a094755e39ae961e8200bba10f6fdc2c125fe239dd1e7cdaca1c1a0"
},
"downloads": -1,
"filename": "sonarlight-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "b9d85d6249df70b34ecc32320624b0b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10609,
"upload_time": "2023-10-30T10:28:36",
"upload_time_iso_8601": "2023-10-30T10:28:36.420247Z",
"url": "https://files.pythonhosted.org/packages/50/f4/bba564407537b075d15d7de89ed6d929d27c66717aa9e447b9d7540904ce/sonarlight-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-30 10:28:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sonarlight"
}
