enzoribeirodev/petrou

Petrou is a Python library aimed at a specific task in image processing: figuring out the best way to split a grayscale image into two or more regions, usually foreground and background, a step called thresholding or segmentation. Instead of picking one fixed method, it gives the user several different ways to define what counts as a good threshold, and several different algorithms to search for the best value. The library implements three thresholding criteria drawn from image processing research: Otsu, Tsallis, and MASI. Each one is a mathematical rule for scoring how well a candidate threshold separates an image into meaningful parts. To find the best threshold according to one of these rules, petrou offers three search strategies: checking every possible value directly, simulated annealing, and particle swarm optimization. All of these share one common building block called SearchSpace, which describes the variables being searched over, their allowed ranges, and how much to nudge them when exploring nearby options. Because every optimizer works through this same interface, adding a new search algorithm or a new scoring rule later does not require rewriting the others. Beyond finding a threshold, petrou also includes tools to check how good a segmentation actually is, using standard metrics such as the Jaccard index and Dice coefficient, which compare a result against a known correct answer. It also has a smaller utility for extracting pixel values along a straight line drawn across an image, using the Bresenham line algorithm, with an optional visual overlay if the extra plotting dependency is installed. The library is installed with pip and is organized into clear submodules for optimization, scoring objectives, thresholding, metrics, and this line profiling tool, with a simple layering rule so that lower level pieces never depend on higher level ones. It also documents how a developer could add their own new optimizer or new scoring criterion. This project is best suited to people already working in image processing, computer vision research, or scientific computing who need fine control over how thresholds are chosen and evaluated, rather than someone looking for a simple one line image filter. The full README is longer than what was shown.