{"id":27873296,"url":"https://github.com/wpbonelli/pytcherplants","last_synced_at":"2026-04-30T10:09:20.524Z","repository":{"id":62592076,"uuid":"425266049","full_name":"wpbonelli/pytcherplants","owner":"wpbonelli","description":"analyze top-down images of Sarracenia","archived":false,"fork":false,"pushed_at":"2022-06-14T13:18:43.000Z","size":344313,"stargazers_count":2,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-05T01:08:56.815Z","etag":null,"topics":["color-analysis","image-processing","python","segmentation"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wpbonelli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-06T14:34:31.000Z","updated_at":"2022-07-13T03:43:44.000Z","dependencies_parsed_at":"2022-11-03T23:30:23.227Z","dependency_job_id":null,"html_url":"https://github.com/wpbonelli/pytcherplants","commit_stats":null,"previous_names":["wpbonelli/pytcherplants","w-bonelli/pytcherplants"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpbonelli%2Fpytcherplants","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpbonelli%2Fpytcherplants/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpbonelli%2Fpytcherplants/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpbonelli%2Fpytcherplants/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wpbonelli","download_url":"https://codeload.github.com/wpbonelli/pytcherplants/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252420954,"owners_count":21745154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color-analysis","image-processing","python","segmentation"],"created_at":"2025-05-05T01:09:04.787Z","updated_at":"2026-04-30T10:09:15.457Z","avatar_url":"https://github.com/wpbonelli.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sarracenia pitcher plants\n\n[![CI](https://github.com/w-bonelli/pytcherplants/actions/workflows/ci.yaml/badge.svg)](https://github.com/w-bonelli/pytcherplants/actions/workflows/ci.yaml)\n[![Coverage Status](https://coveralls.io/repos/github/w-bonelli/pytcherplants/badge.svg?branch=main)](https://coveralls.io/github/w-bonelli/pytcherplants?branch=main)\n\n\nTrait and color analysis for top-down images of pitcher plants, built with [ilastik](https://www.ilastik.org/), [OpenCV](https://github.com/opencv/opencv-python), and [Deep Plant Phenomics](https://github.com/p2irc/deepplantphenomics). Developed for images obtained from an experiment performed by [Mason McNair](https://github.com/mmcnair91) at the University of Georgia.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n\n- [About](#about)\n  - [Layout](#layout)\n  - [References](#references)\n- [Installation](#installation)\n  - [Using Docker](#using-docker)\n  - [Using Singularity](#using-singularity)\n  - [Installing the Python package](#installing-the-python-package)\n  - [Jupyter notebooks](#jupyter-notebooks)\n  - [Setting up a development environment](#setting-up-a-development-environment)\n    - [Developing with Docker](#developing-with-docker)\n    - [Using a virtual Python environment](#using-a-virtual-python-environment)\n      - [`venv`](#venv)\n      - [Anaconda](#anaconda)\n- [Usage](#usage)\n  - [Image name format](#image-name-format)\n  - [Commands](#commands)\n    - [Pixel classification](#pixel-classification)\n    - [Plant segmentation](#plant-segmentation)\n    - [Color analysis](#color-analysis)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## About\n\nThis repository does a few things:\n\n- pixel classification\n- plant segmentation\n- color distribution analysis\n\n| Pixel Classification | Plant Segmentation             |            Color Analysis             | \n|:----------------------------:|:----------------------------:|:-------------------------------------:|\n| ![](samples/groups/1_14_19.10_30_20.5V4B3121.masked.jpg) | ![](media/cont.png)  | ![](media/rad.png) ![](media/rgb.png) |\n\n### Layout\n\nSome sample images and data are included in `samples`. The Python module and CLI are defined in `pytcherplants`. Analysis is in `notebooks`.\n\n### References\n\nPixel classification (via [Ilastik](https://www.ilastik.org/)) adapted from [Peter Pietrzyk's](https://github.com/PeterPieGH) [DIRTmu](https://github.com/Computational-Plant-Science/DIRTmu). Segmentation and analysis adapted from [SMART](https://github.com/Computational-Plant-Science/SMART) by [Suxing Liu](https://github.com/lsx1980).\n\n## Installation\n\nDocker or Singularity are recommended to run this project. The Ilastik pixel classification model necessary for certain commands is baked into the Docker image definition.\n\n### Using Docker\n\nThe Docker image is available on Docker Hub at [`wbonelli/pytcherplants`](https://hub.docker.com/r/wbonelli/pytcherplants). To open an interactive shell with your current working directory mounted to `/opt/dev` inside the container:\n\n```shell\ndocker run -it -v $(pwd):/opt/dev -w /opt/dev wbonelli/pytcherplants bash\n```\n\n### Using Singularity\n\nTo open an interactive shell:\n\n```shell\nsingularity shell wbonelli/pytcherplants\n```\n\nNote that Singularity automatically mounts the current working directory; there is no need to manually load a volume.\n\n### Installing the Python package\n\nThe `pytcherplants` Python package can be installed with pip, e.g. `pip install pytcherplants`. **Note that the pixel classification commands expect Ilastik to be installed at `/opt/ilastik/ilastik-1.4.0b21-gpu-Linux/`.**\n\n### Jupyter notebooks\n\nTo run a local Jupyter notebook server from a suitable python environment (i.e., with `jupyter` and all the dependencies in `requirements.txt` installed; see below):\n\n```shell\njupyter notebook --allow-root\n```\n\nThe [Jupyter UI](https://jupyter.org/documentation) should automatically open. Then navigate to the `notebooks` directory to open a notebook.\n\n### Setting up a development environment\n\nClone the repo with `git clone https://github.com/w-bonelli/pitcherplants.git`. \n\n#### Developing with Docker\n\nThe Docker image can be built from the project root with `docker build -t \u003cimage tag\u003e -f Dockerfile .`.\n\n#### Using a virtual Python environment\n\nAlternatively, a virtual environment can be used.\n\n##### `venv`\n\nFirst use `python3 -m venv` to create a virtual environment. Then activate it with `source bin/activate` and install dependencies with pip: `pip install -r requirements.txt`. Deactivate the environment with `source deactivate`.\n\n##### Anaconda\n\nFirst create an environment:\n\n```shell\nconda create --name \u003cenvironment name\u003e --file requirements.txt python=3.8 anaconda\n```\n\nAny Python3.6+ should support the dependencies in `requirements.txt`. The environment can be activated with `source activate \u003cyour environment name\u003e` and deactivated with `source deactivate`.\n\n## Usage\n\nThe Python CLI includes commands for processing individual image files, directories of images, and CSV files containing aggregate data.\n\n### Image name format\n\nThe various CLI commands expect image file names to conform to `date.treatment.name.ext`, where dates are `_`-delimited triples `%m_%d_%y`. For instance:\n\n- `10_14_19.Calmag.p003.jpg`\n- `1_14_19.Control.p008.JPG`\n\n### Commands\n\nThere are two commands:\n\n- `classify`\n- `segment`\n- `analyze`\n\n#### Pixel classification\n\nTo classify foreground (plant tissue) and background pixels in an image (i.e. to segment the plant from its surroundings), use the `classify` command:\n\n```shell\npypl classify -i \u003cimage file\u003e -o \u003coutput directory\u003e\n```\n\nBy default JPG, PNG, and TIFF files are supported. You can select one or the other by passing e.g. `png` or `jpg` to the `--filetypes` flag (shorthand `-ft`).\n\n#### Plant segmentation\n\n```shell\npypl segment -i \u003cimage file\u003e -o \u003coutput directory\u003e\n```\n\nYou can specify the number of plants per image by providing an integer argument `-c (--count)`, as well as the minimum contour area argument `-m (--min_area)`. The former defaults to 1. If the latter is absent, no minimum is applied.\n\nThis will produce an output image `\u003coutput directory\u003e/\u003cimage file stem\u003e.plants.jpg` with each contour labelled, as well as one or more output images e.g. `\u003coutput directory\u003e/\u003cimage file stem\u003e.plant.0.jpg`, as many as there were plants detected in the input image.\n\n#### Color analysis\n\nUse the `analyze` command to analyze an image's distribution. The image is assumed to have already been segmented and cropped, with background pixels either white or black. The image may contain any number of foreground contours (individual plants).\n\n```shell\npypl analyze -i \u003cmasked image file\u003e -o \u003coutput directory\u003e\n```\n\nTo explicitly set the number of clusters for k-means clustering, use the `-k (--clusters)` flag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpbonelli%2Fpytcherplants","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwpbonelli%2Fpytcherplants","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpbonelli%2Fpytcherplants/lists"}