Skip to main content

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

Project description

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

CI Google Colab codecov

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
  1. Create a Pull Request (PR) in GitHub.
  2. Wait for CI to complete.
  3. Add comment to PR that it is ready to review.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tspng-1.1.0.tar.gz (704.2 kB view hashes)

Uploaded Source

Built Distribution

tspng-1.1.0-py3-none-any.whl (9.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page