Frequently Asked Questions

Which output is the "better" or the "true" output of ACCIV, the scattered velocities (outScatteredVelocity.h5) or the gridded velocities (outGridVelocity.h5)? The gridded velocity looks "unphysical" in some places.

Xylar considers the "scattered" vector data to be the "true" output of ACCIV. These data are, for example, what we and our collaborators used to constrain dynamical models when we were studying vortices on Jupiter. But the interpolated velocity also has its uses, depending on your application. We use it ACCIV to advect the images to a common time, which lets us track more features between images than we would otherwise be able to do. ACCIV does not place any physics-based constraints (e.g. divergence-free or physics-based boundary conditions) on the velocity field that it produces, so there is no reason to expect that the interpolated velocity will be consistent with the physics.

Does ACCIV run on Windows as well as Unix (Linux, Mac OSX, etc.)?

Yes, we have had little difficulty getting ACCIV to work under cygwin on Windows. There is also a Visual Studio project file for ACCIV (though it's a bit out of date). The process of building the libraries that ACCIV depends on in Visual Studio is unfortunately rather complicated. Xylar would be happy to help anyone working in Visual Studio to get set up, but we're not supporting this platform unless we see demand for it.

What are the boundary conditions on the ACCIV velocity field?

For the most part, ACCIV has no concept of boundary conditions. Features are correlated between the two images in a box of a size that you choose (this is the most important control parameter you have in ACCIV) over a search range that you also determine. ACCIV doesn't search for correlations anywhere that it can't fit the full box within the full search range (because results get noisier and noisier as they approach the edge if you do so---still maybe noisy data is better than none?---we could consider changing this). So the scattered velocity vectors will simply not include the sides of the image, though the portion of the image that is not covered will shrink as the correlation box size decreases from one pass to the next.

The gridded velocity data does require boundary conditions, and these are simply zero velocity at the edges of the image. This choice was made because we use the gridded velocity data primarily to advect the images to common points in time (then, we perform correlations between the advected images and finally we advect the correlations back to their positions in the original, undavected images). Since there is no image data to advect into the field at the edges, it works best if the velocity is (at least close to) zero at the edges. We have found that this assumption behaves better than trying to extrapolate velocity data to the image edges. However, the proper way to present the grid velocity data would be to crop it to the convex hull of the scattered data, as the extrapolation beyond the convex hull is rather arbitrary.

Is there an automated procedure for choosing ACCIV parameters based on properties of the image data? Or based on quantitative properties of the velocity output?

Xylar's experience is that (at least initially) it takes some experimentation to find what parameters are appropriate for a given image capture system. Overall, he starts with a pretty big correlation box in the first pass and works his way (as quickly as it seems he can get away with) down to the smallest correlation box he can use without producing a noisy velocity field.

The other parameters are more straight-forward to constrain. The search range for the first pass should be a pixel or two more than the maximum motion (in pixels, of course) that you expect between frames. After the first pass, the search range is only relative to the velocity field found in the previous pass, so the value can be quite small, sometimes only two or three pixels in each direction.

The only penalty to having a large stride is more computation time. That parameter shouldn't affect the quality of results other than that a smaller stride produces larger numbers of velocity vectors in the end.

We have found that one important feature of a set of images is the "effective resolution" of the images---we take a Fourier spectrum of the image and see at what length scale you hit the noise floor. (We discuss this in Asay-Davis et al. (2009).) There should be a relationship between this length scale and the minimum correlation box size that produces reasonable results, but we have not worked with a large enough number of disparate datasets to establish this fact with certainty. Still, it seems intuitive that there will not be reliable features to track at length scales where noise dominates.

It has been our goal to automate parameter choices to the degree possible. For us, the types of image data that we get from vastly different spacecraft are just so varied that we find that we have to investigate the image noise level, resolution, alignment, etc. every time we get a new data set. This is something Xylar is happy to work with you on in any way he can.

I'm getting errors about a missing HDF5 (or other) library at runtime. What's going wrong?

If you see an error something like

../../acciv/makeGeometryFactors.exe: error while loading shared libraries: libhdf5.so.101: cannot open shared object file: No such file or directory

the issue is most likely that you have installed HDF5 into a non-standard location that can't be found by your system without your help. This is an issue with dynamic libraries generally and HDF5 (at least with the default configuration) in specific. If you install them in a non-standard location (e.g. /home/xylar/software/hdf5), your system has no way to know where they are unless you tell it. The solution is to add that path to the system variable LD_LIBRARY_PATH:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/xylar/software/hdf5

You don't need to recompile the code, you just need to do that before you run. If you have other libraries in non-standard locations, just add them with colons (:) between each path.