{"id":31296725,"url":"https://github.com/mthiboust/array2image","last_synced_at":"2026-05-15T13:31:16.352Z","repository":{"id":208602527,"uuid":"719614214","full_name":"mthiboust/array2image","owner":"mthiboust","description":"Converts a Numpy array to a PIL image.","archived":false,"fork":false,"pushed_at":"2023-11-22T08:57:46.000Z","size":1017,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-25T08:24:31.275Z","etag":null,"topics":["array","data-visualization","image","numpy","pillow","plotting","python"],"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/mthiboust.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}},"created_at":"2023-11-16T14:39:36.000Z","updated_at":"2023-11-22T09:00:51.000Z","dependencies_parsed_at":"2023-11-22T11:26:06.546Z","dependency_job_id":"0c9e63d0-c452-4a77-aad2-bdd99c8d7dca","html_url":"https://github.com/mthiboust/array2image","commit_stats":null,"previous_names":["mthiboust/array2image"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mthiboust/array2image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthiboust%2Farray2image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthiboust%2Farray2image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthiboust%2Farray2image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthiboust%2Farray2image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mthiboust","download_url":"https://codeload.github.com/mthiboust/array2image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mthiboust%2Farray2image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33068331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["array","data-visualization","image","numpy","pillow","plotting","python"],"created_at":"2025-09-24T21:02:44.576Z","updated_at":"2026-05-15T13:31:16.340Z","avatar_url":"https://github.com/mthiboust.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Array2image\n\n***Array2image*** helps you convert Numpy arrays to PIL images. It comes with a single function `array_to_image()`.\n\nWhen given an array, it automatically guesses its spatial and channel dimensions. Spatial dimensions greater than 2 are considered as images of images. The resulting image is then represented differently depending on the channel dimension:\n* 1D channel: greyscale image.\n* 2D channel: image with varying hue and saturation.\n* 3D channel: RGB image.\n\nIf specified, custom colormap functions can be used instead. For instance:\n* `matplotlib.cm.*` functions for 1D channel arrays (like `matplotlib.cm.viridis`)\n* `colormap2d.*` functions for 2D channel arrays (like `colormap2d.pinwheel`)\n* The `matplotlib.colors.hsv_to_rgb` function for 3D channel arrays.`\n\nIt assumes that values are floats between 0 and 1 or integers between 0 and 255 (values are clipped anyway). If specified, it automatically normalizes the values.\n\nWhy not directly use `matplotlib.plt.imshow` instead? If you have 2D array with 1 or 3-channel data and don't care about the size nor the incrusted axis in the returned image, `matplotlib.plt.imshow` is great. The ***Array2image*** library makes the focus on simplicity by guessing an appropriate way of rendering non-generic arrays. \n\n# Installation\n\n```bash\npip install array2image\n```\n\nRequires python 3.10+.\n\n# Documentation\n\n### Function signature\n```python\ndef array_to_image(\n    arr,\n    spatial_dims: tuple[int, ...] | None = None,\n    channel_dim: int | None = None,\n    cmap: Callable | None = None,\n    inverted_colors: bool = False,\n    bin_size: int | tuple[int, int] | None = None,\n    target_total_size: int = 200,\n    grid_thickness: int | tuple[int, ...] = 0,\n    norm: bool = False,\n) -\u003e PIL.Image\n```\n\n### Argument description\n\n* **arr**: Array-like to be converted.\n* **spatial_dims**: Spatial dimensions of the array. If None, spatial dimensions are\nautomatically guessed.\n* **channel_dim**: Channel dimension of the array. Only 1, 2 or 3 channel dimension\narrays can be converted to an image. If None, the channel dimension is\nautomatically guessed.\n* **cmap**: Colormap function to be used if provided. If None, default built-in\nfunctions are used.\n* **inverted_colors**: If True, inverts the color of the image.\n* **bin_size**: Number of pixels for each array spatial element.\ntarget_total_size: Target size of the image. Used to automatically choose\n`bin_size` if the latter is None.\n* **grid_thickness**: Tuple of grid thickness for each level of 2D spatial dimensions.\nBy default, it is 0 for the last 2D dimensions and 2 pixels for the others.\n* **norm**: If True, normalize values between 0 and 1 with a min-max normalization.\n\n# Examples\n\n## 1-channel arrays\n\nData for the following examples:\n```python\nimport numpy as np\n\n# Random data: A 2x4x10x8 Numpy array with random values between 0 and 1\nnp.random.seed(0)\narray = np.random.uniform(0, 1, (2, 4, 10, 8))\n\n# MNIST data: The first 48 MNIST digits organized in a 6x8 grid.\nmnist_data = ...\narray = mnist_data[:48].reshape(6, 8, 28, 28)\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003c/td\u003e\n\u003ctd\u003eRandom\u003c/td\u003e\n\u003ctd\u003eMNIST\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Represent only a 4D array\nimage = array_to_image(array)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_random.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_mnist_6_8_28_28.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Force 0 pixel for all grid levels\nimage = array_to_image(\n  array, \n  grid_thickness=(0, 0)\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_random_grid_0_0.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_mnist_6_8_28_28_grid_0_0.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Invert colors\nimage = array_to_image(\n  array, \n  inverted_colors=True\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_random_grid_0_0_inverted_colors.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_mnist_6_8_28_28_inverted_colors.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\nimport matplotlib\n\n# Use an external colormap\nimage = array_to_image(\n  array,\n  cmap=matplotlib.cm.viridis\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_random_grid_0_0_cmap_viridis.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/8b448f9e3a55961c31c6035a365c9a03d56482d6/docs/a2i_mnist_6_8_28_28_cmap_viridis.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\nimport matplotlib\n\n# Represent only a 2D array\nimage = array_to_image(\n  array[0, 0], \n  cmap=matplotlib.cm.viridis\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_random_0_0_cmap_viridis.png\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_mnist_28_28.png\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\nimport matplotlib\n\n# Show a grid\nimage = array_to_image(\n  array[0, 0], \n  cmap=matplotlib.cm.viridis, \n  grid_thickness=1\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_random_0_0_cmap_viridis_grid_1.png\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_mnist_28_28_grid_1.png\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Fix the bin size\nimage = array_to_image(\n  array[0, 0], \n  bin_size=4\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_random_0_0_bin_2.png\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_mnist_28_28_grid_1_bin_4.png\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Fix a specific asymetric bin size\nimage = array_to_image(\n  array[0, 0], \n  bin_size=(4,8)\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_random_0_0_bin_2_4.png\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/9b25a4e2db5db8402058b9f6651894b82cf264ce/docs/a2i_mnist_28_28_grid_1_bin_4_8.png\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## 2-channel arrays\n\n\nData for the following examples:\n```python\nimport numpy as np\n\n# Random data: A 10x10x2 Numpy array with random values between 0 and 1\nnp.random.seed(0)\narray = np.random.uniform(0, 1, (10, 10, 2))\n\n# Dummy fourier data: linearly varying phase and magnitude over a 2D grid\nphase, amplitude = np.meshgrid(np.linspace(0,1,10), np.meshgrid(np.linspace(0,1,10)))\narray = np.stack((phase, amplitude), axis=-1)\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003c/td\u003e\n\u003ctd\u003eRandom\u003c/td\u003e\n\u003ctd\u003eFourier\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Default Hue/Saturation colormap\nimage = array_to_image(array)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/072db6c96721efcdc0171b4d579679786b456f69/docs/a2i_2c_random.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/072db6c96721efcdc0171b4d579679786b456f69/docs/a2i_2c_fourier.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\nimport colormap2d\n\n# External 2D colormap\narray_to_image(\n  array, \n  cmap=colormap2d.pinwheel\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/072db6c96721efcdc0171b4d579679786b456f69/docs/a2i_2c_random_cmap.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/072db6c96721efcdc0171b4d579679786b456f69/docs/a2i_2c_fourier_cmap.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/table\u003e\n\n## 3-channel arrays\n\nData for the following examples:\n```python\nimport numpy as np\n\n# Random data: A 10x10x3 Numpy array with random values between 0 and 1\nnp.random.seed(0)\narray = np.random.uniform(0, 1, (10, 10, 3))\n\n# The Lena RGB image\nimage = Image.open(\"lena.png\")\narray = np.asarray(image)\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\u003c/td\u003e\n\u003ctd\u003eRandom\u003c/td\u003e\n\u003ctd\u003eLena\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\n\n# Default RGB colormap\nimage = array_to_image(array)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/4eedddcd31a63ed7f9f893cb474a99b89c555642/docs/a2i_3c_random.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/4eedddcd31a63ed7f9f893cb474a99b89c555642/docs/a2i_3c_lena.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```python\nfrom array2image import array_to_image\nimport matplotlib\n\n# External 3D colormap\narray_to_image(\n  array, \n  cmap=matplotlib.colors.hsv_to_rgb\n)\n```\n\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/4eedddcd31a63ed7f9f893cb474a99b89c555642/docs/a2i_3c_random_cmap.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003ctd\u003e \n\u003cimg src=\"https://github.com/mthiboust/array2image/blob/4eedddcd31a63ed7f9f893cb474a99b89c555642/docs/a2i_3c_lena_cmap.png\" width=\"200px\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\n\u003c/table\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmthiboust%2Farray2image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmthiboust%2Farray2image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmthiboust%2Farray2image/lists"}