Skip to main content

Object-oriented CIVET bindings for Python

Project description


.github/workflows/test.yml PyPI License - MIT

Python bindings for CIVET binaries like transform_objects and mincdefrag.


pycivet is a helper library which provides a Python API that wraps CIVET binaries with object-oriented syntax. Intermediate files are written to temporary locations and cached.


Consider this bash script:

temp1=$(mktemp --suffix=.mnc)
mincresample -quiet -double mask.mnc $temp1
mincblur -quiet -fwhm $temp1 $temp2
mv "${temp2}_blur.mnc" blurred_mask.mnc
rm $temp1

The equivalent using pycivet:

from civet.minc import Mask

This Perl code snippet from can be expressed in Python as such:

from civet import starting_models


It is recommended you install this package in a container image, e.g.

RUN pip install pycivet


Typically, bioinformatics and neuroinformatics pipelines such as CIVET and FreeSurfer are comprised of many binary programs and a script in csh or perl which glues together those binary programs and their intermediate results. These scripts look something like:

do_something input.mnc /tmp/1.mnc
another_thing /tmp/1.mnc /tmp/2.mnc
create_thing /tmp/3.mnc
many_thing /tmp/2.mnc /tmp/3.mnc /tmp/4.mnc

We propose that the readability and maintainability of such scripts can be improved using modern programming language features such as type hints. These advantages would enable to faster development and with fewer bugs. pycivet explores this concept with CIVET subroutines.


pycivet is an object-oriented Python API to CIVET binaries.

Intermediate Files

Intermediate files are used to pass results between subroutines. This chore is handled transparently by the pycivet.memoization submodule.

Consider this excerpt from

&run( "param2xfm", "-scales", -1, 1, 1,
    "${tmpdir}/flip.xfm" );
&run( "transform_objects", $ICBM_white_model,
    "${tmpdir}/flip.xfm", $initial_model );
unlink( "${tmpdir}/flip.xfm" );
&run( "param2xfm", "-translation", 25, 0, 0,
    "${tmpdir}/slide_right.xfm" );
&run( "transform_objects", $initial_model,
    "${tmpdir}/slide_right.xfm", $initial_model );
unlink( "${tmpdir}/slide_right.xfm" );

Using pycivet we can express the code more concisely:

from civet.obj import Surface


Repeated calls on the same object are cached. This is primarily for the sake of internal code quality, but it can also be taken advantage of externally:

from civet.memoization import Session
from civet.obj import Surface

with Session() as s:
    surf = Surface('input.obj'), 'flipped.obj'), 'flipped_and_slid.obj')

In the example above, the following subroutine commands are cached:

  • param2xfm -scales -1 1 1 flip.xfm
  • transform_objects input.obj flip.xfm flipped.obj


Only results which are needed (by save) are computed.

from civet.obj import Surface
surf = Surface('input.obj')
surf.slide_right()  # does nothing
surf.slide_left().save('left.obj')  # runs param2xfm, transform_objects, ...


Only methods relevant to an object's type are available to be called on that object. For instance, an object representing a .obj surface file would have the methods flip_x() and translate_x(n), and an object representing a .mnc volume would have the methods minccalc_u8(...) and mincdefrag(...) defined, but you cannot call Surface('input.obj').mincdefrag(1, 19). Subroutines and their usage are discoverable through autocomplete features of an IDE that supports type-hints.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycivet-0.1.2.tar.gz (16.6 kB view hashes)

Uploaded source

Built Distribution

pycivet-0.1.2-py3-none-any.whl (19.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page