{"id":19112750,"url":"https://github.com/pgrit/simpleimageio","last_synced_at":"2026-03-09T11:05:16.102Z","repository":{"id":45132552,"uuid":"328465660","full_name":"pgrit/SimpleImageIO","owner":"pgrit","description":"A very simple C# / Python wrapper to read and write various HDR and LDR image file formats.","archived":false,"fork":false,"pushed_at":"2025-04-25T15:28:19.000Z","size":119113,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-30T22:14:41.215Z","etag":null,"topics":["dotnet","exr","hdr","image","python"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgrit.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":"2021-01-10T19:47:16.000Z","updated_at":"2025-04-25T15:28:23.000Z","dependencies_parsed_at":"2025-04-19T00:33:06.197Z","dependency_job_id":"13dc215e-9c27-4704-ad97-c0fb1fc08b80","html_url":"https://github.com/pgrit/SimpleImageIO","commit_stats":{"total_commits":225,"total_committers":3,"mean_commits":75.0,"dds":"0.026666666666666616","last_synced_commit":"ea37e62a7695d1dd66b7606b7c7be2fc72dc8eb4"},"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgrit%2FSimpleImageIO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgrit%2FSimpleImageIO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgrit%2FSimpleImageIO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgrit%2FSimpleImageIO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgrit","download_url":"https://codeload.github.com/pgrit/SimpleImageIO/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251789618,"owners_count":21644086,"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":["dotnet","exr","hdr","image","python"],"created_at":"2024-11-09T04:34:01.260Z","updated_at":"2026-03-09T11:05:16.064Z","avatar_url":"https://github.com/pgrit.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Build](https://github.com/pgrit/SimpleImageIO/workflows/Build/badge.svg)\n\u003ca href=\"https://www.nuget.org/packages/SimpleImageIO/\"\u003e\n![NuGet Version](https://img.shields.io/nuget/v/SimpleImageIO)\n\u003c/a\u003e\n\n# Simple Image IO\n\nA lightweight C# and Python wrapper to read and write RGB images from / to various file formats.\nSupports .exr (with layers) via [tinyexr](https://github.com/syoyo/tinyexr) and a number of other formats (including .png, .jpg, and .bmp) via [stb_image](https://github.com/nothings/stb/blob/master/stb_image.h) and [stb_image_write](https://github.com/nothings/stb/blob/master/stb_image_write.h).\nA subset of TIFF can be read and written via [tinydngloader](https://github.com/syoyo/tinydngloader).\nWe also implement our own importer and exporter for [PFM](http://www.pauldebevec.com/Research/HDR/PFM/).\nIn addition, the package offers some basic image manipulation functionality, error metrics, and tone mapping.\n\nThe C# wrapper further offers utilities for thread-safe atomic splatting of pixel values, and sending image data to the [tev](https://github.com/Tom94/tev) viewer via sockets. It also contains a very basic wrapper around [Intel Open Image Denoise](https://github.com/OpenImageDenoise/oidn).\n\nThe [**Nuget package**](https://www.nuget.org/packages/SimpleImageIO/) contains prebuilt binaries of the C++ wrapper for x86-64 Windows, Ubuntu, and macOS ([.github/workflows/build.yml](.github/workflows/build.yml)).\nThe [**Python package**](https://pypi.org/project/SimpleImageIO/) is set up to automatically download an adequate CMake version and compile the C++ code on any platform.\n\nExcept for the optional Intel Open Image Denoise, all dependencies are header-only and unintrusive, so this library should work pretty much anywhere without any hassle.\n\n## Usage example (C#)\n\nThe following creates a one pixel image and writes it to various file formats:\n\n```C#\nRgbImage img = new(width: 1, height: 1);\nimg.SetPixel(0, 0, new(0.1f, 0.4f, 0.9f));\nimg.WriteToFile(\"test.exr\");\nimg.WriteToFile(\"test.png\");\nimg.WriteToFile(\"test.jpg\");\n```\n\nReading an image from one of the supported formats is equally simple:\n```C#\nRgbImage img = new(\"test.exr\");\nConsole.WriteLine(img.GetPixel(0, 0).Luminance);\n```\n\nThe pixel coordinate (0,0) corresponds to the top left corner of the image. Coordinates outside the valid range are clamped automatically; no error is raised. The framework also offers a `MonochromeImage` with a single channel per pixel. Further, the base class `ImageBase` can be used directly for images with arbitrary channel count (`RgbImage` and `MonochromeImage` only add some convenience functions like directly returning an `RgbColor` object).\n\nAs an added bonus, the C# wrapper can connect to the [tev](https://github.com/Tom94/tev) HDR viewer and directly display image data via sockets. The following example generates a monochrome image and sends it to tev:\n\n```C#\nTevIpc tevIpc = new(); // uses tev's default port on localhost\n\n// Create the image and initialize a tev sync\nMonochromeImage image = new(width: 20, height: 10);\ntevIpc.CreateImageSync(\"MyAwesomeImage\", 20, 10, (\"\", image));\n\n// Pretend we are a renderer and write some image data.\nimage.SetPixel(0, 0, val: 1);\nimage.SetPixel(10, 0, val: 2);\nimage.SetPixel(0, 9, val: 5);\nimage.SetPixel(10, 9, val: 10);\n\n// Tell the TevIpc class to update the image displayed by tev\n// (this currently retransmitts all pixel values)\ntevIpc.UpdateImage(\"MyAwesomeImage\");\n```\n\n## Usage example (Python)\n\nThe following creates a one pixel image, writes it to various file formats, reads one of them back in, and prints the red color channel of the pixel.\nThe result is then sent to the [tev](https://github.com/Tom94/tev) HDR viewer via sockets (modified version of https://gist.github.com/tomasiser/5e3bacd72df30f7efc3037cb95a039d3).\n\n```Python\nimport simpleimageio as sio\nsio.write(\"test.exr\", [[[0.1, 0.4, 0.9]]])\nsio.write(\"test.png\", [[[0.1, 0.4, 0.9]]])\nsio.write(\"test.jpg\", [[[0.1, 0.4, 0.9]]])\nimg = sio.read(\"test.exr\")\nprint(img[0,0,0])\n\nwith sio.TevIpc() as tev:\n    tev.display_image(\"image\", img)\n    tev.display_layered_image(\"layers\", { \"stuff\": img, \"morestuff\": img })\n```\n\nIn Python, an image is a 3D row-major array, where `[0,0,0]` is the red color channel of the top left corner.\nThe convention is compatible with most other libraries that make use of numpy arrays for image representation, like matplotlib.\n\n## Flip books for Jupyter and web\n\nBoth, the Python and the .NET library can generate an interactive HTML viewer to display and compare images visually by flipping between them. See [FlipBookExample.dib](FlipBookExample.dib) for an example with .NET interactive and C\\#, [FlipBookExample.fsx](FlipBookExample.fsx) for a static webpage generator with F\\#, or [flipbook.ipynb](flipbook.ipynb) for a Jupyter notebook with Python.\n\n![](FlipBook.gif)\n\n## Building from source\n\nIf you are on an architecture different from x86-64, you will need to compile the C++ wrapper from source.\nBelow, you can find instructions on how to accomplish that.\n\n### Dependencies\n\nAll dependencies *except OIDN* are header-only and included in the repository. Building requires\n- a C++20 compiler\n- CMake\n- [.NET 6.0](https://dotnet.microsoft.com/) (or newer)\n- Python \u0026geq; 3.6\n\n### Building the C# wrapper - quick and simple\n\n```\npwsh ./make.ps1\n```\n\nDownloads precompiled binaries for Open Image Denoise, copies them to the correct directory, builds the C++ code and then builds and tests the C# wrapper.\n\n### Building the C# wrapper - manually\n\nBuild the C++ low level library with [CMake](https://cmake.org/):\n```\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release\ncmake --build . --config Release\ncd ..\n```\n\nIf you want to use the `Denoiser` class, compiled binaries of Open Image Denoise must be in the correct `runtimes` folder. For example, on x64 Linux, there should be a `libOpenImageDenoise.so` in `runtimes/linux-x64/native/`. See the copy operations in [make.ps1](make.ps1) for details. The project works without these binaries in place, but then any attempt to use the `Denoiser` class will result in a `DllNotFound` exception at runtime.\n\nWhen using binaries, especially the official ones, be aware that packaging for .NET requires the RPATH of the shared library to include the same folder that contains the library itself. Otherwise, TBB will not be found. If you don't understand what that means, or how it can be achieved, check out the build script in [RenderLibs](https://github.com/pgrit/RenderLibs). (This does not apply to Windows, since the linker there has this behavior by default.)\n\nBuild the C# wrapper and run the tests:\n```\ndotnet build \u0026\u0026 dotnet test\n```\n\nTo see if the denoiser is linked correctly, you can additionally run\n```\ndotnet run --project SimpleImageIO.Integration\n```\nThese integration tests assume that you have the [tev](https://github.com/Tom94/tev) viewer open and listening to the default port on localhost. But you can also comment out the tev-related tests and only run the denoiser ones.\n\n### Building the C# wrapper on other platforms\n\nThe [SimpleImageIO.csproj](SimpleImageIO/SimpleImageIO.csproj) file needs to copy the correct .dll / .so / .dylib file to the appropriate runtime folder.\nCurrently, the runtime identifiers (RID) and copy instructions are only set for the x86-64 versions of Windows, Linux, and macOS.\nTo run the framework on other architectures, you will need to add them to the .csproj file.\nYou can find the right RID for your platform here: [https://docs.microsoft.com/en-us/dotnet/core/rid-catalog](https://docs.microsoft.com/en-us/dotnet/core/rid-catalog).\n\nNote that, currently, Open Image Denoise is included in binary from. The `Denoiser` class can therefore not be used on platforms other than x86-64 Windows, Linux, or macOS. Attempting to use it on other platforms will cause a `DllNotFound` exception.\n\nThen, you should be able to follow the steps above and proceed as usual.\n\n### Building the Python wrapper\n\nThe simplest route is to run the build script\n\n```\npwsh ./make.ps1\n```\n\nwhich builds and installs the Python lib with pip, using whatever `python` executable is currently in the path.\n\nIf you need manual control, e.g., specific Python version, here are the required steps:\n```\ncd ./FlipViewer\nnpm install\nnpm run build\ncd ..\ncp ./FlipViewer/dist/flipbook.js PyWrapper/simpleimageio/flipbook.js\n\npython -m build\npython -m pip install ./dist/simpleimageio-*.whl\n```\n\nThe first commands build, bundle, and pack the frontend code. Then, we build the Python package itself and install it via pip. The `*` must be substituted by the correct version number and runtime identifier.\n\nThe tests can be run via:\n\n```\ncd PyTest\npython -m unittest\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgrit%2Fsimpleimageio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgrit%2Fsimpleimageio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgrit%2Fsimpleimageio/lists"}