How Revealing!

As part of the 2018 CCI Imaging Workshop, I ran a guided hands-on about using Fiji for Image Analysis. The workshop was aimed at complete novice and intermediate level users. The slides and materials were delivered through a web browser using the Reval.js framework, and this post will be a few more details on that framework and how (and why) I think it’s really useful for this sort of thing. Let’s get revealing!

Inspiration

I’ve seen browser-based presentations before at the OME users’ meeting and also from the LOCI group (chiefly Ellen Arena and Curtis Rueden). When others are fiddling with arcane adaptors and worrying about movies not playing, they roll up, open a web browser and go. It sounds silly but it’s impressive to behold something that just works.

So what is it?

The underlying framework is called Reveal.js. The idea is to use clever CSS and javascript to give the impression of a continuous slide show that you can control from a keyboard or even swipe gestures if you’re on a mobile device. Throw the files into a webserver front-end like Apache or NGINX, or open the files locally and you have a presentation!

The problems with running workshops

Here are some of the problems I’ve had (or seen people experience) with workshops in the past:

  • I can’t keep up! Everyone goes at their own pace, and if the presenter is going too fast, not everyone is comfortable putting their hand up and asking them to slow down. It’s so easy to miss instructions, references or code examples.
  • I can’t see! Many computer labs are not designed for everyone to be able to see the teaching screen well and some people’s eyesight is not great.
  • I can’t get to the workshop! Regular listeners will know I love Live Tweeting, and one of the reasons to do this (the less selfish one) is to make conference content open and accessible to people who can’t get to meetings (parents on leave, people whos funds don’t cover travel or accommodation to get to conferences etc). If slides are ever distributed it’s often as a PDF after the fact to attendees.
  • I can’t type fast enough! Related to the first point but a particular problem with coding workshops. The presenter does a live demo writing out some code, expecting the class to copy down and play along. Problem is, you make one typo and you’ve scuppered your function/code/script. Boo.
  • MOAR USB KEYS: Image Analysis workshops especially, require training material. How do you get this to people? Email it ahead of time? Pass USB keys around? dropbox? Network shares? I’ve suggested bit-torrent for big datasets before, but all these come with technical challenges and hand-holding through unzipping, mapping shares etc.

One possible solution

I was interested in Reveal.js as a way to solve a lot of these problems. I’ll try to give a brief walkthrough of how I built the presentation and this should highlight where some of these problems are solved.

You can download the source from here. If you have git installed locally, it’s as easy as making a new folder and running:

git clone https://github.com/hakimel/reveal.js.git .

You’ll end up with a few folders and a few files:

Version controlling your nascent presentation is an excellent idea. Go read this post and come back when you’re ready.

Your whole presentation will be a single html file. Index.html is a boilerplate from which you can build your presentation. There are code examples in demo.html and also loads on the repo website.

Making it mine

Below are some ways that I adapted the original framework to make it look like the final thing:

Theme

There are basically only two files that I edited to create the slides. The first was to define a custom CSS style for my slides. I already have slide templates and a font that I use for CCI presentations, so I wanted to replicate that as closely as possible. I copied the white.css file found in css > theme to a new file (cci.css) then started tweaking the colour scheme. The typeface and the new theme are specified in the HTML file inside the head section:

Slides

Each slide in the HTML document is demarcated by the <section></section> pair. To add a new slide, add a new section to the document. One of the cool things about the section tags is that you can next multiple sections within each other which make vertical slides. Lots of people like these for logical grouping and easy navigation. I chose to remove the navigation arrows on my slides so I decided against using vertical slides (apart from for one aside).

Layouts

If you’re used to making powerpoint or keynote presentations, this is probably where Reveal.js is going to seem clunky and awkward. If you’re used to writing HTML and designing websites, this is going to be a snap. You need to think of your slides as boxes into which you can align other boxes of relative width. In CSS you use something called a class to describe a rule that you want to apply to everything with that class. I don’t remember which ones are built-in but I defined each of the following classes (except the top one which is the default size if you specify no class).

The basic elements that I used in my slides are:

  • <p> : Paragraph : A general purpose block of text. Useful for adding an explanation or point.
  • <ul> : Unordered list : Bullet points for instructions or steps the attendees have to follow (also <ol>for numbered lists)
  • <img>: Images : loads of these in the presentation and in some cases, more complex layouts and schematics are easier to create in inkscape or screen capture from an existing presentation.

The point here is that all of these elements can have any class added to them to get your layout right. Below is an example of half unordered list and half image:

The code looks like this:

<ul class="left half">
<li><code>[Image > Crop]</code>: Reduce the canvas size to current area selection</li>
<li><code>[Image > Duplicate]</code>: Duplicate the selected window/stack or selection</li>
<li><code>[Image > Rename]</code>: Change the title of the window</li>
<li><code>[Image > Scale]</code>: Scale the image pixels up or down (calibration is also scaled)</li>
</ul>
<img class="third" src="img-ia/basics_01.png"/>

The other three classes I used are left , right and clear to deal with floats which I will say no more about here.

Added Value

There are loads of cool features of Reveal and plugins written for it that are nice for workshop presentations. I included a the slideout menu from Greg Denehey, slide numbers, fragments (which are like animations for making parts of the presentation animate) and my ‘master’ elements (my twitter handle, UoL and CCI logos) using absolute positioning. Getting a title on each page is a bit of a hack but it seems to work well.

Data

I’m of two minds about how well this worked. I made a folder called materials in the repo and put the images I’d need for the workshop into that folder. I then hyperlinked to the files in the relevant slides. I explained to people that they can either use the URL (see pros below) to open files or save them to a folder and drag them in.

PROS:

  • You can provide links right where the user needs them. No more guesswork about which image is the one you should be working on
  • You can import directly into memory using the [File > Import > URL] option in Fiji
  • No need to download the datasets ahead of time. You have them right when you need them.
  • Instant update: If, mid workshop you find you need to update a test image, you can do that then ask everyone to access it again!

CONS:

  • Images opened with the URL option have some problems:
  • Anything that can be opened by a web browser will be, instead of offering the files for download (IE PNG files will simply be displayed, although this is not a problem if you use the URL method)
  • Anything done with multiple files (IE a batch processing or stitching walk-through) requires users to download an archive then unzip it. Not difficult but it’s extra steps.
  • Not realistic for huge files or datasets (eg Multiview Reconstruction)

Overall, I think the ease of content delivery out weights the slight awkwardness.

Running the workshop

Somewhat predictably as I ended up using it, all of the problems mentioned earlier are solved or at least tempered using Reveal.js for a workshop. Indeed most of the issues are solved by the users having a copy of the slides open on their own PC during the workshop (something you can do if you’re organised enough to share your slidedeck, the users have the right software, are on the right platform etc). Some other really nice features of Reveal.js:

  • If you’re using code examples, people can copy paste them directly from the web page. No more typos!
  • The same way you can deliver test data you can also hyperlink to anything else, scripts, library files, plugins etc.

Given a bit of twitter promotion, people can always play along with the slides from home, although there is lots of content that is delivered by the presenter that you do not have access to without the slides. Perhaps I’ll sort out a live web stream next year?

Epilogue

The one thing that has not been mentioned here is the requirement to know a bit of HTML/CSS to put together your slide decks. I’ve written a few websites, and when I do so, it’s always using Notepad++.

The problem is, like any markup language, you quickly lose it if you don’t practise. Using HTML/CSS kung-fu for something other than websites is a great way to keep your skills honed!

Advertisements

2 thoughts on “How Revealing!

  1. Jan Eglinger

    Thanks for sharing the course slides, that’s great material!
    I’ve recently also had good experience with using Jupyter/BeakerX notebooks and RISE.

    Pros:
    – easily, interactively editable presentations
    – Markdown instead of HTML, which some might consider a little easier to read and edit
    – the ‘splitcell’ notebook extension allows for simple two column layout
    – share your RISE presentations via an interactive mybinder.org link

    Cons:
    – to run the presentation locally and edit it directly in your git repository, you need a jupyter environment (which is however as easy as running `conda env create -f environment.yml`)
    – a little less flexibility regarding styling (you can provide your own rise.css however)

    Regarding the File > Import > URL issues with hyperstacks: would you mind reporting the issue on the forum or the imagej1 repository? I think we should work together to make the user experience better here. I also observed that with https links from the forum, the import doesn’t work currently.

    Liked by 1 person

    Reply

Comment!

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.