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

1. Create a virtual environment.

   python3 -m venv .venv

2. Activate the virtual environment.

   source .venv/bin/activate

3. Install tspng.

   python3 -m pip install tspng

4. 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.

5. 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

1. Install the application.

   python3 -m pip install .[cli]

2. Run the application.

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

3. (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

1. Clone this repository.

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

2. Create a virtual environment.

   python3 -m venv .venv

3. Activate the virtual environment.

   source .venv/bin/activate

4. Upgrade pip.

   python3 -m pip install --upgrade pip

5. Install all the dependencies.

   python3 -m pip install -e .[dev,cli]

6. Create a local branch.

   git checkout -b feature-awesome-new-feature

7. Modify the code.

8. Run the tests.

   pytest --color=yes

9. Commit changes to your local branch.

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

10. Push your local branch to GitHub to create a Pull Request (PR).

git push origin feature-awesome-new-feature

11. Create a Pull Request (PR) in GitHub.
12. Wait for CI to complete.
13. 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.