# SimpleITK Notebooks: learning image analysis by running it > The SimpleITK Notebooks repository is a collection of Jupyter notebooks that teach image analysis through the SimpleITK wrapper, in Python and in R, with the supporting infrastructure for remote data downloads and automated notebook testing. It is meant for learning, for teaching and as a starting point for research, and it runs in a browser through Binder or Colab without a local install. **InsightSoftwareConsortium/SimpleITK-Notebooks** — Jupyter notebooks for learning how to use SimpleITK - Repository: https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks - Stars: 913 · Forks: 375 - Language: Jupyter Notebook - License: Apache-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/insightsoftwareconsortium-simpleitk-notebooks ## What SimpleITK sits on top of SimpleITK is described as an abstraction layer and wrapper around the Insight Segmentation and Registration Toolkit, ITK. It is available in C++, Python, R, Java, C#, Lua, Tcl and Ruby. That layering is what the notebooks inherit. The SimpleITK API documentation is based on the C++ implementation, which is readily mapped to whichever language you use, and the ITK book is where the underlying concepts are explained. The README points at Book 2, Design and Functionality, and makes an important caveat: the ITK API is significantly different from the SimpleITK one, but the general concepts are the same, with the combination of an optimizer and a similarity metric for registration given as the example. So the notebooks are a layer above the tutorials. You are learning SimpleITK, which is a simplified surface over ITK, and the notebooks assume you will consult the ITK material for the theory. The visualisation in the project page is a good indicator of what is covered. It is a visualization of a rigid CT and MR registration process, and the script used to generate the frames for the animated image lives in the Utilities directory of the repository, which means the teaching material is accompanied by the code that produced its illustrations. ## Three intended uses, and the infrastructure that makes two of them work The repository states three uses. It is for learning SimpleITK, as a basis for teaching activities, and as a basis for research activities. The second and third uses are where the repository's own infrastructure matters. It supports remote data downloads and notebook testing, and the project says these readily facilitate collaborative research. That is a bigger claim than it sounds: notebook testing means the code in the teaching material is executed in continuous integration, so a notebook that stops working fails a build rather than quietly rotting. The badges show two continuous integration systems running notebook tests, GitHub Actions and CircleCI. The presence of both suggests the project has been migrating or covering both, and either way the notebooks are tested automatically rather than only being reviewed by eye. The repository layout reflects the two language tracks. There are Python/ and R/ directories, each with its own README giving language specific installation details, plus Data/ for the sample data, SharedImages/ for images shared between notebooks, Utilities/ for helper scripts including the animation script, docs/ for the built site, and tests/ for the test infrastructure. The top level environment.yml, requirements_dev.txt, tox.ini and run.sh are the Python development environment and the entry point for the test run. ## Running the notebooks in a browser with no install Before you clone anything, the project suggests trying the Python notebooks in a hosted environment. There are two paths, BinderHub and Google Colaboratory, and the mechanism is the same for both: go to the notebook and click the shield icon in the first notebook cell if it exists. A Binder badge lets you run all the notebooks in a single environment: you navigate to the Python directory and open a notebook. The caveats are listed and they are worth reading before you plan a teaching session on it. Some notebooks require significant computational resources which may not be available from these services. Every cell that uses the sitk.Show() command will raise an exception, because that call needs a local Fiji installation; the suggestion is to ignore those cells or modify the code for the session. Binder is a free public service with no login required and limited resources, so it may not always be available or may launch slowly. Colab is a free Google service that requires a login, and it launches each notebook in an independent environment. That last difference has a practical consequence. Binder gives you one environment for the whole session, so variables and imports persist between notebooks you open in it. On Colab each notebook starts fresh, so a notebook that depends on something an earlier one defined will fail unless you run them in order or repeat the setup. ## Making the notebooks use the full browser width A small but real annoyance with Jupyter is that the notebook content does not occupy the full browser window width by default, which makes wide image plots and side by side figures cramped. The fix can be applied per notebook, by adding a code cell with a display and HTML call. ```python from IPython.core.display import display, HTML display(HTML("")) ``` Or it can be applied to every notebook at once, by putting the same CSS rule in the custom.css jupyter configuration file. The rule itself is a single line setting the container width to 100 percent with the important flag. The location of that file differs by platform. On macOS and Linux it is found in ~/.jupyter/custom/custom.css, and on Windows it is found in the .jupyter custom directory under the user profile folder. Setting it once in the configuration file is the right approach for teaching, where every student opens many notebooks and nobody should have to add a cell first. Doing it per notebook is the right approach for a single session on a shared machine where you would rather not change the configuration for everyone. ## What SimpleITK gives you and where the boundary is The language availability list for SimpleITK is long, C++, Python, R, Java, C#, Lua, Tcl and Ruby, and the notebooks cover the Python and R tracks. There is one constraint to know up front: SimpleITK with R is only available on Linux and Mac, with a link to the remotes based installer. That constraint is a real one for anyone teaching on Windows, and it is stated in the getting started section rather than buried. The notebooks themselves are for interactive image analysis, and the README points to the SimpleITK read-the-docs pages for general installation information. The project documentation site is built from the docs directory in the repository, and the .readthedocs.yaml file in the root is the configuration for that build. The Data directory is what makes the notebooks runnable without hunting for sample data, and the remote data download support means some of it is fetched on demand rather than committed to the repository. The testing setup deserves a note. The tox.ini and the tests directory, along with run.sh, are how the notebooks are executed as part of the test suite, and requirements_dev.txt pins the development dependencies. That is the mechanism behind the claim that the infrastructure supports reproducible research. ## Contributing, citing and the state of the project The project solicits contributions in three specific forms: bug fixes, improved versions of existing notebooks covering both text and code, and new notebooks. Questions go to the ITK discourse, and problems are reported through the GitHub issue tracker. The repository is not archived and the last push was on 2026-10-11, and the primary language is recorded as Jupyter Notebook. It publishes no GitHub releases, so there is no tagged version to pin, and the documentation site at the Insight Software Consortium pages serves the rendered material instead. There is a formal citation, which matters for a teaching and research resource because it is what makes the work citable in a paper. The requested citation is the SimpleITK Image-Analysis Notebooks paper by Yaniv, Lowekamp, Johnson and Beare, published in the Journal of Digital Imaging, with a DOI and volume and page numbers given. There is also a CITATION.cff file in the repository root for the newer citation format. The licence is Apache-2.0, recorded in the LICENSE file, which is a permissive grant that lets you reuse and adapt the notebooks in teaching material or in derived research code without the copyleft obligations that would apply under a stronger copyleft licence. The community spirit in the README is genuine rather than decorative, since the notebook testing infrastructure and the shared data directory are both contributions that make the material better for everyone who uses it afterwards. ## Conclusion Adopt these notebooks if you are learning SimpleITK, preparing course material, or want a worked example of registration or segmentation you can adapt, because the material is written as executable teaching material rather than as API documentation. Do not treat them as a production library or as a substitute for reading the ITK concepts, since the notebooks deliberately skip some of the underlying theory. Verify first that you can install SimpleITK for your language, note that SimpleITK with R is only available on Linux and Mac, plan for the notebooks that call sitk.Show() because they need a local Fiji installation, and read the caveat that the free hosting services have limited resources. ## FAQ ### How do I run the SimpleITK notebooks without installing anything? Use BinderHub or Google Colaboratory. Go to the notebook and click the shield icon in the first notebook cell if it exists. Binder runs all the notebooks in one environment and needs no login, while Colab requires a Google login and launches each notebook in an independent environment. ### Why do some SimpleITK notebook cells fail in the browser? Every cell using the sitk.Show() command raises an exception because it requires a local Fiji installation. The guidance is to ignore those cells or modify the code for the session, and some notebooks also need more compute than the free hosted services provide. ### Can I use SimpleITK with R on Windows? Not according to the project documentation, which states that SimpleITK with R is only available on Linux and Mac, pointing to the remotes based installer. Language specific installation details for each track are in the Python and R README files in the repository. ### How do I make the SimpleITK notebooks use the full browser width? Either add a code cell per notebook with the IPython display and HTML call, or apply the container width rule to the custom.css jupyter configuration file, which is found in the .jupyter custom directory under your user profile on macOS, Linux and Windows. ## Sources - [InsightSoftwareConsortium/SimpleITK-Notebooks on GitHub](https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks) - [Issues](https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks/issues) - [License: Apache-2.0](https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks/blob/main/LICENSE) - [README](https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/insightsoftwareconsortium-simpleitk-notebooks