ENH: Add 3D geometry and propagation module

[mdw771]

Geometry:

• Added bounding_box and contains methods in all 3D geometry classes, Cuboid_3d, Sphere_3d, TruncatedCone_3d, and Cylinder_3d.

Material:

• Added CustomMaterial class which takes user specified delta and beta. Useful for describing mixtures.

Plot:

• discete_grometry now works with 3D geometry classes.
• Multiple changes made to discrete_phantom:
  • The prop argument can take a list of strings (e.g. ['delta', 'beta']) to generate grids for multiple quantities. Result grids are returned in list if a list or tuple object is passed.
  • Added energy keyword argument.
  • Added fix_psize argument. When set to False, the function behaves as what it originally is. When set to True, pixel size is fixed at 1 instead of being given by 1.0 / size. This is useful in preventing a over-fine meshgrid in 3D cases which results in intractible computational cost.
  • Added overlay_mode argument. When set to add, the function behaves as what it originally is. When set to replace, geometries in child phantoms replace the voxels with parent values, instead of adding to them.
  • Added return_patch argument. When set to True, the function also returns the geometry patch (as bool type).
  • A try except structure is used to allow the reading of properties in form of both methods and attributes (such as delta and beta in CustomMaterial).

Acquisition:

• Added Simulator class. The object takes in refractive index grids and performs multislice propagation. This class should be used in place of initialize_wavefront and multislice_propagation in the previous propagation module.

Demo codes:

• Amended tests/beyond_dof.py to provide a demo for functions added.

Other changes:

• Removed grid.

[carterbox]

@mdw771, Please fix the error that cause failing Travis builds. It looks like you forgot to remove the import statements for the grid module. There is also an import error for skimage.morphology probably because skimage isn't listed in the requirements.txt or in the install section of travis.yml.

We are targeting both python2.7 and python3.x, so you need to use parenthesis on print statements.

Thanks for your patience in advance. I'm going on vacation next week, but I'll try and review as much as I can today.

[mdw771]

Thanks for the comments.

• All occurrences of import xdesign.grid have been removed.
• tests/3d_brain.py and tests/test.py are outdated scripts used for testing the old version of the package. They have been removed.
• tests/beyond_dof.py has been renamed as tests/test_tube_particles.py and the codes are included in function test_model_prop_pipeline.py.
• Units of Input parameters of Simulator class were changed to cm and eV.
• Added docstring to Simulator.initialize_wavefront. Options will be explained in documentation in later commits.
• warnings module used for WARNING strings.
• Modified acquisition.tomography_3d. Changed phase retrieval method to paganin. tomopy.retrieve_phase is used.
• Added contains method to Cylinder_3d.
• Added back import phasepack in metrics.
• I temporarily hold the parameter fix_psize in discrete_phantom in place. The reason for this extra parameter is that in discrete_geometry a grid with side length of approximately (xmax - xmin) / psize pixels is created. For 3D object a grid size like this is computationally intractable. psize and thus size has to be set to 1 to prevent the creation of an over-large grid, but this results in a one-pixel data grid. I suggest that the discrete functions takes only the number of pixels per side for the grid and simply assume the real-size of each pixel to be 1, since are not important unless physics calculations (eg. propagation simulation) is involved.
• discrete_phantom: TypeError will be raised when invalid material properties are enquired. Property retrieval methods in Material and its child classes are modified with keyword argument for energy.
• Added my name to __author__ in propagation and geometry.
• Moved plot_wavefront from propagation to plot.

[carterbox]

I suggest that the discrete functions takes only the number of pixels per side for the grid and simply assume the real-size of each pixel to be 1, since are not important unless physics calculations (eg. propagation simulation) is involved.

I don't understand. Why is the real size of each pixel not important? Every Entity has a real size in centimeters, so how is the real size of each pixel not important?

Also, all the TravisCI tests need to pass before this pull is approved.

[mdw771]

I suggest that the discrete functions takes only the number of pixels per side for the grid and simply assume the real-size of each pixel to be 1, since are not important unless physics calculations (eg. propagation simulation) is involved.

I just realized that the point coordinates are supposed to be given in cm instead of in pixels. Now this makes more sense to me. But I still suggest to change the current scheme that fixes the entire sample size at 1 cm to a scheme that requires inputs of individual pixel size and number of pixels (grid size). When the model is used for microtomography or holographical studies people are generally interested in resolution of micron or nanometer level. It is necessary in such cases to let users specify the pixel size in order to limit the grid size.

[carterbox]

people are generally interested in resolution of micron or nanometer level

What I think you mean is: having a 1 cm field of view is too large for some experiments; the ability to specify a smaller region for plotting or discretization is good.

I agree :smile:. I think the best way to handle this is to have two keyword arguments such as below for the discretization function.

"""
psize : float
    The side length of a cubic pixel.
bounding_box : :py:class:`numpy.ndarray`, :py:class:`List`
    The desired field of view specified as `[min, max]` where min and max
    are two column vectors pointing to the min and max corners of the
    desired field of view.
"""

bounding_box would default to [[0, 1], [0, 1], [0, 1] ...].

Does that sound good?

[mdw771]

I think the best way to handle this is to have two keyword arguments such as below for the discretization function.

This would address the problem, but I'm thinking of another way which seems more straightforward: we set 3 keywords arguments:

"""
psize : float
    Side length of a pixel or voxel in cm.
grid_length : float
    Length of a side of the grid in cm (this is the quantity that was originally
    default to 1 cm).
grid_size : int
    Number of pixels along a side of the grid (this is the original "size" argument).
"""

All arguments default to None and user shall supply any 2 of them for the function to infer the other one. In this way the grid dimension is not necessarily 1 cm, but the function would be more flexible for various situations. How do you think of this?

[carterbox]

I have two arguments for the 2 arg API over the 2 of 3 arg API.

1. The advantage of specifying the bounding_box is that you can reduce computation by avoiding empty regions. grid_length and grid_size and psize, tells how many pixels are wanted but not where they are wanted, so the problem is under-defined. If you assume the grid includes the origin, this could be expensive if your object of interest is very small and far away from the origin.

2. I oppose the "choose only two of three optional arguments". I tried that with another API, and it made the code messy. You have to check user inputs to make sure only 2 of the 3 choices were supplied, and you have to convert the input to the parameters that the implementation actually uses.

[mdw771]

Travis test of test_tube_particles.test_model_prop_pipeline fails on server due to the absence of xraylib. After adding xraylib in requirements.txt and inserting conda install xraylib in .travis.yml, the building process seems stuck and went timeout after 10 min. Local tests all went through with Python 2.7.13 (Anaconda) except a Not equal to tolerance rtol=1e-07, atol=0.01 failure in tests.test_3d.test_probe_circular.

[coveralls]

Changes Unknown when pulling f8baf6db5e95ade3a011356b175e0cb8a01378ed on mdw771:master into on tomography:dev.

[coveralls]

Changes Unknown when pulling f8baf6db5e95ade3a011356b175e0cb8a01378ed on mdw771:master into on tomography:dev.

[coveralls]

Changes Unknown when pulling 9197326722e4f9033f48b315869d8a148b41dd0e on mdw771:master into on tomography:dev.

[carterbox]

Travis failed because test_probe_circular. This test fails like 1/10 times because #53, so I'm ignoring it.