{"id":19110088,"url":"https://github.com/zeiss/pylibczirw","last_synced_at":"2025-04-30T20:42:03.672Z","repository":{"id":242673253,"uuid":"800384078","full_name":"ZEISS/pylibczirw","owner":"ZEISS","description":"A simple and easy-to-use Python wrapper for libCZI - a cross-platform C++ library intended for providing read and write access to CZI documents.","archived":false,"fork":false,"pushed_at":"2025-04-11T08:45:23.000Z","size":509,"stargazers_count":14,"open_issues_count":20,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-19T08:33:23.049Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zeiss.github.io/pylibczirw/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZEISS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"COPYING","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-14T08:24:51.000Z","updated_at":"2025-04-11T08:23:18.000Z","dependencies_parsed_at":"2025-04-09T15:48:02.056Z","dependency_job_id":null,"html_url":"https://github.com/ZEISS/pylibczirw","commit_stats":null,"previous_names":["zeiss/pylibczirw"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fpylibczirw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fpylibczirw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fpylibczirw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZEISS%2Fpylibczirw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZEISS","download_url":"https://codeload.github.com/ZEISS/pylibczirw/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251779048,"owners_count":21642474,"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":[],"created_at":"2024-11-09T04:23:35.105Z","updated_at":"2025-04-30T20:42:03.645Z","avatar_url":"https://github.com/ZEISS.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pylibCZIrw\n[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)\n[![REUSE status](https://api.reuse.software/badge/github.com/ZEISS/pylibczirw)](https://api.reuse.software/info/github.com/ZEISS/pylibczirw)\n[![Build](https://github.com/ZEISS/pylibczirw/actions/workflows/build.yml/badge.svg?branch=main\u0026event=push)](https://github.com/ZEISS/pylibczirw/actions/workflows/build.yml)\n[![CodeQL](https://github.com/ZEISS/pylibczirw/actions/workflows/codeql.yml/badge.svg?branch=main\u0026event=push)](https://github.com/ZEISS/pylibczirw/actions/workflows/codeql.yml)\n[![codecov](https://codecov.io/gh/ZEISS/pylibczirw/graph/badge.svg?token=JX6cZGEJ0a)](https://codecov.io/gh/ZEISS/pylibczirw)\n[![MegaLinter](https://github.com/ZEISS/pylibczirw/actions/workflows/mega-linter.yml/badge.svg?branch=main\u0026event=push)](https://github.com/ZEISS/pylibczirw/actions/workflows/mega-linter.yml)\n[![GitHub Pages](https://github.com/ZEISS/pylibczirw/actions/workflows/pages.yml/badge.svg?branch=main\u0026event=push)](https://github.com/ZEISS/pylibczirw/actions/workflows/pages.yml)\n[![PyPI version](https://badge.fury.io/py/pylibCZIrw.svg)](https://badge.fury.io/py/pylibCZIrw)  \n\n# Contribute\nIf you intend to **use** this repo, clone the repository on your machine with ``` git clone --recurse-submodules ```.  \nIf you intend to also **contribute** to this repo, you are requested to copy ALL files in the hooks directory into your .git/hooks directory right after you cloned this repo!  \nIn addition, be sure to ideally always keep your remotes up-to-date with ``` git pull --recurse-submodules ```. Even better, you can set the configuration option _submodule.recurse_ to _true_ locally (this works for git pull since Git 2.15) with ``` git config --local submodule.recurse true ```.  This option will make Git use the _--recurse-submodules_ flag for all commands that support it (except clone). See \u003chttps://git-scm.com/book/en/v2/Git-Tools-Submodules\u003e for more information.\nNote: if you forget to link the submodules when cloning, you can use ``` git submodule update --init ```.  \n\nYou should ideally have [PyCharm Professional](https://www.jetbrains.com/pycharm/) and [conda](https://docs.conda.io/en/latest/miniconda.html) installed locally. You should also configure your Project interpreter as a conda environment to have all required packages installed, i.e.  \n1. Create a fresh conda environment via `conda create -p \u003csome-path\\PyPI\\pylibCZIrw\u003e python` and activate it with `conda activate \u003cenvironment_name\u003e`  \n   Note: Alternatively, when opening the project the first time, in the prompt to create a venv, select the python location from one of the existing conda venvs.\n2. Navigate to the repository from inside the environment.\n3. Install necessary packages for building from the activated environment via `pip install .`\n4. Install necessary packages for code quality analysis and testing from the activated environment via `pip install -r requirements_test.txt`  \n\nYou may then [configure all relevant 3rd party tools](https://www.jetbrains.com/help/pycharm/configuring-third-party-tools.html#), e.g. pytest, mypy, flake8 or bandit. You may want to check with the corresponding pipeline (template) for which analysis tools are run and their command line.  \n\nThis repo follows [GitFlow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). PR/Build validation is executed on develop and main. Self-approval is allowed on develop. No policy is applied on release/ to allow for PR changes on release/ before merging to main or back to develop. See [Packaging](#packaging) and [Versioning](#versioning) for more information.  \n\nFor more information, refer to [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n# Introduction\n\nczi is a python wrapper around the [libCZI C++ library](https://github.com/ZEISS/libczi).\n\nSimilar endeavours have been made to wrap libCZI in python, namely:\n- [pylibCZI](https://github.com/elhuhdron/pylibczi)\n- [aicspylibCZI](https://github.com/AllenCellModeling/aicspylibczi)\n\nThis python package has a slightly different API with some improvements to reading but, more importantly, the addition of writing functionality.\n\nThere are also libCZI wrappers for other languages:\n- [Mathematica / Wolfram Language](https://github.com/ptahmose/WolframLibraryLink_libCZI)\n- [Matlab/Octave via MEXFile](https://github.com/ptahmose/MEXlibCZI)\n\n# Building\n_**pylibCZIrw**_ is a python library using bindings from:  \n* [libCZI](https://github.com/ZEISS/libczi) and  \n* pybind11  \n  - a very modern and maintained project (Supports c++11/c++14 features)  \n  - Bindings are done in a very few lines of code, interface with numpy array is easy.\n  - No need to \"learn\" and code in an intermediate language (Cython).\n  - Already used internally at Zeiss and very good feedbacks.\n\nTo contribute to the development (C++ or python side), you will have to compile the C++ bindings.  \nThis documentation provides a step-by-step guide to help you to do so.\n\n## Requirements\n\n- 64 bits OS and 64 bits Python (with [cmake pre-installed](https://cmake-python-distributions.readthedocs.io/en/latest/installation.html)).\n- _**python 3.XX**_\n- C++ compiler (_**clang/gcc**_ for linux, _**VS Studio**_ on _**Windows**_).\n\n## Getting started\n\n- Make sure that the libs folder contains _**libCZIrw**_ and _**pybind11**_ submodules (i.e. those subfolders are not empty).\n\n## Building on Windows\n\nBefore building, install [vcpkg](https://vcpkg.io/en/getting-started.html)\nOnce this is done, add the environment variable VCPKG_INSTALLATION_ROOT to be the root of the installation (repo).\n\n### Using PyCharm (or plain Python console)\n1. ```pip install .``` from the root of the repo.  \nNote: For pip 21.2 and below, use in-tree-build ```pip install --use-feature=in-tree-build .``` from the root of the repo, or it will fail.\n2. You can import this library in python and start using the bindings.  \n```from pylibCZIrw import czi```\n3. Updating to a libczi version on a different fork can be done via navigating to the lib folder in the fork `cd \u003cRepositoryDirectory\u003e/pylibczirw/libs/libCZIrw`\n   Then adding the fork branch ``git remote add fork https://github.com/\u003cmy fork\u003e.git``  \n   Fetching the branches in the fork ``git fetch fork``  \n   And finally checking out the required branch ``git checkout write_colormode_to_displaysettingsxml``\n4. To test this on another project that uses pylibczi, navigate to the pylibczirw folder in python terminal of the pylibCZIrw project, and then create a wheel file using\n   ```python setup.py bdist_wheel```.  \n    Note: Make sure you didn't run ``pip install .`` as this will delete the wheel file after installing it.\n    Then install the package in the project using ```pip install \u003cRepositoryDirectory\u003e\\pylibczirw\\dist\\pylibCZIrw-3.4.0-cp310-cp310-win_amd64.whl```  \n    Note: this required the python versions in both projects (and venvs) to be the same.\n    Note: If this fails on cmake, the cmake inputs can be copied from the console output, and run separately for faster debugging.\n5. Alternatively, in the python terminal of the project that uses pylibCZIrw, navigate to the build folder of pylibCZIrw and run ```pip install . -e```.  \n   This will build and install the latest pylibCZIrw whenever it changes.  \n   Note: This is slow and takes around 5 min to build. To run a faster option that doesn't auto update, run ```pip install .```. This will however need to be rerun on every change to pylibczirw.\n6. Finally run ```pip install .``` from the root of the repo CziConverter repo to install all the new dependencies.\n### Using Visual Studio \u003e 2015\n1. Create an environment variable PYTHON_EXECUTABLE that contains the full path to python.exe (needed for pybind11)\n2. Launch _**Visual Studio**_.\nClick Open a local folder and select pylibczirw.  \nIt will automatically load the _**Cmake**_ project.\n\n3. To build the project right-click on the **CmakeList.txt** at the root of the repo and select Build.  \nIf it fails with the linking error **LNK1104 cannot open file 'python3X_d.lib'**, try to select the **\"x64-Release\"** config instead of **\"x64-Debug\"**  \n(some _**Windows**_ installation of python are missing the debug .dll version (dynamic libraries)).\n\n4. If the Build was successful it should have generated a python library file **_pylibCZIrw.cp\u003cpython-version\u003e-win_amd64.pyd** in the corresponding build folder.\n\n5. Copy this file to the root of the repo and rename it to _pylibCZIrw.pyd\n\n6. You can import this library in python and start using the bindings.  \n```from _pylibCZIrw import czi```\n\n## Building on Linux\n\nNot done yet. Only in CI/CD pipeline.\n\n# Versioning\nThis [package](#packaging) follows [Semantic Versioning](https://semver.org/).  \nVersion bumps are carried out automatically using [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/index.html).  \nNote: When updating major version, this must be synchronised with a [Colab template update](doc/jupyter_notebooks).\n\n# Packaging\n\nA package installable through pip is generated as part of a [build](https://github.com/ZEISS/pylibczirw/actions/workflows/build.yml) and pushed to [PyPI](https://pypi.org/project/pylibczirw/).  \n\n# Release Process\n  1. Once changes have been merged to develop, a PR with updated version (see: [Versioning](#versioning)) should be created to develop.  \n     The following files need to have their version updated: CZIwriteAPI.cpp, CMakeLists.txt, setup.py, INFO.md\n  2. Make sure both the [API](#api)s have been updated.\n  3. Next create a release branch based on develop, with naming `release/v_version (ex: release/v_3_4_0)`\n  4. Create a PR to merge this into main.  \n     **WARNING** Do not merge until package is tested.  \n     To create a TestPyPI package, run a manual build of [TC-PyPI-pylibCZIrw](https://dev.azure.com/ZEISSgroup/RMS-DEV/_build?definitionId=5108) with the `Upload` stage selected.  \n     This, when complete will produce a URI to the test package (ex: \u003chttps://test.pypi.org/project/pylibCZIrw/3.4.0/\u003e).\n  5. Once this test package is ready, it can be installed using the following command replacing the version with the one specified previously  \n     ``` pip install -i https://test.pypi.org/simple/ pylibCZIrw==3.4.0 ```.\n  6. After testing this package, merge the release branch into main, and then back into develop, if any bugfixes have been made.\n\n# Installation\nBinary wheels for all python versions that this package is considered to be compatible against (see python_requires in setup.py) as well as a source distribution are [packaged](#packaging). Installing from the source distribution requires **cmake** to be available on PATH.\n\n1. ```python -m pip install --upgrade --requirement requirements.txt``` (essentially needed for keyring and artifacts-keyring to be available)\n2. ``` python -m pip install pylibCZIrw --index-url https://pkgs.dev.azure.com/ZEISSgroup/RMS-DEV/_packaging/RMS-PyPI/pypi/simple ```\n3. Complete authentication (varies based on the concrete method)\n\n# API\nSee [API Specification](https://zeiss.github.io/pylibczirw/)  \n\n# Troubleshooting\nSee [Troubleshooting](/TROUBLESHOOTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeiss%2Fpylibczirw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeiss%2Fpylibczirw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeiss%2Fpylibczirw/lists"}