{"id":18520092,"url":"https://github.com/thomashirtz/mosaic","last_synced_at":"2025-08-02T08:06:06.082Z","repository":{"id":225412627,"uuid":"765924409","full_name":"thomashirtz/mosaic","owner":"thomashirtz","description":"Python library for efficient rectangular decomposition of binary images using the Generalized Delta-Method.","archived":false,"fork":false,"pushed_at":"2024-03-07T08:54:47.000Z","size":87,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-14T17:12:10.755Z","etag":null,"topics":["binary-image","binary-images-decomposition","computer-vision","decomposition","gdm","generalized-delta-method","image-analysis","image-block-representation","image-processing","rectangular-decomposition","segmentation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thomashirtz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-01T22:20:43.000Z","updated_at":"2024-10-17T07:08:34.000Z","dependencies_parsed_at":"2024-03-07T09:48:23.884Z","dependency_job_id":"1f9540b3-b413-4944-bb29-d7d99a1893a6","html_url":"https://github.com/thomashirtz/mosaic","commit_stats":null,"previous_names":["thomashirtz/mosaic"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thomashirtz/mosaic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fmosaic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fmosaic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fmosaic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fmosaic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomashirtz","download_url":"https://codeload.github.com/thomashirtz/mosaic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fmosaic/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268351167,"owners_count":24236356,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["binary-image","binary-images-decomposition","computer-vision","decomposition","gdm","generalized-delta-method","image-analysis","image-block-representation","image-processing","rectangular-decomposition","segmentation"],"created_at":"2024-11-06T17:18:35.996Z","updated_at":"2025-08-02T08:06:06.028Z","avatar_url":"https://github.com/thomashirtz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `mosaic`\n\n`mosaic` is a Python library for performing rectangular decomposition of 2D binary images using the Generalized Delta-method (GDM) technique. This technique, proposed by Spiliotis and Mertzios in their paper [\"Real-time computation of two-dimensional moments on binary images using image block representation\"](https://ieeexplore.ieee.org/document/725368), allows for efficient identification and grouping of contiguous foreground regions into rectangular blocks.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"450\" alt=\"Example from the 99-Shape Database of the LEMS at Brown University\" src=\"./scripts/output.png\"\u003e\n\u003c/div\u003e\n\nFurther research and comparisons conducted by Suk et al. in their paper [\"Rectangular Decomposition of Binary Images\"](https://library.utia.cas.cz/separaty/2012/ZOI/suk-rectangular%20decomposition%20of%20binary%20images.pdf) have underscored the exceptional efficiency of the GDM technique. Their studies, which benchmarked various methods for binary image decomposition, concluded that the approach adopted by Spiliotis and Mertzios stands out for its optimal balance between computational speed and the quality of results. This makes this repository not only a powerful tool for image analysis tasks but also the preferred choice for applications demanding high performance and accuracy.\n\n## How the Algorithm Works\n\n\u003cimg align=\"right\" width=\"150\"  src=\"illustration.png\"\u003e\nThe GDM technique utilizes a step-by-step process to decompose 2D binary images into rectangular blocks. Here's a breakdown of how the algorithm operates:  \n\u003cbr/\u003e\u003cbr/\u003e  \n\n**Step 1: Identifying Object Level Intervals**  \nFor each line `y` in the image, the algorithm identifies intervals of contiguous foreground pixels, referred to as \"object level intervals.\"\n\n**Step 2: Comparing Intervals with Previous Blocks**  \nThe algorithm then compares these intervals to existing blocks that were identified up to the previous line (`y - 1`). This step determines if an interval is part of an existing block or if it marks the start of a new block.\n\n**Step 3: Initiating New Blocks**  \nIf an interval does not align with any existing block, it signifies the start of a new block. This new block is initialized based on the interval's position.\n\n**Step 4: Extending Existing Blocks**  \nWhen an interval matches with an existing block, the algorithm extends the block to include the new interval, marking the block's end at line `y`.\n\nThis iterative process allows this algorithm to efficiently group contiguous foreground regions into rectangular blocks, optimizing both the speed and accuracy of binary image decomposition.\n\n\n## Installation\n\nYou can install Mosaic using pip:\n\n```\npip install git+https://github.com/thomashirtz/mosaic#egg=mosaic\n```\n\n## Quick Start\n\nGet started with just a few lines of code. This simple example demonstrates how to perform rectangular decomposition on a binary image:\n\n```python\nfrom mosaic import rectangular_decomposition\nimport numpy as np\n\n# Example binary image (replace with your own)\nimage = np.random.randint(2, size=(100, 100), dtype=bool)\nrectangles = rectangular_decomposition(image)\n\nprint(\"Identified rectangles:\", rectangles)\n```\n\nTo see `mosaic` in action, including how to use the visualization functionality, check out the [example script](scripts/example.py). This script guides you through reading a binary image, performing decomposition, and visualizing the results.\n\n## Usage\n\n### Single Image Decomposition\nTo perform rectangular decomposition on a single binary image, you can use the `rectangular_decomposition` function:\n\n```python\nfrom mosaic import rectangular_decomposition\n\nimage = ...  # Your binary image as a 2D NumPy array\nrectangles = rectangular_decomposition(image)\n```\n\nThis function returns a list of Rectangle, where each tuple represents a rectangular block identified within the image.\n\n### Batch Processing\nMosaic also provides a function for processing a batch of binary images:\n\n```python\nfrom mosaic import batch_rectangular_decomposition\n\nimage_batch = ...  # Your batch of binary images\nbatch_results = batch_rectangular_decomposition(image_batch)\n```\n\nThis function accepts a batch of binary images as input and returns a list of lists, where each inner list contains Rectangle namedtuples for the corresponding image in the batch.\n\n### Visualizing Results\n\nVisualize the decomposition of an image to better understand the process and results of the `mosaic` library. This functionality not only aids in verifying the effectiveness of the rectangular decomposition but also provides insightful visual feedback that can be used for presentations or further analysis.\n\n```python\nfrom mosaic.utilities import plot_image_decomposition\n\n# Assuming 'binary_image' and 'rectangle_list' are already defined\nplot_image_decomposition(binary_image, rectangle_list)\n```\n\nLeverage this visualization tool to explore how different binary images are decomposed into rectangular blocks. This can be particularly useful for understanding the library's behavior on complex images, thereby enhancing your overall image processing workflow.\n\n## License\n\n     Copyright 2024 Thomas Hirtz\n\n     Licensed under the Apache License, Version 2.0 (the \"License\");\n     you may not use this file except in compliance with the License.\n     You may obtain a copy of the License at\n\n         http://www.apache.org/licenses/LICENSE-2.0\n\n     Unless required by applicable law or agreed to in writing, software\n     distributed under the License is distributed on an \"AS IS\" BASIS,\n     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n     See the License for the specific language governing permissions and\n     limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomashirtz%2Fmosaic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomashirtz%2Fmosaic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomashirtz%2Fmosaic/lists"}