petroscope

Petroscope is a python package to analyze and work with microscopic geological images.

Installation (outdated)

Download wheels distro from the GitHub releases page then install it:

python -m pip install petroscope-0.0.11-py3-none-any.whl

Or you can install the package from PyPI:

pip install petroscope

The minimal required Python version is 3.10.

Acknowledgements

The development of methods for processing and analyzing of geological images implemented in this package was supported by the Russian Science Foundation (grant No. 24-21-00061).

Contributors

The following researchers have contributed to the development of petroscope:

• Alexander Khvostikov | ORCID: 0000-0002-4217-7141 | ResearchGate
• Gleb Nikolaev | ORCID: 0009-0003-0814-3997
• Svetlana Krasnova

Calibration module

The Calibration module automatically corrects illumination and distortion in microscopic geological images using reference calibration images. These reference images can be:

• OLED/AMOLED screen images (for uniform illumination correction)
• Mirror images (for reflection-based illumination correction)

Example Usage (predefined script)

To run the calibration process from the command line, navigate to the example data directory and execute:

cd examples/data/
python -m petroscope.calibrate.run -i ./calibration_test -o ./calibration_test_out -m ./mirror1200.jpg

Using in Python Code

If you prefer to use the module programmatically, check out the provided example script.

Segmentation module

This module is dedicated to image segmentation. It contains a number of helpful utils for segmentation related tasks, abstract class GeoSegmModel, classes to perform segmentation evaluation and metrics calculation.

This module is designed primarily to be used with LumenStone dataset, collected and annotated by our team. Annotation labels for this dataset are provided in LumenStoneClasses class.

Segmentation metrics

IoU per class, mean IoU, total accuracy metrics are used for segmentation evaluation. For the correct calculation of these metrics, it is necessary to use information about the areas of all objects in the dataset, not just in individual images. These calculations are implemented in metrics.py.

Patch-sampling balancer

One of the main challenges in developing segmentation methods for geological images of polished sections is the severe class imbalance in datasets for minerals, which naturally occurs due to the varying frequencies of mineral occurrence in nature. Some minerals may appear as small clusters of only a few dozen pixels, while others may occupy a large portion of the images.

Training neural network segmentation models directly on such data leads to extremely poor results. It has also been empirically shown that using various loss functions focused on class imbalance and class weighting does not yield the desired results in this case.

To address class imbalance, a simple yet quite effective patch-based sampling method was proposed, leaning on constructing probability maps of mineral occurrence in the dataset. The implementation is presented in SelfBalancingDataset class.

References

The implemented patch-based balancer is inspired by our previous works:

• Alexey Kochkarev, Alexander Khvostikov, Dmitry Korshunov, Andrey Krylov, and Mikhail Boguslavskiy. Data balancing method for training segmentation neural networks. CEUR Workshop Proceedings, 2744:1–10, 2020. DOI;

• Zh Sun, A. Khvostikov, A. S. Krylov, A. Sethi, I. Mikhailov, and P. Malkov. Joint super-resolution and tissue patch classification for whole slide histological images. Programming and Computer Software, 50(3):257–263, 2024 DOI;

Example of usage

• segm_balancer.py - an example of sampling patches from the dataset with simple augmentations, visualizing the probability maps of classes and the obtained accumulators.

ResUnet segmentation model

ResUnet is the base mineral segmentation model which is built upon the UNet architecture with residual conv blocks. It was trained on LumenStone S1v1 dataset for 7 segmenting classes.

To use this model you have to install pytorch.

Achieved metrics for LumenStone S1v1 (to be updated)

Examples of usage

• segm_resunet_inference.py - an example of using ResUnet model for inference (making prediction for one image);

• segm_cnn_test.py - a more detailed example demonstrating the testing of ResUnet model on LumenStone S1v1 dataset with calculating of all metrics;

Panorama module

The panorama module is based on the automatic panoramic image stitching method that produces highly detailed panoramic images from a sequence of partially overlapping images of polished sections.

At the moment the module is available in the experimental branch panoramas.

References

The proposed method of panorama stitching is described in:

• Nikolaev, G., Korshunov, D., and Khvostikov, A.: Automatic stitching of panoramas for geological images of polished sections, ISPRS Ann. Photogramm. Remote Sens. Spatial Inf. Sci., X-2/W1-2024, 39–46, 2024. DOI