diff --git a/README.md b/README.md index 12fc1dd..cfe0773 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,6 @@
- [![PyPI License](https://img.shields.io/pypi/l/sydraw.svg)](https://pypi.org/project/sydraw) [![PyPI Version](https://img.shields.io/pypi/v/sydraw.svg)](https://pypi.org/project/sydraw) [![PyPI Downloads](https://img.shields.io/pypi/dm/syndalib.svg?color=orange)](https://pypistats.org/packages/syndalib) @@ -47,192 +46,3 @@ $ python >>> import sydraw >>> sydraw.__version__ ``` - -# Datasets Generation -You can generate models of circles, lines and ellipses. -You can define a vast set of parameters to specify the sampling space and the characteristics of your models (the hyperparameters change for each model, but each of them consists in a interval of values the hyperparameter can take). -In this README you'll find a section for each class of models in which I'll dig deeper into the hyperparameters I provide. -the generation process is straight-forward and it is shown in the following code snippet: - -```python -# import the 2D point cloud module -from sydraw import synth - -# optionally you can specify the sampling space of both outliers and each class by defining a dictionary (options) -# and feeding it into the set_options() function. -# for reference, this example shows you the default options: -options = { - "outliers": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) - }, - "circles": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1.0, 1.0), - "y_center_r": (-1.0, 1.0), - }, - - "lines": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) - }, - - "ellipses": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1, 1), - "y_center_r": (-1, 1), - "width_r": (0.1, 1), - "height_r": (0.1, 1) - }, -} - -synth.set_options(options) - - -# models generation -outliers_range = [0.1,0.2,0.3,0.4,0.5] -noise_range = [0.01] -synth.generate_data(ns=1024, - npps=256, - class_type="circles", - nm=2, - outliers_range=outliers_range, - noise_range=noise_range, - ds_name="example_dir", - is_train=False - ) -``` - -# terminology and abbreviations -- ```sample:``` unordered set of points. a sample is made by outliers and inliers for each sampled model. -- ```model:``` instance of a class (i.e. line with a specific slope and intercept) -- ```npps:``` number of points per sample -- ```ns:``` number of samples within each .mat file -- ```nm:``` number of models to be generated within each sample of the dataset - -# data folder -data are saved in a structured fashion. -here I'll show you where the data generated in the previous code snippet will be saved: -``` -./data - |- circles - |- nm_2 - |- ds_name - |- npps_256 - |- ns_1024 - |- test - |- imgs - |- circles_no_10_noise_0.01.mat - |- circles_no_20_noise_0.01.mat - |- circles_no_30_noise_0.01.mat - |- circles_no_40_noise_0.01.mat - |- circles_no_50_noise_0.01.mat - -``` -where ```imgs``` contains some images of the randomly sampled models. It has the following structure: -``` -imgs - |- circles_no_10_noise_0.01 - |- *jpg files - |- circles_no_20_noise_0.01 - |- *jpg files - |- circles_no_30_noise_0.01 - |- *jpg files - |- circles_no_40_noise_0.01 - |- *jpg files - |- circles_no_50_noise_0.01 - |- *jpg files -``` - - -# classes of models -## outliers -```class_type = "outliers" ``` -outliers are sampled from the 2D space (x_r) X (y_r), -where x_r (x range) is the closed interval of values x can take and -y_r (y range) is the closed interval of values y can take. -``` -"outliers": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) - }, -``` -## circles -```class_type = "circles"``` -circles are generated by uniformly sampling a center and a radius from the closed intervals specified by the user. -the default values are: -``` -"circles": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1.0, 1.0), - "y_center_r": (-1.0, 1.0), -}, -``` - -## lines -```class_type = "lines"``` -lines are generated by randomly sampling two points in the 2D space (x_r) x (y_r) (in order to define slope and intercept) -and consequently sampling points belonging to such line. -each point of the line is assured to belong to the 2D space (x_r) x (y_r). -``` -"lines": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) -}, -``` - -## ellipses -```class_type = "ellipses"``` -ellipses are generated by uniformly sampling a center and a radius from the closed intervals specified by the user, and -consequently apply a horizontal stretch/shrinkage to the sampled circle. -the default values are: -``` - "ellipses": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1, 1), - "y_center_r": (-1, 1), - "width_r": (0.1, 1), - "height_r": (0.1, 1) - }, -``` - -## conics -```class_type = "conics"``` -randomly samples models from the classes specified above. -hyperbola is not implemented yet. - -# Points and Models Generations -If you are not interested in generating huge datasets of data corrupted by outliers and noise, namely, if you just want to generate some points belonging to a specific model and retrieve such models coefficients, you can do as follows. -I'll show you an example using a circle, but there are analogous functions for the other conics - -```python -from sydraw import drawer -``` -##### points generation -generates 10 randomly sampled points from a user-specified circle. -```python -circle = drawer.circle_points(r=3.0, c=(1.0,1.0), n=10) -``` - -The code above will generate a numpy array of 2D points in homogeneous coordinates. Such points belong to the circle with radius = 3 and center = (1.0,1.0). -``` ->>> array([[-1.51779408, -0.63116921, 1. ], - [-1.83302435, 1.98690071, 1. ], - [-0.0106027 , 3.82465612, 1. ], - [-0.32848561, 3.68981895, 1. ], - [-1.93858646, 0.39608805, 1. ], - [ 3.66809769, -0.37158839, 1. ], - [-0.54906204, 3.56912569, 1. ], - [ 3.88941592, 1.8070165 , 1. ], - [ 2.56806854, -1.55756937, 1. ], - [ 3.88477601, 1.82344847, 1. ]]) -``` - - -##### model coefficients generation -```python -circle = drawer.circle_coefs(r=3.0, c=(1.0, 1.0), n=10) -``` -The code above will return a numpy array whose elements are the coefficients of the corresponding conic. - -[▲ back to top](#sydraw) diff --git a/docs/about/changelog.md b/docs/about/changelog.md deleted file mode 100644 index 46ee453..0000000 --- a/docs/about/changelog.md +++ /dev/null @@ -1,9 +0,0 @@ -# Release Notes - -## 0.0.0 (2021-01-05) - - - implemented line - -## 0.0.1 (2021-02-01) - - - implemented ellipse \ No newline at end of file diff --git a/docs/about/changelog.md b/docs/about/changelog.md new file mode 120000 index 0000000..699cc9e --- /dev/null +++ b/docs/about/changelog.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file diff --git a/docs/about/contributing.md b/docs/about/contributing.md deleted file mode 100644 index 4a74e20..0000000 --- a/docs/about/contributing.md +++ /dev/null @@ -1,92 +0,0 @@ -# Contributor Guide - -## Setup - -### Requirements - -* Make: - - macOS: `$ xcode-select --install` - - Linux: [https://www.gnu.org](https://www.gnu.org/software/make) - - Windows: `$ choco install make` [https://chocolatey.org](https://chocolatey.org/install) -* Python: `$ asdf install` (https://asdf-vm.com)[https://asdf-vm.com/guide/getting-started.html] -* Poetry: [https://python-poetry.org](https://python-poetry.org/docs/#installation) -* Graphviz: - * macOS: `$ brew install graphviz` - * Linux: [https://graphviz.org/download](https://graphviz.org/download/) - * Windows: [https://graphviz.org/download](https://graphviz.org/download/) - -To confirm these system dependencies are configured correctly: - -```text -$ make doctor -``` - -### Installation - -Install project dependencies into a virtual environment: - -```text -$ make install -``` - -## Development Tasks - -### Manual - -Run the tests: - -```text -$ make test -``` - -Run static analysis: - -```text -$ make check -``` - -Build the documentation: - -```text -$ make docs -``` - -### Automatic - -Keep all of the above tasks running on change: - -```text -$ make dev -``` - -> In order to have OS X notifications, `brew install terminal-notifier`. - -## Continuous Integration - -The CI server will report overall build status: - -```text -$ make ci -``` - -## Demo Tasks - -Run the program: - -```text -$ make run -``` - -Launch an IPython session: - -```text -$ make shell -``` - -## Release Tasks - -Release to PyPI: - -```text -$ make upload -``` diff --git a/docs/about/contributing.md b/docs/about/contributing.md new file mode 120000 index 0000000..f939e75 --- /dev/null +++ b/docs/about/contributing.md @@ -0,0 +1 @@ +../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/about/license.md b/docs/about/license.md deleted file mode 100644 index 83536ef..0000000 --- a/docs/about/license.md +++ /dev/null @@ -1,22 +0,0 @@ - -MIT License - -Copyright © 2022, William Bonvini - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/docs/about/license.md b/docs/about/license.md new file mode 120000 index 0000000..f0608a6 --- /dev/null +++ b/docs/about/license.md @@ -0,0 +1 @@ +../../LICENSE.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 2714366..0000000 --- a/docs/index.md +++ /dev/null @@ -1,143 +0,0 @@ -# sydraw - -[![Coverage Status](https://img.shields.io/codecov/c/gh/WilliamBonvini/pinchsearcher)](https://codecov.io/gh/WilliamBonvini/pinchsearcher) -[![Scrutinizer Code Quality](https://img.shields.io/scrutinizer/g/WilliamBonvini/pinchsearcher.svg)](https://scrutinizer-ci.com/g/WilliamBonvini/pinchsearcher) -[![PyPI License](https://img.shields.io/pypi/l/sydraw.svg)](https://pypi.org/project/sydraw) -[![PyPI Version](https://img.shields.io/pypi/v/sydraw.svg)](https://pypi.org/project/sydraw) -[![PyPI Downloads](https://img.shields.io/pypi/dm/sydraw.svg?color=orange)](https://pypistats.org/packages/sydraw) - -sydraw (Synthetic Data Library) is a python library that helps you create synthetic 2D point clouds for single/multi-model single/multi-class tasks. -You'll be able to fix a set of hyperparameters for each class of models you are interested in generating. -Have a look at some samples: - -| Single Class - Single Model | Single Class - Multi Model | Multi Class - Multi Model | -|:-----------------------------------------------------:|:---------------------------------------------------:|:-------------------------------------------------:| -| | | | - - -## Setup - -### Requirements - -* Python 3.8+ - -### Installation - -Install it directly into an activated virtual environment: - -```text -$ pip install sydraw -``` - -or add it to your [Poetry](https://poetry.eustace.io/) project: - -```text -$ poetry add sydraw -``` - -## Usage - -After installation, the package can be imported: - -```text -$ python ->>> import sydraw ->>> sydraw.__version__ -``` - -# Datasets Generation -You can generate models of circles, lines and ellipses. -You can define a vast set of parameters to specify the sampling space and the characteristics of your models (the hyperparameters change for each model, but each of them consists in a interval of values the hyperparameter can take). -In this README you'll find a section for each class of models in which I'll dig deeper into the hyperparameters I provide. -the generation process is straight-forward and it is shown in the following code snippet: - -```python -# import the 2D point cloud module -from sydraw import syn2d - -# optionally you can specify the sampling space of both outliers and each class by defining a dictionary (options) -# and feeding it into the set_options() function. -# for reference, this example shows you the default options: -options = { - "outliers": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) - }, - "circles": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1.0, 1.0), - "y_center_r": (-1.0, 1.0), - }, - - "lines": { - "x_r": (-2.5, 2.5), - "y_r": (-2.5, 2.5) - }, - - "ellipses": { - "radius_r": (0.5, 1.5), - "x_center_r": (-1, 1), - "y_center_r": (-1, 1), - "width_r": (0.1, 1), - "height_r": (0.1, 1) - }, -} - -syn2d.set_options(options) - - -# models generation -outliers_range = [0.1,0.2,0.3,0.4,0.5] -noise_range = [0.01] -syn2d.generate_data(ns=1024, - npps=256, - class_type="circles", - nm=2, - outliers_range=outliers_range, - noise_range=noise_range, - ds_name="example_dir", - is_train=False - ) -``` - -# terminology and abbreviations -- ```sample:``` unordered set of points. a sample is made by outliers and inliers for each sampled model. -- ```model:``` instance of a class (i.e. line with a specific slope and intercept) -- ```npps:``` number of points per sample -- ```ns:``` number of samples within each .mat file -- ```nm:``` number of models to be generated within each sample of the dataset - -# data folder -data are saved in a structured fashion. -here I'll show you where the data generated in the previous code snippet will be saved: -``` -./data - |- ds_name - |- circles - |- nm_2 - |- npps_256 - |- ns_1024 - |- test - |- imgs - |- circles_no_10_noise_0.01.mat - |- circles_no_20_noise_0.01.mat - |- circles_no_30_noise_0.01.mat - |- circles_no_40_noise_0.01.mat - |- circles_no_50_noise_0.01.mat - -``` -where ```imgs``` contains some images of the randomly sampled models. It has the following structure: -``` -imgs - |- circles_no_10_noise_0.01 - |- *jpg files - |- circles_no_20_noise_0.01 - |- *jpg files - |- circles_no_30_noise_0.01 - |- *jpg files - |- circles_no_40_noise_0.01 - |- *jpg files - |- circles_no_50_noise_0.01 - |- *jpg files -``` - diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/docs/usage/output_folder_structure.md b/docs/usage/output_folder_structure.md new file mode 100644 index 0000000..725cb4c --- /dev/null +++ b/docs/usage/output_folder_structure.md @@ -0,0 +1,35 @@ + +# Output Folder Structure +data are saved in a structured fashion. +here I'll show you where the data generated in the previous code snippet will be saved: +``` +./data + |- circles + |- nm_2 + |- ds_name + |- npps_256 + |- ns_1024 + |- test + |- imgs + |- circles_no_10_noise_0.01.mat + |- circles_no_20_noise_0.01.mat + |- circles_no_30_noise_0.01.mat + |- circles_no_40_noise_0.01.mat + |- circles_no_50_noise_0.01.mat + +``` +where ```imgs``` contains some images of the randomly sampled models. It has the following structure: +``` +imgs + |- circles_no_10_noise_0.01 + |- *jpg files + |- circles_no_20_noise_0.01 + |- *jpg files + |- circles_no_30_noise_0.01 + |- *jpg files + |- circles_no_40_noise_0.01 + |- *jpg files + |- circles_no_50_noise_0.01 + |- *jpg files +``` + diff --git a/docs/parametric_models.md b/docs/usage/parametric_models.md similarity index 100% rename from docs/parametric_models.md rename to docs/usage/parametric_models.md diff --git a/docs/usage/terminology.md b/docs/usage/terminology.md new file mode 100644 index 0000000..b67d8d6 --- /dev/null +++ b/docs/usage/terminology.md @@ -0,0 +1,7 @@ + +# terminology and abbreviations +- ```sample:``` unordered set of points. a sample is made by outliers and inliers for each sampled model. +- ```model:``` instance of a class (i.e. line with a specific slope and intercept) +- ```npps:``` number of points per sample +- ```ns:``` number of samples within each .mat file +- ```nm:``` number of models to be generated within each sample of the dataset diff --git a/mkdocs.yml b/mkdocs.yml index 950c681..4a3cbe5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,8 +12,13 @@ markdown_extensions: nav: - Home: index.md - - Advanced: advanced.md + - Usage: + - Terminology: usage/terminology.md + - Points Generation: usage/point_generation.md + - Parametric Models: usage/parametric_models.md + - Output Folder Structure: usage/output_folder_structure.md - About: - - Release Notes: about/changelog.md - - Contributor Guide: about/contributing.md - - License: about/license.md + - Release Notes: about/changelog.md + - Contributor Guide: about/contributing.md + - License: about/license.md +