Tutorial 3d tracking

[caspervdw]

This is a tutorial for tracking in 3D. It makes use of pims.ImageSequence3D, the anisotropic feature finding (https://github.com/soft-matter/trackpy/pull/162) and trackpy.annotate3d.

edit: and I sould refer to https://github.com/soft-matter/trackpy/issues/205

[danielballan]

Nicely done. I learned some things from reading. For future readers, here is direct link to the tutorial on nbviewer.

Here are some minor suggestions none of them show-stoppers:

• You left an extra word in, "we can have to use the python engine." Incidentally, I intended for the refine logic to default to the python engine if the input image are not 2D. I think the logic is mangled, and so it is currently necessary to specify engine='python'. I will fix this before 0.3, but I think you should leave the tutorial as is, explicit about how this works.
• You wrote, "the z resolution is very bad." Maybe, "very low" would be clearer.

I'm very excited to have this. I've been told that Professor Crocker himself recently dropped by our documentation and wondered whether we would add higher-dimensional tracking. This is good advertising for that capability.

[tacaswell]

Awesome :+1:

[caspervdw]

I just pushed some minor changes, for my part it can be merged.

Shall I make a 3D tracking picture for the tutorial homepage? I have a nice picture of tracks on particles confined to a big sphere.

Is it possible to clarify somewhere that I authored this tutorial, as well as (some of) the functions it refers to? I am spending a lot of time on these things and it would be nice to have my name somewhere, also for future code.

[nkeim]

Excellent! Like I said, this is a marquee feature of trackpy, so to speak.

A homepage image would be great. It seems like we can replace the fluorescent particles image from the homepage (the only one with bright particles on a black background); its visual appeal is limited when it's just a thumbnail.

As for attribution: we want to get it right. Expect an email.

[nkeim]

My corrections (sorry for the delay):

Under "Linking":

• Terminology: The argument pos_columns...
• Phrasing: The standard set of columns is ['x', 'y'].

After cell 12:

• "iterpret" ➔ interpret

[caspervdw]

Thanks for the feedback! I pushed the changes you suggested.

[caspervdw]

I made a PR in pims to reduce the number of files in this example. If this is merged, I can replace the 800+ .png files with one zipfile.

[tacaswell]

https://github.com/soft-matter/pims/pull/138 <- relevant PIMS PR

[caspervdw]

Thanks for the reference. I just force-pushed the zipfile, so that the png files are out of the repo.

[nkeim]

Awesome! Since this image "format" could be confusing to a new reader, however, it's probably best to mention it in the tutorial — explain that normally, PIMS reads a directory of 2D image files with this special naming scheme, and that the zip file just contains such a directory. And that the reader is free to unzip the file and see these images directly.

[danielballan]

We should also note (in the notebook) that this requires the dev version of PIMS. As long as it's mentioned I don't think it's a problem. There should be a PIMS release before or in coordination with the next trackpy release.

[caspervdw]

In the first block it says "PIMS and Trackpy v0.3 are required.", isn't that enough? As v0.3 isn't there yet, it's should be clear that currently, you should use the dev version.

[danielballan]

OK, I think the message on the index page of the docs should clarify the situation well enough. Until v0.3 is released, the situation is a little muddy, and there's only so much we can do about that.