Improve Usability and Documentation

hanslovsky commented 5 years ago

At the moment, Paintera is really hard to use for first-time users, we need to improve documentation, including (but not limited to):

[x] Usage example and better documentation for paintera-conversion-helper.
[ ] Provide converted example data. I suggest we convert CREMI (raw and neuron_ids) and add a downlink on cremi. What do you think @axtimwalde? For this to work, we would have to fix #207 first
[ ] Step-by-step instructions from hdf5 file or n5, to conversion, to loading raw and label data inside Paintera, and working on it.
- [ ] as a wiki on this GitHub with screenshots.
- [ ] Video tutorials showing some workflows and common use-cases would be very helpful.
[ ] List of keybindings inside Paintera (this is related to #245).
[x] More detailed installation instructions (tbh the current way of installing it is too complicated for most non-computer scientist users, but that's a different topic).
[ ] Provide specifications / better explanations of the data model
- [ ] fragment-segment-assignment
- [ ] label-block-mapping
- [ ] label-multiset https://github.com/saalfeldlab/imglib2-label-multisets/issues/10
[ ] Standalone application with self contained application packaging, but fix #252 first.

If you have any other ideas for improvement, please let me know, so I can add them to the topic (or modify the initial comment directly if you have permission).

cc @uschmidt83 @constantinpape

constantinpape commented 5 years ago

For first-time users:

Video tutorials showing some workflows and common use-cases would be very helpful.
More detailed installation instructions (tbh the current way of installing it is too complicated for most non-computer scientist users, but that's a different topic)

Related: For developers:

Provide specifications / better explanations of the data model (e.g. format of fragment-segment-assignment, label-block-mapping, label-multiset)

hanslovsky commented 5 years ago

@constantinpape Can you be a little more specific about what is hard about the installation process? I can see multiple issues:

Java installation with JavaFX, especially on Ubuntu. This will hopefully be not necessary anymore soon (upstream dependency needs to be fixed for that).
Maven installation and making sure that it is on the PATH.
conda installation and use (could be alleviated by providing paintera on PyPI).
Starting Paintera from CLI, making sure that conda is set up properly, and finding the right prompt might be an issue. I guess people would prefer to have an icon that they can click on the desktop/start menu/application list.

Maybe, the self-contained application packaging is a better solution.

hanslovsky commented 5 years ago

Thanks @uschmidt83 and @constantinpape for raising these issues in person or through this thread. Please add more as they come up.

constantinpape commented 5 years ago

@hanslovsky Regarding the installation process: All the 4 points you brought up are very relevant.

From my experience, for a lot of potential users the best option would be a FIJI package, or if this is not possible due to JavaFX dependencies, a self-contained package.

4\. I guess people would prefer to have an icon that they can click on the desktop/start menu/application list.

Yes, if you want to target a very broad audience, ideally it would be possible to install and use paintera without any need for the command line.

hanslovsky commented 5 years ago

Relevant maven plugin for self-contained application packaging: https://github.com/javafx-maven-plugin/javafx-maven-plugin

uschmidt83 commented 5 years ago

I think it's important to have intended target users in mind to prioritize these things. The README says

Paintera is a general visualization tool for 3D volumetric data and proof-reading in segmentation/reconstruction with a primary focus on neuron reconstruction from electron micrographs in connectomics.

I realize that I'm not an intended target user, but I think Paintera would also be great to create or proof-read annotations for light microscopy. I don't think there's a better tool at the moment.

constantinpape commented 5 years ago

I think it's important to have intended target users in mind to prioritize these things. The README says

Paintera is a general visualization tool for 3D volumetric data and proof-reading in segmentation/reconstruction with a primary focus on neuron reconstruction from electron micrographs in connectomics.

I realize that I'm not an intended target user, but I think Paintera would be also be great to create or proof-read annotations for light microscopy. I don't think there's a better tool at the moment.

I agree. We have been using paintera for multiple applications in the lab, ranging from proof-reading light-sheet videos to EM cell and ultra-structure segmentations. It's the only available tool to do these things at scale right now (at least as far as I am awar), so it is of broader interest than just Connectomics.

hanslovsky commented 5 years ago

FWIW the paintera command can now be installed through pip:

pip install paintera

paintera-conversion-helper is not available yet (saalfeldlab/paintera-conversion-helper#25)

hanslovsky commented 5 years ago

saalfeldlab/paintera-conversion-helper#26 will make the CLI of the conversion helper a little more user friendly (the comma-separated syntax is very clunky) and saalfeldlab/paintera-conversion-helper#27 will set the confusing --label-block-lookup-backend-n5=10000 by default.

hanslovsky commented 5 years ago

Updated installation instructions in #274 Paintera is now available through pip or conda-forge (no need to specify hanslovsky conda channel anymore)

hanslovsky commented 5 years ago

Added better description of paintera-conversion-helper parameters in #275 This includes a short overview and justification of non-scalar label multisets for label representation and an explanation of the -m option.

constantinpape commented 5 years ago

Another thing: the painter-conversion-helper error messages are currently not helpful at all. It took me half an hour to figure out that one of the in-dataset-path I passed to it was incorrect, because it only yields a very cryptic error message:

Exception in thread "main" java.lang.NullPointerException
        at org.janelia.saalfeldlab.n5.spark.N5ConvertSpark.convert(N5ConvertSpark.java:125)
        at org.janelia.saalfeldlab.conversion.CommandLineConverter.handleRawDataset(CommandLineConverter.java:356)
        at org.janelia.saalfeldlab.conversion.CommandLineConverter.run(CommandLineConverter.java:211)
        at org.janelia.saalfeldlab.conversion.CommandLineConverter.main(CommandLineConverter.java:109)
ERROR 2019-09-05 14:45:12,103: Error in `/usr/bin/java -cp /home/pape/Work/software/conda/miniconda3/envs/paintera/jgo/org/janelia/saalfeldlab/paintera-conversion-helper/0.8.0/* -Xmx7G -Dspark.master=loca
l[*] -XX:+UseConcMarkSweepGC org.janelia.saalfeldlab.conversion.CommandLineConverter -r -d sampleA.n5,volumes/raw,raw -d sampleA.n5,volumes/segmentation/multicut,label -o sampleA_paintera.n5 -b 256,25,25
-s 2,2,1 2,2,1 2,2,1 2,2,2 -m -1 -1 5 3 --label-block-lookup-backend-n5=10000': 1
usage: paintera-conversion-helper [-v] [-u] [-U] [-m] [--ignore-jgorc] [--link-type type] [--additional-jars jar [jar ...]] [--additional-endpoints endpoint [endpoint ...]] [JVM_OPTIONS [JVM_OPTIONS ...]]
 <endpoint> [main-args]

It should at least check for "easy" mistakes like wrong paths or ill-formed scaling arguments and give a human readable error message for this.

hanslovsky commented 5 years ago

This spot in the CommandLineConverter would probably be a good place for such checks. Pull requests always welcome.

hanslovsky commented 5 years ago

@constantinpape FWIW, I am re-writing the conversion helper with improved command line arguments (get rid of the , syntax, in particular). This will deprecate paintera-conversion-helper and add a new command paintera-convert. Not sure about the timeline yet, but it shouldn't take too long. I will also add checks:

fail if input container does not exist
fail if input dataset does not exist
fail if input dataset exists but is group
fail if output exists (unless overwriteExisting is specified)

If one of the datasets fail, the entire job should fail (unless specified to just log failure).

https://github.com/saalfeldlab/paintera-conversion-helper/tree/paintera-convert

hanslovsky commented 5 years ago

@uschmidt83 @constantinpape I created a paintera image with graalvm for easier distribution: https://my.pcloud.com/publink/show?code=XZ1QPHkZdeOPKtQi4HyCqH7DCCUhoXH1Rdo7 Please download and check if it runs on your Linux machine. A few things to note:

This will (likely) only run on Linux
This is a "fallback" image and still requires a JDK (maybe JRE is sufficient) installed on the system. I will inquire and figure out how to make a true native image
I have not found a way to set the max heap size. Supposedly, -Xmx should just work but it does not seem to affect the heap size (according to visualvm)

If this turns out to be a good way to package Paintera, we could just add the native images for each platform (Windows, macOS, Linux) to each release. (2) would be a minor annoyance but not a deal breaker. (3) would be prohibitive.

hanslovsky commented 5 years ago

Actually, do not try yet, we saw this in the lab:

Error: Could not find or load main class org.janelia.saalfeldlab.paintera.Paintera2

hanslovsky commented 4 years ago

I do not have a good way of creating a native launcher, but I started using gradle a few days ago. gradle creates distributions that contain all jars and batch/shell launcher scripts. Users only need to install Java (with JavaFX) and can then simply run this script (as long as the jars remain in the same place relative to the script). The entire folder can be downloaded as archive. This is probably much simpler for many people than going through pip/conda. The distribution could even be used to create installers for Windows/macOS/Linux (but that is not handled by gradle). For an example, check out the use-gradle-for-packaging-command branch:

cd paintera-app-gradle
./gradlew -Pversion=0.24.0 clean build

This will build Paintera with version 0.24.0 and, among other files, create

build/distributions
├── paintera-0.24.0.tar
└── paintera-0.24.0.zip

If you use the installDist task, you will also see

build/install
└── paintera
    ├── bin
    │   ├── paintera
    │   └── paintera.bat
    └── lib
        ├── annotations-13.0.jar
        ├── ...

which you could also just get by extracting the dstributions. You can then start Paintera with

build/install/paintera/bin/paintera

The distributions (with the correct paintera or paintera.bat for each OS) could then be simply attached to each release. It may even be possible to ship (Open)JDK with it.

Note that this does not use the local Maven repo to lookup jars. To do that (e.g. to build from a local SNAPSHOT), add the -PuseMavenLocal flag.

This is just an idea that I wanted to share with you. I will not work on this but I think it may be a good way to make installation easier for non-tech users. This probably needs a little bit of tweaking before being ready for use. Feel free, to work off that branch, modify as you need, get inspiration from the generated shell/batch scripts to create a solution without gradle, or disregard.

cc @igorpisarev @axtimwalde @constantinpape @uschmidt83

saalfeldlab / paintera

Improve Usability and Documentation #251

[x] More detailed installation instructions (tbh the current way of installing it is too complicated for most non-computer scientist users, but that's a different topic).