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.
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.
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).
Install the library using the following command:
pip install pavimentados
Next,
-
download the model from this link
-
Decompress it using the following command
tar -xzvf model_20240818.tar.gzIn 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.
- gpx: A file in GPX format
Once these elements are imported, the processor is instantiated as follows:
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.
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:
{
"paviment_model": {
"yolo_threshold": 0.20,
"yolo_iou": 0.45,
"yolo_max_detections": 100
},
"signal_model": {
"yolo_threshold": 0.40,
"yolo_iou": 0.45,
"yolo_max_detections": 100
}
}The workflow object receives the instantiated processor. Without it is not able to execute the workflow.
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:
results = workflow.execute(ml_processor,
batch_size=16,
video_output_file="processed_video.mp4"
)
video_output_fileandimage_folder_outputare 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.
# 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:
- table_summary_sections: DataFrame with summary table by sections.
- data_resulting: DataFrame with results per frame.
- data_resulting_fails: DataFrame with results by unique faults encountered.
- signals_summary : DataFrame with results by signal.
To see more details about the results please refer to this page.
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.
For information regarding the latest changes/updates in the library please refer to the changes document.
This package has been developed by:
Jose Maria Marquez Blanco
Joan Alberto Cerretani
Victor Durand
Copyright © [2025]. Inter-American Development Bank ("IDB"). Authorized Use.
The procedures and results obtained based on the execution of this software are those programmed by the developers and do not necessarily reflect the views of the IDB, its Board of Executive Directors or the countries it represents.
Copyright © [2025]. Banco Interamericano de Desarrollo ("BID"). Uso Autorizado.
Los procedimientos y resultados obtenidos con la ejecución de este software son los programados por los desarrolladores y no reflejan necesariamente las opiniones del BID, su Directorio Ejecutivo ni los países que representa.
Copyright © [2025]. Inter-American Development Bank ("IDB"). The Support and Usage Documentation is licensed under the Creative Commons License CC-BY 4.0 license. The opinions expressed in the Support and Usage Documentation are those of its authors and do not necessarily reflect the opinions of the IDB, its Board of Executive Directors, or the countries it represents.
Copyright © [2025]. Banco Interamericano de Desarrollo (BID). La Documentación de Soporte y Uso está licenciada bajo la licencia Creative Commons CC-BY 4.0. Las opiniones expresadas en la Documentación de Soporte y Uso son las de sus autores y no reflejan necesariamente las opiniones del BID, su Directorio Ejecutivo ni los países que representa.
The Software may include features which use, are powered by, or are an artificial intelligence system (“AI-Powered Services”), and as a result, the services provided via the Software may not be completely error-free or up to date. Additionally, the User acknowledges that due to the incorporation of AI-Powered Services in the Software, the Software may not dynamically (in “real time”) retrieve information and that, consequently, the output provided to the User may not account for events, updates, or other facts that have occurred or become available after the Software was trained. Accordingly, the User acknowledges that the use of the Software, and that any actions taken or reliance on such products, are at the User’s own risk, and the User acknowledges that the User must independently verify any information provided by the Software.
El Software puede incluir funciones que utilizan, están impulsadas por o son un sistema de inteligencia artificial (“Servicios Impulsados por IA”) y, como resultado, los servicios proporcionados a través del Software pueden no estar completamente libres de errores ni actualizados. Además, el Usuario reconoce que, debido a la incorporación de Servicios Impulsados por IA en el Software, este puede no recuperar información dinámicamente (en “tiempo real”) y que, en consecuencia, la información proporcionada al Usuario puede no reflejar eventos, actualizaciones u otros hechos que hayan ocurrido o estén disponibles después del entrenamiento del Software. En consecuencia, el Usuario reconoce que el uso del Software, y que cualquier acción realizada o la confianza depositada en dichos productos, se realiza bajo su propio riesgo, y reconoce que debe verificar de forma independiente cualquier información proporcionada por el Software.