{"id":28481530,"url":"https://github.com/insightsoftwareconsortium/itksoftwareguide","last_synced_at":"2025-07-04T17:32:05.834Z","repository":{"id":2616162,"uuid":"3600233","full_name":"InsightSoftwareConsortium/ITKSoftwareGuide","owner":"InsightSoftwareConsortium","description":"Sources for the ITKSoftwareGuide.","archived":false,"fork":false,"pushed_at":"2025-06-11T18:29:33.000Z","size":21082,"stargazers_count":33,"open_issues_count":9,"forks_count":17,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-06-30T15:21:31.519Z","etag":null,"topics":["books","community","html","image-analysis","insight-toolkit","itk","pdf","registration","segmentation"],"latest_commit_sha":null,"homepage":"https://itk.org/ItkSoftwareGuide.pdf","language":"TeX","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/InsightSoftwareConsortium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"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":"2012-03-02T07:52:43.000Z","updated_at":"2025-06-11T18:28:08.000Z","dependencies_parsed_at":"2024-04-12T11:33:07.937Z","dependency_job_id":"ebf1adac-ad48-455f-903c-2c9fdba53292","html_url":"https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide","commit_stats":{"total_commits":1956,"total_committers":34,"mean_commits":"57.529411764705884","dds":0.4253578732106339,"last_synced_commit":"520cac8820fb6c38178aa1341977d143b0b01703"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/InsightSoftwareConsortium/ITKSoftwareGuide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InsightSoftwareConsortium%2FITKSoftwareGuide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InsightSoftwareConsortium%2FITKSoftwareGuide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InsightSoftwareConsortium%2FITKSoftwareGuide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InsightSoftwareConsortium%2FITKSoftwareGuide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/InsightSoftwareConsortium","download_url":"https://codeload.github.com/InsightSoftwareConsortium/ITKSoftwareGuide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/InsightSoftwareConsortium%2FITKSoftwareGuide/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263588231,"owners_count":23484886,"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":["books","community","html","image-analysis","insight-toolkit","itk","pdf","registration","segmentation"],"created_at":"2025-06-07T20:07:38.144Z","updated_at":"2025-07-04T17:32:05.829Z","avatar_url":"https://github.com/InsightSoftwareConsortium.png","language":"TeX","readme":"ITK Software Guide\n==================\n\n[![Build](https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/workflows/Build/badge.svg)](\nhttps://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/actions?query=workflow%3ABuild+branch%3Amaster)\n\nThis [ITK Software Guide] is the handbook for developing software with ITK.\n\nIt is divided into two companion books.\n\nThe [first book] covers\nbuilding and installation, general architecture and design, as well as the\nprocess of contributing in the ITK community.\n\nThe [second book] covers\ndetailed design and functionality for reading and writing images, filtering,\nregistration, segmentation, and performing statistical analysis.\n\nThis repository contains the source code for the Software Guide.\n\nHow to Contribute to the ITK Software Guide\n===========================================\n\nContributions are welcome and appreciated!\n\nContribution Process Overview\n-----------------------------\n\nThe following commands illustrate patch submission to [GitHub]:\n\n```sh\n   $ git clone https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide.git\n   $ cd ITKSoftwareGuide\n   $ ./Utilities/SetupForDevelopment.sh\n   $ git checkout -b my-topic\n   # make changes to local file(s)\n   $ git add -- changedFileName\n   $ git commit\n   $ git review-push\n```\n\nContribution Details\n--------------------\n\nFor more detailed instructions, see the [CONTRIBUTING.md](CONTRIBUTING.md) file.\n\nBuilding with Docker\n--------------------\n\nAll the dependencies described below are available pre-installed in a [Docker]\nimage. This is the easiest way to build and contribute to The Software\nGuide.\n\n  1. Download and [install Docker](https://docs.docker.com/installation/).\n  2. From a shell, run\n```sh\ndocker run --name software-guide -p 8888:8888 insighttoolkit/itksoftwareguide-edit:latest\n```\n  3. Open the URL provided in the ternmial output in a web browser. In the web interface, open a Terminal\n  4. To setup the repository for develop and build the project, run:\n```sh\nssh-keygen\ncat ~/.ssh/id_rsa.pub\n# Paste this value into https://github.com/settings/keys\ncd /ITKSoftwareGuide\n./Utilities/SetupForDevelopment.sh\ncd /ITKSoftwareGuide-build/ITKSoftwareGuide-build\nninja\n```\n  6. To view the built PDF's, navigate to `/ITKSoftwareGuide-build/ITKSoftwareGuide-build/SoftwareGuide/Latex/`,\n     and double click on the PDF.\n  7. Contribute as described in [CONTRIBUTING.md](CONTRIBUTING.md).\n  8. To restart the container, run `docker start software-guide`.\n\nBuild Overview\n--------------\n\nA combination of [CMake]\n`Superbuild` infrastructure, [Python] extraction scripts, and [LaTeX]\nformatting are required to render the entire ITK Software Guide.\n\n`CMakeLists.txt` files are placed in the directories\ninvolved on the build process. As any other CMake-managed process, the results\nof the build process are put in a binary tree corresponding to the source tree.\n\nThe following dependencies are required to build ITK Software Guide on Linux or\nWindows platforms:\n\n  * [Git]\n  * [Python]\n  * [ImageMagick]: Windows installer can be found\n    [here](https://www.imagemagick.org/script/download.php#windows).\n  * [LaTeX] and [BibTeX]. See the preamble of the\n    [`./SoftwareGuide/Latex/00-Preamble-Common.tex`] file for the full list of\n    required LaTeX packages. Among these packages, the [Minted] package for\n    syntax highlighting in its turn depends on a Python package [Pygments].\n    Instructions for installing [Minted] and [Pygments] packages on Windows are\n    available [here](https://minted.googlecode.com/files/minted.pdf).\n  * [dvips], [ps2pdf]. While on Linux platforms these tools are usually\n    included with most distributions, on Windows platforms they are usually\n    included in [MikTex] Latex distribution.\n\nITK Software Guide is generated with Latex by using input from a variety of\nsource code files and images:\n\n  1. LaTeX files found in [`./SoftwareGuide/Latex`].\n  2. JPEG, PNG and EPS files in [`./SoftwareGuide/Art`].\n  3. PNG files generated as the result of compiling and running the examples\n     included in the ITK source code.\n  3. ITK examples source code `.cxx` files where the comments delimited with\n     `BeginLaTeX`, `EndLaTeX` and `BeginCodeSnippet`, `EndCodeSnippet` have\n     been written specifically to be included in the ITK Software Guide; the\n     regular LaTeX files in [`./SoftwareGuide/Latex`] include the LaTeX files\n     generated from the ITK examples source code.\n\nFollowing is a brief description of the build process:\n\n  1. The source code of `ITK` is downloaded and built (including ITK\n     examples) in the binary output directory.\n  2. JPEG and PNG files in the [`./SoftwareGuide/Art`] directory are converted\n     to EPS using [ImageMagick] tools; the resulting EPS files are saved in the\n     `Art` directory in the binary output directory.\n  3. PNG files are generated by running ITK examples and converted to EPS using\n     [ImageMagick]; the resulting EPS files are saved in `Art/Generated`\n     directory of the binary output directory.\n  4. A Python script\n     [`./SoftwareGuide/Examples/ParseCxxExamples.py`](https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Examples/ParseCxxExamples.py)\n     is invoked to extract the comments in the ITK examples source file\n     delimited with `BeginLaTeX`, `EndLaTeX` and `BeginCodeSnippet`,\n     `EndCodeSnippet` and generate LaTeX files which are copied into the\n     `Examples` subdirectory of the binary output directory.\n  5. The top-level LaTeX file\n     [`./SoftwareGuide/LaTeX/ITKSoftwareGuide-Book1.tex`](https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/ITKSoftwareGuide-Book1.tex)\n     is compiled with a series of calls to `latex`, `bibtex`, `latex`,\n     `makeindex`,`dvips`, and `ps2pdf` to generate the PDF file.\n\nConfiguring and Building with CMake\n-----------------------------------\n\nFollowing is the description how to configure and build ITK Software Guide using\n[CMake]:\n\n  1. Run cmake-gui and specify input and binary output directories.\n     Alternatively, create the binary output directory and run\n```sh\n   $ ccmake source_dir\n```\nwhere source_dir is the full path of the `ITKSoftwareGuide` directory.\n  2. Configure and generate the project for the target platform.\n  3. Build `SuperBuild\\_ITKSoftwareGuide` project as appropriate for the target\n     platform.\n\nTroubleshooting\n---------------\n\n  1. Build process will fail if [CMake] is unable to locate any of the\n     dependencies. In this case a close examination of the error messages might\n     provide a clue as to which dependency is failing.\n\n  2. Frustrated by the build taking a long time to complete\n     ... no solution here :blush:.\n\n\n\n\n[`./SoftwareGuide/Art`]: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/tree/master/SoftwareGuide/Art\n[`./SoftwareGuide/Latex`]: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/tree/master/SoftwareGuide/Latex\n[`./SoftwareGuide/Latex/00-Preamble-Common.tex`]: https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/00-Preamble-Common.tex\n\n[ITK Software Guide]: https://itk.org/ITKSoftwareGuide/html/\n[first book]: https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1.html\n[second book]: https://itk.org/ITKSoftwareGuide/html/Book2/ITKSoftwareGuide-Book2.html\n[CMake]: https://cmake.org/\n[GitHub]: https://github.com/\n\n[BibTeX]: http://www.bibtex.org/\n[Docker]: https://www.docker.com/\n[dvips]: https://tug.org/texinfohtml/dvips.html\n[Git]: https://git-scm.com/\n[ImageMagick]: https://www.imagemagick.org\n[LaTeX]: https://www.latex-project.org//\n[Minted]: https://ctan.org/pkg/minted?lang=en\n[MikTex]: https://miktex.org/\n[ps2pdf]: https://www.ps2pdf.com/\n[Pygments]: https://pygments.org/\n[Python]: https://www.python.org/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsoftwareconsortium%2Fitksoftwareguide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finsightsoftwareconsortium%2Fitksoftwareguide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finsightsoftwareconsortium%2Fitksoftwareguide/lists"}