{"id":39803613,"url":"https://github.com/jewettaij/visfd","last_synced_at":"2026-01-18T12:35:54.961Z","repository":{"id":77619301,"uuid":"124841397","full_name":"jewettaij/visfd","owner":"jewettaij","description":"volumetric image toolkit for simple feature detection in 3D images (segment tomograms)","archived":false,"fork":false,"pushed_at":"2025-08-19T20:45:54.000Z","size":2987,"stargazers_count":6,"open_issues_count":7,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-19T22:27:16.406Z","etag":null,"topics":["3d-images","cryo-em","cryoem","electron-microscopy","image-processing","membrane-detection","mrc-format","segmentation","tensor-voting","tomography"],"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/jewettaij.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2018-03-12T06:07:23.000Z","updated_at":"2025-08-19T20:43:08.000Z","dependencies_parsed_at":"2024-10-26T01:00:02.502Z","dependency_job_id":null,"html_url":"https://github.com/jewettaij/visfd","commit_stats":null,"previous_names":[],"tags_count":104,"template":false,"template_full_name":null,"purl":"pkg:github/jewettaij/visfd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jewettaij%2Fvisfd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jewettaij%2Fvisfd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jewettaij%2Fvisfd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jewettaij%2Fvisfd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jewettaij","download_url":"https://codeload.github.com/jewettaij/visfd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jewettaij%2Fvisfd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28536002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["3d-images","cryo-em","cryoem","electron-microscopy","image-processing","membrane-detection","mrc-format","segmentation","tensor-voting","tomography"],"created_at":"2026-01-18T12:35:54.257Z","updated_at":"2026-01-18T12:35:54.934Z","avatar_url":"https://github.com/jewettaij.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CircleCI](https://img.shields.io/circleci/build/github/jewettaij/visfd/master)](https://circleci.com/gh/jewettaij/visfd)\n[![C++11](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://isocpp.org/std/the-standard)\n[![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/jewettaij/visfd)]()\n[![License](https://img.shields.io/badge/License-MIT-green.svg)]()\n[![DOI](https://zenodo.org/badge/124841397.svg)](https://zenodo.org/badge/latestdoi/124841397)\n\n\nvisfd\n===========\n\n## Volumetric Image toolkit for Simple Feature Detection\n\n\u003cimg src=\"https://raw.githubusercontent.com/jewettaij/visfd_tutorials/main/prokaryotes/Hylemonella_gracilis/images/orig_crop_XZ_view_XY_view_LR.jpg\" title=\"original tomogram sliced in the XZ and XY directions\" height=170\u003e  \u003cimg src=\"https://raw.githubusercontent.com/jewettaij/visfd_tutorials/main/images/rightarrow.svg\" height=30\u003e  \u003cimg src=\"https://raw.githubusercontent.com/jewettaij/visfd_tutorials/main/prokaryotes/Hylemonella_gracilis/images/membrane_tilt_inner+outer+poincloud_clipped_mesh_LR.jpg\" title=\"detected surfaces are dark blue, green. Inferred, generated surfaces on top and bottom\" height=180\u003e  \u003cimg src=\"https://raw.githubusercontent.com/jewettaij/visfd_tutorials/main/images/rightarrow.svg\" height=30\u003e  \u003cimg src=\"https://raw.githubusercontent.com/jewettaij/visfd_tutorials/main/prokaryotes/Hylemonella_gracilis/images/segmentation_occ_bbg_LR.jpg\" title=\"segmented image showing membranes, ribosomes, and the nucleoid\" height=160\u003e\n\n\nVISFD is a small C++ template library for 3D image processing\n(\"[visfd.hpp](./lib/visfd/visfd.hpp)\")\nwhich is useful for extracting geometric shapes, volumes, and other features\nfrom 3-D volumetric images (eg. tomograms).\nVISFD also includes a basic C++ library for reading and writing MRC files.\n(\"[mrc_simple.hpp](./lib/mrc_simple/mrc_simple.hpp)\").\n\n*VISFD's most useful feature is probably its ability to segment cell volumes\nin Cryo-ET images, as well as membrane-bound organelles within cells.*\n\nVISFD is also a collection of stand-alone programs\nwhich use this library\n(including \"[filter_mrc](./doc/doc_filter_mrc.md)\",\n \"[combine_mrc](./doc/doc_combine_mrc.md)\",\n \"[voxelize_mesh](./doc/doc_voxelize_mesh.md)\",\n \"[sum_voxels](./doc/doc_sum_voxels.md)\",\n and\n \"[pval_mrc](./doc/doc_pval_mrc.md)\").\nThey are documented [here](./doc).\nMultiprocessor support is implemented using\n[OpenMP.](https://en.wikipedia.org/wiki/OpenMP)\n\n\n## Segmenting cell volumes from 3D CryoEM tomograms\n\nMachine-learning based detectors for membranes\nand large molecular complexes have been implemented in programs like\n[EMAN2](https://blake.bcm.edu/emanwiki/EMAN2/Programs/tomoseg)\nand\n[AIS](https://github.com/bionanopatterning/Ais).\n*VISFD compliments this software*\nby providing tools for geometry extraction,\n[curve and surface detection](http://dx.doi.org/10.1016/j.jsb.2014.02.015),\nsigned normal determination, and robust connected-component analysis.\nIn a typical workflow, features of interest (like membranes or filaments)\nwould be detected and emphasized using programs like EMAN2 or AIS.  Then the coordinates of these\ngeometric shapes would be extracted using VISFD and analyzed using 3rd-party tools like\n[**SSDRecon/PoissonRecon**](https://github.com/jewettaij/PoissonRecon).\nThis makes it possible to detect and close holes in incomplete membrane\nsurfaces automatically.  *However, VISFD can detect curves and surfaces on it's own.\n(EMAN2 and/or AIS are recommended but not required.)*\n\n\n\n## Alternatives to VISFD\n\nAlthough VISFD has similiarities and features to general libraries for for 3-D image processing,\nsuch as [scikit-image](https://scikit-image.org) and\n[scipy.ndimage](https://docs.scipy.org/doc/scipy/reference/ndimage.html),\nVISFD is no where near as general or well documented as these tools.\nHowever VISFD has additional features (such as tensor-voting) which\nare useful for extracting geometry from Cryo-EM tomograms of living cells.\n\n\n## Programs included with this repository:\n\nAfter compilation, all programs will be located in the \"*bin/*\" subdirectory.  Here is a brief description of some of them:\n\n\n## filter_mrc\n\n**[filter_mrc](./doc/doc_filter_mrc.md)**\nis a stand-alone program which uses many of the\nfeatures of the **visfd** library.\nThis program was intended to be used for automatic\n[detection](https://www.ncbi.nlm.nih.gov/pubmed/24625523)\nand\n[segmentation](./doc/doc_voxelize_mesh.md)\nof\n[closed](https://stackoverflow.com/questions/51149213/how-to-avoid-hole-filling-in-surface-reconstruction)\nmembrane-bound compartments in Cryo-EM tomograms.\nOther features include\nfiltering,\nannotation,\n[scale-free blob-detection](https://en.wikipedia.org/wiki/Blob_detection),\n[morphological noise removal](https://en.wikipedia.org/wiki/Opening_(morphology)),\n[connected component analysis](https://en.wikipedia.org/wiki/Connected-component_labeling),\n[filament (curve) detection *(planned)*](./doc/doc_filter_mrc.md#Detecting-curves), and\n[edge detection *(planned)*](./doc/doc_filter_mrc.md#-edge-thickness).\nImages can be segmented hierarchically into distinct contiguous objects,\nusing a variety of strategies.\nThis program currently only supports the *.MRC* (a.k.a. *.REC* or *.MAP*)\nimage file format.\nAs of 2021-9-13, this program does not have a graphical user interface.\n\nTutorials for using *filter_mrc* this are available\n[**here**](https://github.com/jewettaij/visfd_tutorials).\nA (long) reference manual for this program is available\n[**here**](./doc/doc_filter_mrc.md).\nThe source code for the VISFD filters used by this program is located\n[**here**](./lib/visfd/).\n\n\n## voxelize_mesh.py\n**voxelize_mesh.py** is a program that finds the voxels in a volumetric\nimage that lie within the interior of a closed surface mesh.\nIt was intended for segmenting the interiors of membrane-bound\ncompartments in tomograms of cells.\nThe mesh files that this program reads are *typically* generated by\n*filter_mrc* ([together with other tools](./doc/doc_filter_mrc.md#example-3)).\nHowever it can read any standard PLY file containing a closed polyhedral mesh.\nThis program currently only supports the .mrc/.rec image file format.\nDocumentation for this program is located\n[here](./doc/doc_voxelize_mesh.md).\n**WARNING: This experimental program is very slow and currently requires\na very large amount of RAM.**\n\n\n## combine_mrc\n**combine_mrc** is a program for combining two volumetric images (i.e. tomograms, both of identical size) into one image/tomogram, using a combination of addition, subtraction, multiplication, division, and thresholding operations.  These features can be used perform binary operations between two images (which are similar to \"**and**\", \"**or**\", and \"**not**\" operations.)\nDocumentation for this program is located\n[here](./doc/doc_combine_mrc.md).\n\n## histogram_mrc.py\n**histogram_mrc.py** is a graphical python program which displays the\nhistogram of voxel intensities contained in an MRC file.\nIt can be useful when deciding what thresholds to use\nwith in the \"**filter_mrc**\" and \"**combine_mrc**\" programs.\nVoxels and regions in the image can be excluded from consideration\nby using the \"-mask\" and \"-mask-select\" arguments.\nThis software requires the *matplotlib* and *mrcfile* python modules\n(both of which can be installed using pip).\nDocumentation for this program is located\n[here](./doc/doc_histogram_mrc.md).\n\n## sum_voxels\n**sum_voxels** is a program for estimating volumes.\nIt is a simple program which\nreads an MRC (.REC) file as an argument\nand computes the sum of all the voxel intensities.\n(Typically the voxel intensities are either 1 or 0.\n The resulting sums can be converted into volumes\n either by multiplying by the volume-per-voxel,\n or by specifying the voxel width using the \"-w\" argument,\n and including the \"-volume\" argument.)\nFor convenience, threshold operation can be applied\n(using the \"-thresh\", \"-thresh2\", and \"-thresh4\" arguments)\nso that the voxels intensities vary between 0 and 1\nbefore the sum is calculated.\nThe sum can be restricted to certain regions\n(by using the \"-mask\" and \"-mask-select\" arguments).\nDocumentation for this program is located\n[here](./doc/doc_sum_voxels.md).\n\n\n## pval_mrc\n**pval_mrc** is a program for estimating the probability\nthat a cloud of points in an image is distributed randomly.\nIt looks for regions of high (or low) density in an image.\n(The user can specify a *-mask* argument to perform the analysis\n in small, confined, irregularly-shaped subvolumes from a larger image.)\nDocumentation for this program is located\n[here](./doc/doc_pval_mrc.md).\n\n\n### Development Status: *alpha*\n\nAs of 2023, development on this software has been postponed.\nIf I have time to work on it again, some program names, command line arguments,\nfile names, and function names (in the API) may be altered in the future.\n\n\n## Installation\n\nThe [INSTALL.md](INSTALL.md) file has instructions\nfor installing VISFD and its dependencies.\n\n\n## Requirements\n\n- **16GB** of RAM or higher.\n(For membrane detection, your RAM must exceed 11x-44x the size of the tomogram\n that you are analyzing.  This does not include the memory needed by the OS,\n browser, or other programs you are running.\n The *voxelize_mesh.py* program requires even more memory.\n You can reduce the memory needed and computation time dramatically\n by cropping or binning your tomogram.)\n- A terminal (running BASH) where you can enter commands.\n- A [C++ compiler](./INSTALL.md#Compile-the-VISFD-code)\n- [make](https://en.wikipedia.org/wiki/Make_(software))\n- Software to visualize MRC/REC/MAP files\n(such as [IMOD/3dmod](https://bio3d.colorado.edu/imod/))\n- python (version 3.0 or later)\n- The \"numpy\", \"matplotlib\", \"mrcfile\", and \"pyvista\" python modules\n  (These are are installable via \"pip3\" or \"pip\".)\n- [**SSDRecon/PoissonRecon**](https://github.com/jewettaij/PoissonRecon).\n- Software to visualize mesh files (such as [meshlab](http://www.meshlab.net)).\n\n\n### Recommended:\n\n- A text editor.  (Such as vi, emacs, atom, VisualStudio, Notepad++, ...\n  Apple's TextEdit can be used if you save the file as *plain text*.)\n- A computer with *at least* 4 CPU cores (8 threads).\n- 32GB of RAM (depending on image size, this still might not be enough)\n- [ChimeraX](https://www.cgl.ucsf.edu/chimerax/) is useful for visualizing\n  MRC files in 3-D and also includes simple graphical\n  [volume editing capability](https://www.cgl.ucsf.edu/chimera/docs/ContributedSoftware/voleraser/voleraser.html).\n\n\n## License\n\nAll of the code in this repository\n(except for code located in \"lib/mrc_simple\" and \"lib/visfd/eigen_simple.hpp\")\nis available under the terms of the terms of the\nMIT license.  (See \"[LICENSE.md](./LICENSE.md)\")\n\n\n### Additional license dependencies\n\n#### MPL-2.0 licensed code (eigen_simple)\nThe \"lib/visfd/eigen3_simple.hpp\" file contains code from\n[Eigen](http://eigen.tuxfamily.org) which requires the \n[MPL-2.0 license](lib/eigen_simple/COPYING.MPL2).\n\n\n#### GPLv2 licensed code (mrc_simple)\nA small subset of the code in \"lib/mrc_simple\" was adapted from ***IMOD***.\nThe IMOD code uses the GPL license (version 2), which is more restrictive.\nLicense details for the \"mrc_simple\" library can be found in the\n[COPYRIGHT.txt](lib/mrc_simple/COPYRIGHT.txt)\nfile located in that directory.\n*If you write your own code using the \"visfd\" library to analyze 3D images\n(which you have loaded into memory by some other means),\nthen you can ignore this notice.*\n\n\n## Funding\n\nVISFD was funded by NIH grant R01GM120604.\n\n\n## Citation\n\nIf you find this program useful, please cite DOI\n[10.5281/zenodo.5559243](https://doi.org/10.5281/zenodo.5559243)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjewettaij%2Fvisfd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjewettaij%2Fvisfd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjewettaij%2Fvisfd/lists"}