tspng 1.0.0

A Python package for manipulating PNG files with embedded JSON related to Machine Learning.

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
   {
   "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": ""
      }
   ]
   }
   

Contributing

1. Create a virtual environment.

   python3 -m venv .venv
   

2. Activate the virtual environment.

   source .venv/bin/activate
   

3. Clone this repository.

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

4. Install the dependencies.

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

5. Build the package.

   python3 -m build
   

Testing

Testing is divided into unit and integration tests. Unit tests are located in the package source code tree and are defined on a per-module basis with a test_<module>.py format, while the integration tests are defined in the tests directory.

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.