PatchCollection

PatchCollection is a class in Matplotlib's collections module that aggregates multiple Patch objects into a single artist. Patch objects represent geometric shapes such as rectangles, circles, polygons. By bundling them, PatchCollection enables efficient rendering and unified styling when drawing many shapes on one axes.

Its primary purpose is performance optimization and convenient styling: instead of managing each patch separately, a single PatchCollection can be added to an Axes. Properties like facecolor, edgecolor, and linewidth can be configured for all patches. It also supports per-patch data by associating a scalar array with the collection and mapping it to colors via a colormap.

Typical workflow: create patches, create a PatchCollection from the list, configure color mapping if needed, and attach the collection to an Axes with the appropriate method. This approach is commonly used for visualizations that involve many small shapes, such as grid-based maps, mosaic plots, or heatmaps built from geometric cells.

Limitations include the need to manage the Patch objects themselves and ensure color data aligns with the patches. PatchCollection is part of Matplotlib's rendering pipeline and complements individual patch objects for large-scale visuals.