# 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 `notebooks/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 `notebooks/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/).
## Release notes
0.1.7 - [Fix coordinate augmentation](https://github.com/KennethTM/sonarlight/issues/2)
0.1.5 - Fixed offset error (off by 8 bytes) when reading frames.
## Other image examples
Raw data
{
"_id": null,
"home_page": null,
"name": "sonarlight",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python",
"author": "Kenneth Thor\u00f8 Martinsen",
"author_email": "kenneth2810@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/77/8d/a695ad401432aa54aff56571a2874a93bf29139db28d05eb126d4cce838b/sonarlight-0.1.7.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 `notebooks/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 `notebooks/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## Release notes\n\n0.1.7 - [Fix coordinate augmentation](https://github.com/KennethTM/sonarlight/issues/2)\n0.1.5 - Fixed offset error (off by 8 bytes) when reading frames.\n\n## Other image examples\n\n\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "sonarlight",
"version": "0.1.7",
"project_urls": null,
"split_keywords": [
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "330abe9d8096194720b55265bfabc4c1366c0a58bd3351d72894a8f49ed550f1",
"md5": "4ca8c4da45a3521fed4745b2b2b96bcc",
"sha256": "efc24e7b21e641f2b5dab1239bbcf0b2a23100bc7dec3ce716a6f6a437839dd2"
},
"downloads": -1,
"filename": "sonarlight-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ca8c4da45a3521fed4745b2b2b96bcc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11741,
"upload_time": "2025-01-20T12:40:47",
"upload_time_iso_8601": "2025-01-20T12:40:47.341688Z",
"url": "https://files.pythonhosted.org/packages/33/0a/be9d8096194720b55265bfabc4c1366c0a58bd3351d72894a8f49ed550f1/sonarlight-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "778da695ad401432aa54aff56571a2874a93bf29139db28d05eb126d4cce838b",
"md5": "10a24f38dd878398289f59611b8f4a49",
"sha256": "daa49b31856afd2a17dce1ce7cc06bf516634d76722833e9743cf9dddc0c641f"
},
"downloads": -1,
"filename": "sonarlight-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "10a24f38dd878398289f59611b8f4a49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10652,
"upload_time": "2025-01-20T12:40:51",
"upload_time_iso_8601": "2025-01-20T12:40:51.235357Z",
"url": "https://files.pythonhosted.org/packages/77/8d/a695ad401432aa54aff56571a2874a93bf29139db28d05eb126d4cce838b/sonarlight-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 12:40:51",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sonarlight"
}
JSON