{"id":16215737,"url":"https://github.com/elcosas/spad_regression_research","last_synced_at":"2025-04-07T22:42:01.796Z","repository":{"id":181850946,"uuid":"665726878","full_name":"elcosas/SPAD_Regression_Research","owner":"elcosas","description":"Experimentations with various non-parametic regression algorithms for reconstructing transient response curves from SPAD sensors","archived":false,"fork":false,"pushed_at":"2024-01-22T06:12:28.000Z","size":16848,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-14T00:14:09.526Z","etag":null,"topics":["image-processing-python","jupyter-notebook"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elcosas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-07-12T21:29:33.000Z","updated_at":"2023-07-28T16:31:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"628283a0-9833-4c18-9a63-6bb594f33c6a","html_url":"https://github.com/elcosas/SPAD_Regression_Research","commit_stats":null,"previous_names":["elcosas/spad_regression_research"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcosas%2FSPAD_Regression_Research","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcosas%2FSPAD_Regression_Research/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcosas%2FSPAD_Regression_Research/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elcosas%2FSPAD_Regression_Research/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elcosas","download_url":"https://codeload.github.com/elcosas/SPAD_Regression_Research/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744277,"owners_count":20988781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-processing-python","jupyter-notebook"],"created_at":"2024-10-10T11:16:08.425Z","updated_at":"2025-04-07T22:42:01.777Z","avatar_url":"https://github.com/elcosas.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SPAD Regression Research\n![GitHub Repo stars](https://img.shields.io/github/stars/elcosas/SPAD_Regression_Research)\n![GitHub forks](https://img.shields.io/github/forks/elcosas/SPAD_Regression_Research)\n![GitHub](https://img.shields.io/github/license/elcosas/SPAD_Regression_Research)\n![GitHub last commit (branch)](https://img.shields.io/github/last-commit/elcosas/SPAD_Regression_Research/main)\n------------------------------------------------------------------------\nThis repository contains various tests and jupyter notebook experimentations with various\nregression algorithms, mainly non-parametic, in order to better model the response curves of\nSPAD sensors from both EWH and EDH datasets\\\n![example graph](visuals/example.png)\\\n*Figure 1: Example graph of each regression model plotted against ground-truth data*\n\n## Motivation\nThe use of equi-depth histograms (EDH) to model photon arrival times in SPAD sensors for single-photon 3D cameras has greatly improved the accuracy of identifying the precise depth value of an object in a scene. Additionally, EDH also allows for much smaller binning requirements in order to accurately model depth levels, thus decreasing the amount of data needed to process each pixel in the image. Despite this, there are still issues with solely using EDH data to estimate depth and saturation, mainly the limited amount of actual depth levels that can be extracted from datasets with smaller bin sizes. The use of non-parametic regresssion equations as proposed both here and in the writeup hope to remedy this by allowing for estimation of photon counts at any point in the camera's exposure time. This not only allows for obtaining more information about the object captured by each pixel (such as reflectivity of the object and other sources of ambient light), but also allows for more potential depth levels for even smaller sized equi-depth bins. \n\n## Installation\nThe project can be installed using git via:\n```bash\ngit clone https://github.com/elcosas/SPAD_Regression_Research.git\n```\nAll libraries required for installation can be installed through pip using `max_requirements.txt`\n```bash\npip install -r max_requirements.txt\n```\nor by using `min_requirements.txt` to avoid installing Jupyterlab dependencies\n```bash\npip install -r min_requirements.txt\n```\nTo get started, `cd` into the `src` folder and run:\n```bash\npython3 example.py 0\n```\nto generate the same graph shown in *Figure 1*!\n\n## Usage (Notebook)\nThe main `Notebook.ipynb` file contains the various expermentations done with the sample data provided as well as different parametic and \nnon-parametic regression methods tested with the sample data. Once inside the project folder, the notebook can be viewed and tested\nby running:\n```bash\njupyter lab Notebook.ipynb\n```\n\n## Usage (Scripts)\nThe repository also contains various scripts that can be used to plot the three regression models on various datasets, generate error statistcs files for the regression models,\nand create depth maps using these models. First, use `cd src` to change to the scripts directory and run any of the following scripts:\n\n### `edh_test.py` \u0026 `ewh_test.py`:\nThese scripts generate the histogram, equi-depth or equi-width respectively, of the transients passed as arguments and plots the passed regression method in comparison with the ground-truth data.\nThese can be run with:\n```bash\npython3 edh_test.py {model name} {operation name} {set #}\n```\n```bash\npython3 ewh_test.py {model name} {operation name} {set #}\n```\nWhere:\\\n`model name`: the regression model to test, either \"gaussian\", \"lowess\", or \"kde\" (note: kde is not avalible for equi-width tests)\\\n`operation name`: the test type to run, either \"single\" to generate a single graph, or \"all\" to generate a zip file of all the graphs in the transients dataset\\\n`set #`: the dataset # to use (scales from 0-29 for the data in `./dataset`)\n\n### `error_test.py`:\nThis script generates two .csv files, one for EWH data and EDH data, with error statistics for all three regression equations. These include the coefficient of determination,\nmean squared error, maximum error, and peak error (error between maximum values). it can be run with:\n```bash\npython3 error_test.py {set #}\n```\nWhere:\\\n`set #`: the dataset # to use (scales from 0-29 for the data in `./dataset`)\n\n### `mk_image.py`:\nThis script generates a depth map from the equi-depth boundaries of a 3-dimensional .npy file of image data. it can be run with:\n```bash\npython3 mk_image.py {file name}.npy {model name}\n```\nWhere:\\\n`file name`: the file name of the 3-dimensional .npy file\\\n`model name`: the regression model to test, either \"gaussian\", \"lowess\", or \"kde\" (note: kde is not avalible for equi-width tests)\n\n## Write-up installation\nThe .pdf of the paper can built by running `cd paper` to move to the `paper` directory, then running `make build` to compile the .tex file into a .pdf\n(this assumes LaTeX is installed, if not run `sudo apt install texlive-latex-recommended`). Any extraneous files can be removed by running `make clean`\n\n## Attributions and License\nThis project is licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felcosas%2Fspad_regression_research","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felcosas%2Fspad_regression_research","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felcosas%2Fspad_regression_research/lists"}