mrpeek: a sixel-based terminal image viewer for MRtrix3 #202
Description
Guidelines
We are very excited to meet you at the 2020 OHBM Brainhack 🎉 To submit a project, you need to be an attendee of the 2020 OHBM Brainhack. We ask you to register first over here. Thank you!
We have prepared a checklist to help with your project submission. Here is how to proceed:
- Before filling in any part, please submit this issue
- Check items in the checklist below as you go through them
- Once you are done (at least all 'required' items must be provided), please delete the "Guidelines" section add a comment saying 'hi @ohbm/project-monitors: My project is ready!'
Thank you!
After step 1 (issue submitted), we will assign a 'project monitor' to follow your submission. If at any time you need help or anything is unclear, please add a comment and ping your project monitor. Our team is here to help!
Project info
mrpeek: a sixel-based terminal image viewer for MRtrix3:
Project lead:
- J-Donald Tournier @jdtournier
- Daan Christiaens @dchristiaens
- Max Pietsch: @maxpietsch
Timezone: London UTC+1
Hub: Europe, Middle East and Africa
Description:
Displaying images on a remote server is very difficult / impossible currently using MRtrix3's mrview, due the incompatibility of OpenGL 3+ with X11 forwarding (see here for details). It will be some time before the technology is updated to fix this.
In the meantime, @wasserth's niicat project shows that it is possible to allow some (limited) display functionality using sixel. The libsixel project provides an implementation that seems like a good starting point for a C++ command.
The aim of this project is to create a simple command for interactive display of MR images within the terminal, build on the MRtrix3 codebase, so that it can be used for quick inspection of images both locally and remotely.
If successful, changes will be included in a future update to the MRtrix3 software. Contributors will be included in the built-in git contribution statistics. We additionally credit contributors by showing their avatar at the bottom of the MRtrix3 website front page, and in the changelog as reported on the community forum (example).
Link to project: MRtrix3/mrtrix3#2079
Mattermost handle: jdtournier
Goals for the OHBM Brainhack
The range of possible milestones are presented in MRtrix3/mrtrix3#2079. The minimum requirements for the Hackathon would be:
- extract a given slice of interest and render it to the terminal using libsixel
- implement options or other user controls to select the slice of interest, projection (axial/sagittal/coronal), and brightness/control
- implement real-time interaction based on keyboard input
- implement real-time interaction based on mouse input
Good first issues:
- Install MRtrix3 from source and set up an external linked module to create your own app
- build a simple MRtrix3 app that can loop over a single slice of an image and extract the intensities (inspired by e.g. MRtrix3's mrcolour)
- install libsixel and add it as a dependency to your project (by editing your
configfile if needed) - work out how to feed the image intensities from the input data in a format suitable for libsixel, and display to the terminal
Skills:
Some experience with C++ is essential for this project. Experience with git and Unix in general would be advantageous. The pace of the project will however be tailored to the skillset of team members. No prior expectations are set on the quantity of team members.
Chat channel: hbmhack-mrpeek
Video Channel
Please have a look at the Mattermost channel(pinned posts) for the URL of the video channel, or alternatively, please contact to @jdtournier on Mattermost.
Image for the OHBM brainhack website
Project submission
Submission checklist
Once the issue is submitted, please check items in this list as you add under 'Additional project info'
Please include the following above (all required):
- Link to your project: could be a code repository, a shared document, etc. See here
- Include your Mattermost handle (i.e. your username). If you do not have an account, please sign up here.
- Goals for the OHBM Brainhack: describe what you want to achieve during this brainhack. See here.
- Flesh out at least 2 "good first issues": those are tasks that do not require any prior knowledge about your project, could be defined as issues in a GitHub repository, or in a shared document, cf here.
- Skills: list skills that would be particularly suitable for your project. We ask you to include at least one non-coding skill, cf. here.
- Chat channel: A link to a chat channel that will be used during the OHBM Brainhack. This can be an existing channel or a new one. We recommend using the Brainhack space on mattermost, cf. here.
- Video channel: Please create a video channel that will be used during the OHBM Brainhack and share it in your chat channel above. This can be an existing channel or a new one. For instance a jitsi meet room, cf. here.
- Provide an image of your project for the OHBM brainhack website
You can also include information about (all optional):
- Number of participants, cf. here
- Twitter-size summary of your project pitch, cf. here
- Set up a kanban board on your repository to better divide the work and keep track of things, cf here
- Project snippet for the OHBM Brainhack website, cf. here
We would like to think about how you will credit and onboard new members to your project. We recommend reading references from this section. If you'd like to share your thoughts with future project participants, you can include information about (recommended):
- Specify how will you acknowledge contributions (e.g. listing members on a contributing page).
- Provide links to onboarding documents if you have some.