<div align="center">
<h1>Pavimentados</h1>
[User Manual](docs/manual_202410.pdf)
[](https://sonarcloud.io/summary/new_code?id=EL-BID_pavimentados)
[](https://pepy.tech/project/pavimentados)
</div>
## Description
---
Pavimentados is a tool that allows the identification of pavement faults located on highways or roads.
This library provides an environment to use computer vision models developed to detect different elements.
The detected elements are then used to generate metrics that aid the process of planning road maintenance.
The model files can be downloaded from this [link](https://github.com/EL-BID/pavimentados/raw/refs/heads/main/models/model_20240818.tar.gz).
> **Important changes**: Unlike the previous version, this new version does not include traffic sign detection. We hope to be able to
> include it again in future versions.
## Main Features
---
Some of the features available are:
- Scoring using the models already developed.
- Workflows for image acquisition and assessment.
- Evaluation of gps information to determine the location of faults and elements.
- Image or video support.
- Support for GPS data in different formats (GPRRA, csv, embedded in image).
## Instalation
---
Install the library using the following command:
```
pip install pavimentados
```
Next,
* [download the model](https://github.com/EL-BID/pavimentados/raw/refs/heads/main/models/model_20240818.tar.gz) from this link
* Decompress it using the following command
```bash
tar -xzvf model_20240818.tar.gz
```
## Quick Start
---
In the `notebooks` folder there is a complete example of how to process both images and videos present
in `notebooks/road_videos` and `notebooks/road_images`. The results are saved to `notebooks/outputs`.
The first step is to import the components that create a workflow with images:
```
from pavimentados.processing.processors import MultiImage_Processor
from pavimentados.processing.workflows import Workflow_Processor
```
In this example, there is the image processor object MultiImage_Processor which is in charge of taking the images and analyzing them individually using the models. In addition, there is the Workflow_Processor object that is in charge of the image processing workflow.
Internally, the Workflow_Processor has objects that can interpret different image sources or GPS information.
Among the allowed image sources are:
- image_routes: A list of image routes.
- image_folder: A folder with all images.
- video: The path to a video file.
Among the allowed GPS data sources are:
- image_routes: A list of paths to the routes of the images that have the gps data embedded in them.
- image_folder: A path to a folder with all the images that have the gps data embedded in them.
- loc: A file in [NMEA format](docs%2Fgps_data_formats.md).
- gpx: A file in GPX format
Once these elements are imported, the processor is instantiated as follows:
```python
from pathlib import Path
models_path = Path("./artifacts") # Path to downloaded model
ml_processor = MultiImage_Processor(artifacts_path=str(models_path))
```
Alternatively, an additional JSON file can be specified to set or overwrite certain configuration parameters of the models.
```python
ml_processor = MultiImage_Processor(artifacts_path=str(models_path), config_file="./models_config.json")
```
These parameters allow the specification of parameter such as the confidence, iou, or maximum amount of detections per frame.
Example of the configuration file:
```json
{
"paviment_model": {
"yolo_threshold": 0.20,
"yolo_iou": 0.45,
"yolo_max_detections": 100
}
}
```
The workflow object receives the instantiated processor. Without it is not able to execute the workflow.
```python
input_video_file = "sample.mp4"
input_gps_file = "sample.log"
# Create a workflow for videos
workflow = Workflow_Processor(
input_video_file, image_source_type="video", gps_source_type="loc", gps_input=input_gps_file, adjust_gps=True
)
```
The last step is to execute the workflow:
```python
results = workflow.execute(ml_processor,
batch_size=16,
video_output_file="processed_video.mp4"
)
```
> * `video_output_file` and `image_folder_output` are optional and are only to save output video or image files along detections.
The results can be saved in csv format or used for further processing.
```python
# Save results to outputs directory
import pandas as pd
for result_name in results.keys():
pd.DataFrame(results[result_name]).to_csv(f"{result_name}.csv")
```
In the `results` object you will find the following:
1. table_summary_sections: DataFrame with summary table by sections.
2. data_resulting: DataFrame with results per frame.
3. data_resulting_fails: DataFrame with results by unique faults encountered.
To see more details about the results please refer to [this page](docs%2Fresults.md).
## Project structure
---
* `docs`: Documentation files.
* `models`: Reference path where the downloaded model artifact should be placed.
* `notebooks`: Examples of how to process images and videos.
* `pavimentados/analyzers`: Modules for image/video processing and generation of the final output.
* `pavimentados/configs`: General configuration and parameters of the models.
* `pavimentados/models`: Modules for YoloV8 and Siamese models.
* `pavimentados/processing`: Workflows for processing.
## Changelog
---
For information regarding the latest changes/updates in the library please refer to the [changes document](docs/CHANGELOG.md).
## Authors
---
This package has been developed by:
<a href="https://github.com/J0s3M4rqu3z" target="blank">Jose Maria Marquez Blanco</a>
<br/>
<a href="https://www.linkedin.com/in/joancerretani/" target="blank">Joan Alberto Cerretani</a>
<br/>
<a href="https://www.linkedin.com/in/ingvictordurand/" target="blank">Victor Durand</a>
Raw data
{
"_id": null,
"home_page": null,
"name": "pavimentados",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "Machine Learning, crack detections, computer vision, safe road",
"author": "Jose Maria Marquez Blanco",
"author_email": "jose.marquez.blanco@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f9/2f/680fe35537ae4e8156c6ecb289172f010f1928a4a84b9c9de4d2718b5062/pavimentados-1.0.5.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1>Pavimentados</h1>\n\n[User Manual](docs/manual_202410.pdf)\n\n\n[](https://sonarcloud.io/summary/new_code?id=EL-BID_pavimentados)\n[](https://pepy.tech/project/pavimentados)\n\n\n</div>\n\n## Description\n---\nPavimentados is a tool that allows the identification of pavement faults located on highways or roads. \nThis library provides an environment to use computer vision models developed to detect different elements. \nThe detected elements are then used to generate metrics that aid the process of planning road maintenance.\n\nThe model files can be downloaded from this [link](https://github.com/EL-BID/pavimentados/raw/refs/heads/main/models/model_20240818.tar.gz).\n\n> **Important changes**: Unlike the previous version, this new version does not include traffic sign detection. We hope to be able to \n> include it again in future versions. \n\n## Main Features\n---\n\nSome of the features available are:\n\n- Scoring using the models already developed.\n- Workflows for image acquisition and assessment.\n- Evaluation of gps information to determine the location of faults and elements.\n- Image or video support.\n- Support for GPS data in different formats (GPRRA, csv, embedded in image).\n\n## Instalation\n---\n\nInstall the library using the following command:\n\n```\npip install pavimentados\n```\n\nNext, \n* [download the model](https://github.com/EL-BID/pavimentados/raw/refs/heads/main/models/model_20240818.tar.gz) from this link\n\n* Decompress it using the following command\n```bash\ntar -xzvf model_20240818.tar.gz\n```\n\n## Quick Start\n---\n\nIn the `notebooks` folder there is a complete example of how to process both images and videos present\nin `notebooks/road_videos` and `notebooks/road_images`. The results are saved to `notebooks/outputs`.\n\nThe first step is to import the components that create a workflow with images:\n```\nfrom pavimentados.processing.processors import MultiImage_Processor\nfrom pavimentados.processing.workflows import Workflow_Processor\n```\n\nIn this example, there is the image processor object MultiImage_Processor which is in charge of taking the images and analyzing them individually using the models. In addition, there is the Workflow_Processor object that is in charge of the image processing workflow. \n\nInternally, the Workflow_Processor has objects that can interpret different image sources or GPS information. \n\nAmong the allowed image sources are:\n\n - image_routes: A list of image routes.\n - image_folder: A folder with all images.\n - video: The path to a video file.\n\nAmong the allowed GPS data sources are:\n\n - image_routes: A list of paths to the routes of the images that have the gps data embedded in them.\n - image_folder: A path to a folder with all the images that have the gps data embedded in them.\n - loc: A file in [NMEA format](docs%2Fgps_data_formats.md).\n - gpx: A file in GPX format\n \nOnce these elements are imported, the processor is instantiated as follows:\n\n```python\nfrom pathlib import Path\nmodels_path = Path(\"./artifacts\") # Path to downloaded model\nml_processor = MultiImage_Processor(artifacts_path=str(models_path))\n```\n\nAlternatively, an additional JSON file can be specified to set or overwrite certain configuration parameters of the models.\n\n```python\nml_processor = MultiImage_Processor(artifacts_path=str(models_path), config_file=\"./models_config.json\")\n```\nThese parameters allow the specification of parameter such as the confidence, iou, or maximum amount of detections per frame.\n\nExample of the configuration file:\n```json\n{\n\t\"paviment_model\": {\n\t\t\"yolo_threshold\": 0.20,\n\t\t\"yolo_iou\": 0.45,\n\t\t\"yolo_max_detections\": 100\n\t}\n}\n```\n\nThe workflow object receives the instantiated processor. Without it is not able to execute the workflow.\n\n```python\ninput_video_file = \"sample.mp4\"\ninput_gps_file = \"sample.log\"\n\n# Create a workflow for videos\nworkflow = Workflow_Processor(\n input_video_file, image_source_type=\"video\", gps_source_type=\"loc\", gps_input=input_gps_file, adjust_gps=True\n)\n```\n\nThe last step is to execute the workflow:\n\n```python\nresults = workflow.execute(ml_processor, \n batch_size=16, \n video_output_file=\"processed_video.mp4\" \n )\n```\n\n> * `video_output_file` and `image_folder_output` are optional and are only to save output video or image files along detections.\n\nThe results can be saved in csv format or used for further processing.\n\n```python\n# Save results to outputs directory\nimport pandas as pd\nfor result_name in results.keys():\n pd.DataFrame(results[result_name]).to_csv(f\"{result_name}.csv\")\n```\n\nIn the `results` object you will find the following:\n\n 1. table_summary_sections: DataFrame with summary table by sections.\n 2. data_resulting: DataFrame with results per frame.\n 3. data_resulting_fails: DataFrame with results by unique faults encountered.\n\nTo see more details about the results please refer to [this page](docs%2Fresults.md).\n\n\n## Project structure\n---\n* `docs`: Documentation files.\n* `models`: Reference path where the downloaded model artifact should be placed. \n* `notebooks`: Examples of how to process images and videos.\n* `pavimentados/analyzers`: Modules for image/video processing and generation of the final output.\n* `pavimentados/configs`: General configuration and parameters of the models.\n* `pavimentados/models`: Modules for YoloV8 and Siamese models.\n* `pavimentados/processing`: Workflows for processing.\n\n\n## Changelog\n---\nFor information regarding the latest changes/updates in the library please refer to the [changes document](docs/CHANGELOG.md).\n\n\n## Authors\n---\n\nThis package has been developed by:\n\n<a href=\"https://github.com/J0s3M4rqu3z\" target=\"blank\">Jose Maria Marquez Blanco</a>\n<br/>\n<a href=\"https://www.linkedin.com/in/joancerretani/\" target=\"blank\">Joan Alberto Cerretani</a>\n<br/>\n<a href=\"https://www.linkedin.com/in/ingvictordurand/\" target=\"blank\">Victor Durand</a>\n",
"bugtrack_url": null,
"license": null,
"summary": "A python package Library which implement IA algorithms to detect cracks and failures on roads. The package is wrapper around all the models and provides an interfaces to use them properly",
"version": "1.0.5",
"project_urls": null,
"split_keywords": [
"machine learning",
" crack detections",
" computer vision",
" safe road"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e22e0bfd8af5115b9b3c85078ca2707dbcae51d8fb914c8103c523c90d84ae87",
"md5": "d92da3435546dae0ad7e918a1fb81770",
"sha256": "f1c7ab6648e5fc2b65847bb48c3a18d4845b59e9a0bb02f3efd3163e9de53e55"
},
"downloads": -1,
"filename": "pavimentados-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d92da3435546dae0ad7e918a1fb81770",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 34330,
"upload_time": "2024-12-13T21:02:07",
"upload_time_iso_8601": "2024-12-13T21:02:07.076944Z",
"url": "https://files.pythonhosted.org/packages/e2/2e/0bfd8af5115b9b3c85078ca2707dbcae51d8fb914c8103c523c90d84ae87/pavimentados-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f92f680fe35537ae4e8156c6ecb289172f010f1928a4a84b9c9de4d2718b5062",
"md5": "075a32d6cd06450138a9894b37065611",
"sha256": "5d882142b43a1c15ede6ee66cf1cde33814b1735018dc1449711d24c0b76fcaf"
},
"downloads": -1,
"filename": "pavimentados-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "075a32d6cd06450138a9894b37065611",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 31617,
"upload_time": "2024-12-13T21:02:09",
"upload_time_iso_8601": "2024-12-13T21:02:09.940742Z",
"url": "https://files.pythonhosted.org/packages/f9/2f/680fe35537ae4e8156c6ecb289172f010f1928a4a84b9c9de4d2718b5062/pavimentados-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 21:02:09",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pavimentados"
}
JSON