tspng: A Python package for Computer Vision and Machine Learning metadata manipulation

A Python package for manipulating Portable Network Graphics (PNG) files with embedded JavaScript Object Notation (JSON) metadata from Machine Learning (ML) applications, such as the Theiascope™ platform for microscopy image analysis and quantitation. These files have data embedded in the PNG in a [COCO JSON format] compatible form. This package provides extraction of the JSON data and implantation of JSON data into existing PNGs.

Quick Start

Library

Create a virtual environment.
```
python3 -m venv .venv
```
Activate the virtual environment.
```
source .venv/bin/activate
```
Install tspng.
```
python3 -m pip install tspng
```
Create a png_dump.py script to extract inference results from a PNG file,
```
import json

from tspng.extraction import extract_from_file

print(json.dumps(extract_from_file(PATH_TO_FILE), indent=2))
```
where PATH_TO_FILE is replaced with the path to a .ts.png file on disk.

Run the png_dump.py script.

$ python3 ./png_dump.py
{
"info": {
  "description": "Theiascope image",
  "url": "http://www.theiascientific.com",
  "version": "1.0",
  "year": 2023,
  "contributor": "Theia Scientific, LLC",
  "date_created": "2023-05-10 19:22:47.722802+00:00"
},
"licenses": {
  "url": "http://www.theiascientific.com",
  "id": 1,
  "name": "Proprietary"
},
"images": [
  {
     "license": 1,
     "file_name": "20230510T192247Z.722_crimson-notebook (PML).ts.png",
     "height": 512,
     "width": 512,
     "date_captured": "2023-05-10 19:22:47.722802+00:00",
     "id": 3783,
     "field_of_view": [
     0,
     0,
     512,
     512
     ],
     "scale_bar": {
     "dimensions": [
        25,
        501,
        128,
        1
     ],
     "length": 100.0,
     "units_abbr": "nm",
     "units_name": "nanometers"
     }
  }
],
"annotations": [...],  // Omitted for clarity
"models": [
  {
     "id": 17,
     "configuration": {
     "image_processing": {
        "brightness": 0,
        "clahe": false,
        "contrast": 1.0,
        "gamma": 1.0,
        "gray": false,
        "invert": false
     },
     "max_concurrency": 2,
     "num_cpus": 0,
     "num_gpus": 1.0,
     "box_nms_thresh": 0.7,
     "crop_n_layers": 0,
     "crop_nms_thresh": 0.7,
     "crop_overlap_ratio": 0.3413333333333333,
     "crop_n_points_downscale_factor": 1,
     "min_mask_region_area": 0,
     "points_per_side": 32,
     "points_per_batch": 64,
     "pred_iou_thresh": 0.88,
     "stability_score_thresh": 0.95,
     "stability_score_offset": 1.0,
     "weights_file": {
        "filename": "sam_vit_b_01ec64.pth",
        "version": "default",
        "path": "/sam/vit-b"
     }
     },
     "created": "2023-05-09 19:46:18.309323+00:00",
     "family": "SAM",
     "name": "vit-b",
     "pid": 1
  }
],
"categories": [
  {
     "supercategory": "defect",
     "id": 1,
     "name": ""
  }
]
}

Application

Install the application.
```
python3 -m pip install .[cli]
```

Run the application.

$ tspng extract example.ts.png
{...}  // Omitted for clarity

(Optional) Use the jq utility to obtain specific fields and information from the extracted metadata. For example, to pretty print the output:
```
tspng extract example.ts.png | jq 
```

Contributing

Clone this repository.

git clone https://github.com/Theia-Scientific/tspng && cd tspng

Create a virtual environment.
```
python3 -m venv .venv
```
Activate the virtual environment.
```
source .venv/bin/activate
```
Upgrade pip.
```
python3 -m pip install --upgrade pip
```
Install all the dependencies.
```
python3 -m pip install -e .[dev,cli]
```

Create a local branch.

git checkout -b feature-awesome-new-feature

Modify the code.
Run the tests.
```
pytest --color=yes
```

Commit changes to your local branch.

git add -A && git commit -m "Add new feature"

Push your local branch to GitHub to create a Pull Request (PR).
```
git push origin feature-awesome-new-feature
```
Create a Pull Request (PR) in GitHub.
Wait for CI to complete.
Add comment to PR that it is ready to review.

License

LICENSE.

Acknowledgments

This material is based upon work supported by the U.S. Department of Energy, Office of Nuclear Energy under Award Number DE-SC0021529.

Theia-Scientific / tspng

readme