Merge remote-tracking branch 'origin/master' into near_field_ptycho

.github/workflows/main.yml

@@ -94,9 +94,8 @@ jobs:
           uv pip install ."[docs]"
 
       - name: Build docs
-        working-directory: docs
         run: |
-          make html
+          uv run python -m sphinx -b html docs/source docs/build/html
 
       - name: List files in docs/build/html
         run: |

README.md

@@ -28,6 +28,8 @@ plt.show()
 
 Further documentation is found [here](https://cdtools-developers.github.io/cdtools/).
 
+Instructions for building custom documentation based on a specific version or commit can be found [here](https://github.com/cdtools-developers/cdtools/blob/master/docs/build_custom_docs.md).
+
 # Installation
 
 CDTools can be installed in several ways depending on your needs. For most users, installation from pypi is recommended. For developers or those who want the latest features, installation from source is available.

docs/build_custom_docs.md

@@ -0,0 +1,57 @@
+# Build custom docs
+
+This is a short description how to build custom documentation with `sphinx` based on the exact version (or even commit) you are using. 
+
+This requires a cloned version of `cdtools` from GitHub. See the installation guide for more information: 
+
+https://cdtools-developers.github.io/cdtools/installation.html#option-2-installation-from-source
+
+
+## Installation of Dependencies
+
+First, ensure you have all necessary dependencies installed. You can do this using [`uv`](https://github.com/astral-sh/uv) or `pip`:
+
+
+```sh
+uv pip install ."[docs]"
+# or, if you prefer pip:
+pip install ."[docs]"
+```
+
+This will install your project along with the extra dependencies required for building the documentation.
+
+**Note:** `uv` is a fast Python package installer and resolver, serving as a drop-in replacement for `pip` with improved performance. You can use either `pip` or `uv` as shown above.
+
+
+## Checkout the version or commit
+
+To ensure your documentation matches a specific version or commit of your codebase, use `git` to checkout the desired state. For example, to checkout a specific tag or commit:
+
+```sh
+git checkout <tag-or-commit-hash>
+```
+
+Replace `<tag-or-commit-hash>` with the version tag (e.g., `v1.2.3`) or the commit hash you want to use. This ensures the documentation is built for the exact code you are working with.
+
+## Building the Documentation
+
+To build the HTML documentation, run the following command from the root of your project:
+
+```sh
+uv run python -m sphinx -b html docs/source docs/_build/html/
+```
+
+This command tells Sphinx to build the documentation located in the `docs/source` directory and output the HTML files to `docs/_build/html/`.
+
+You can then open the generated HTML files in your browser to view the documentation.
+
+
+## Get back to the latest version of cdtools
+
+To return to the latest version of your code, use:
+
+```sh
+git checkout master
+```
+
+This will switch your working directory back to the latest development branch.

src/cdtools/datasets/ptycho_2d_dataset.py

@@ -220,7 +220,8 @@ class Ptycho2DDataset(CDataset):
             logarithmic=True,
             units='um',
             log_offset=1,
-            plot_mean_pattern=True
+            plot_mean_pattern=True,
+            plot_mask=False,
     ):
         """Launches an interactive plot for perusing the data
 
@@ -241,7 +242,7 @@ class Ptycho2DDataset(CDataset):
                 mask = 1
                 
             if logarithmic:
-                return np.log(meas_data + log_offset) / np.log(10) * mask
+                return np.log10((meas_data * mask) + log_offset)
             else:
                 return meas_data * mask
 
@@ -268,6 +269,9 @@ class Ptycho2DDataset(CDataset):
 
         if plot_mean_pattern:
             self.plot_mean_pattern(log_offset=log_offset)
+
+        if plot_mask:
+            plotting.plot_real(self.mask, title='Dataset Mask')
             
         return plotting.plot_nanomap_with_images(self.translations.detach().cpu(), get_images, values=nanomap_values, nanomap_units=units, image_title='Diffraction Pattern', image_colorbar_title=cbar_title)
 

src/cdtools/models/bragg_2d_ptycho.py

@@ -258,6 +258,7 @@ class Bragg2DPtycho(CDIModel):
             obj_padding=200,
             obj_view_crop=None,
             units='um',
+            surface_normal=None
     ):
         wavelength = dataset.wavelength
         det_basis = dataset.detector_geometry['basis']
@@ -278,24 +279,39 @@ class Bragg2DPtycho(CDIModel):
                         distance,
                         oversampling=oversampling)
         
-        # now we grab the sample surface normal
-        if hasattr(dataset, 'sample_info') and \
-           dataset.sample_info is not None and \
-           'orientation' in dataset.sample_info:
+        # Now we define the surface normal
+        # The surface normal definition is based on the following heirarchy:
+        #   manual surface_normal definition > scattering_mode
+        #   > dataset.sample_info['orientation'] > transmission geometry
+        if surface_normal is not None:
+            surface_normal = np.asarray(surface_normal)
+        elif isinstance(scattering_mode, str):
+            if scattering_mode.strip().lower() in {'t', 'transmission'}:
+                surface_normal = np.array([0.,0.,1.])
+            elif scattering_mode.strip().lower() in {'r', 'reflection'}:
+                outgoing_dir = np.cross(det_basis[:,0], det_basis[:,1])
+                outgoing_dir /= np.linalg.norm(outgoing_dir)
+                surface_normal = outgoing_dir + np.array([0.,0.,1.])
+                surface_normal /= np.linalg.norm(outgoing_dir)
+        elif scattering_mode is not None:
+            raise ValueError(
+                'Scattering mode must be either "transmission" ("t"), "reflection" ("r"), or the default of None.'
+            )
+        elif hasattr(dataset, 'sample_info') and \
+             dataset.sample_info is not None and \
+             'orientation' in dataset.sample_info:
+            # If the scattering_mode has not been defined, we grab
+            # this from the cxi file if its present.
             surface_normal = dataset.sample_info['orientation'][2]
         else:
-            surface_normal = np.array([0.,0.,1.])
-            
-        # If this information is supplied when the function is called,
-        # then we override the information in the .cxi file
-        if scattering_mode in {'t', 'transmission'}:
-            surface_normal = np.array([0.,0.,1.])
-        elif scattering_mode in {'r', 'reflection'}:
-            outgoing_dir = np.cross(det_basis[:,0], det_basis[:,1])
-            outgoing_dir /= np.linalg.norm(outgoing_dir)
-            surface_normal = outgoing_dir + np.array([0.,0.,1.])
-            surface_normal /= np.linalg.norm(outgoing_dir)
+            surface_normal = np.array([0., 0., 1.])
 
+            # Guard against any surface_normal entries that are not castable
+        # to a length-3 numpy vector, with a sensible error message
+        if not surface_normal.shape == (3,):
+            raise ValueError(
+                '`surface_normal` needs to be a numpy vector with 3 elements. If it was set incorrectly from dataset.sample_info, consider explicitly setting it via the `surface_normal` keyword argument.'
+            )
         # and we use that to generate the probe basis
 
         ew_normal = np.cross(np.array(ew_basis)[:,1],