Add test data to package, improve docs (#36)

* Bump version to the usual development increment 0.2.dev0 Signed-off-by: Håkon Wiik Ånes <[email protected]> * Explain need of pixel size in PC array with vendor="EMSOFT" Signed-off-by: Håkon Wiik Ånes <[email protected]> * Make sure OpenCL kernels and test pattern is included in wheel Signed-off-by: Håkon Wiik Ånes <[email protected]> * Update changelog Signed-off-by: Håkon Wiik Ånes <[email protected]>
USNavalResearchLaboratory · Aug 5, 2022 · bbcf484 · bbcf484
1 parent 2bb8532
commit bbcf484
Show file tree

Hide file tree

Showing 5 changed files with 66 additions and 34 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -5,6 +5,19 @@ Changelog
 All notable changes to PyEBSDIndex will be documented in this file. The format is based
 on `Keep a Changelog <https://keepachangelog.com/en/1.1.0>`_.
 
+Unreleased
+==========
+
+Added
+-----
+- Explanation that the pixel size must be passed as the forth PC value whenever
+  ``vendor=EMSOFT`` is used.
+
+Fixed
+-----
+- OpenCL kernels and test data are also included in the built distribution (wheel), not
+  only the source distribution.
+
 0.1.0 (2022-07-12)
 ==================
 

diff --git a/pyebsdindex/__init__.py b/pyebsdindex/__init__.py
@@ -7,7 +7,7 @@
 ]
 __description__ = "Python based tool for Hough/Radon based EBSD indexing"
 __name__ = "pyebsdindex"
-__version__ = "0.1.0"
+__version__ = "0.2.dev0"
 
 
 # Try to import only once

diff --git a/pyebsdindex/_ebsd_index_single.py b/pyebsdindex/_ebsd_index_single.py
@@ -175,43 +175,47 @@ def __init__(
         filename : str, optional
             Name of file with EBSD patterns.
         phaselist : list of str, optional
-            Options are "FCC" and "BCC". Default is ["FCC"].
+            Options are ``"FCC"`` and ``"BCC"``. Default is ``["FCC"]``.
         vendor : str, optional
             This string determines the pattern center (PC) convention to
-            use. The available options are "EDAX" (default), "BRUKER",
-            "OXFORD", "EMSOFT", "KIKUCHIPY" (equivalent to "BRUKER").
+            use. The available options are ``"EDAX"`` (default),
+            ``"BRUKER"``, ``"OXFORD"``, ``"EMSOFT"``, ``"KIKUCHIPY"``
+            (equivalent to ``"BRUKER"``).
         PC : list, optional
-            Pattern center (PC) x*, y*, z* in EDAX TSL's convention,
-            defined in fractions of pattern width with respect to the
-            lower left corner of the detector. If not passed, this is
-            set to (x*, y*, z*) = (0.471659, 0.675044, 0.630139).
+            (PCx, PCy, PCz) in the vendor convention. For EDAX TSL, this
+            is x*, y*, z*, defined in fractions of pattern width with
+            respect to the lower left corner of the detector. If not
+            passed, this is set to (x*, y*, z*) = (0.471659, 0.675044,
+            0.630139). If ``vendor="EMSOFT"``, the PC must be four
+            numbers, the final number being the pixel size.
         sampleTilt : float, optional
             Sample tilt towards the detector in degrees. Default is 70
-            degrees. Unused if `ebsd_indexer_obj` is passed.
+            degrees. Unused if ``ebsd_indexer_obj`` is passed.
         camElev : float, optional
             Camera elevation in degrees. Default is 5.3 degrees. Unused
-            if `ebsd_indexer_obj` is passed.
+            if ``ebsd_indexer_obj`` is passed.
         bandDetectPlan : pyebsdindex.band_detect.BandDetect, optional
             Collection of parameters using in band detection. Unused if
-            `ebsd_indexer_obj` is passed.
+            ``ebsd_indexer_obj`` is passed.
         nRho : int, optional
-            Default is 90 degrees. Unused if `ebsd_indexer_obj` is passed.
+            Default is 90 degrees. Unused if ``ebsd_indexer_obj`` is
+            passed.
         nTheta : int, optional
-            Default is 180 degrees. Unused if `ebsd_indexer_obj` is passed.
+            Default is 180 degrees. Unused if ``ebsd_indexer_obj`` is
+            passed.
         tSigma : float, optional
-            Unused if `ebsd_indexer_obj` is passed.
+            Unused if ``ebsd_indexer_obj`` is passed.
         rSigma : float, optional
-            Unused if `ebsd_indexer_obj` is passed.
+            Unused if ``ebsd_indexer_obj`` is passed.
         rhoMaskFrac : float, optional
-            Default is 0.1. Unused if `ebsd_indexer_obj` is passed.
+            Default is 0.1. Unused if ``ebsd_indexer_obj`` is passed.
         nBands : int, optional
             Number of detected bands to use in triplet voting. Default
-            is 9. Unused if `ebsd_indexer_obj` is passed.
+            is 9. Unused if ``ebsd_indexer_obj`` is passed.
         patDim : int, optional
             Number of dimensions of pattern array.
-        kwargs
-            Keyword arguments passed on to `BandDetect`.
-
+        **kwargs
+            Keyword arguments passed on to ``BandDetect``.
         """
         self.filein = filename
         if self.filein is not None:
@@ -318,9 +322,12 @@ def index_pats(
         clparams : list, optional
             OpenCL parameters passed to pyopencl.
         PC : list, optional
-            Pattern center (PC) (PCx, PCy, PCz) in `self.vendor`'s
-            convention (default is "EDAX"). If not given, this is read
-            from `self.PC`.
+            (PCx, PCy, PCz) in the vendor convention. For EDAX TSL, this
+            is (x*, y*, z*), defined in fractions of pattern width with
+            respect to the lower left corner of the detector. If not
+            given, this is read from ``self.PC``. If
+            ``vendor="EMSOFT"``, the PC must be four numbers, the final
+            number being the pixel size.
         verbose : int, optional
             0 - no output, 1 - timings, 2 - timings and the Hough
             transform of the first pattern with detected bands

diff --git a/pyebsdindex/pcopt.py b/pyebsdindex/pcopt.py
@@ -62,18 +62,22 @@ def optimize(pats, indexer, PC0=None, batch=False):
     Parameters
     ----------
     pats : numpy.ndarray
-        EBSD patterns.
+        EBSD pattern(s), of shape
+        ``(n detector rows, n detector columns)``,
+        or ``(n patterns, n detector rows, n detector columns)``.
     indexer : pyebsdindex.ebsd_index.EBSDIndexer
         EBSD indexer instance storing all relevant parameters for band
         detection.
     PC0 : list, optional
-        Initial guess of PC. If not given, `indexer.PC` is used.
+        Initial guess of PC. If not given, ``indexer.PC`` is used. If
+        ``indexer.vendor`` is ``"EMSOFT"``, the PC must be four numbers,
+        the final number being the pixel size.
     batch : bool, optional
-        Default is False which indicates the fit for a set of patterns
-        should be optimized using the cumulative fit for all the
-        patterns, and one PC will be returned.
-        If set to True, then a optimization is run for each individual
-        pattern, and an array of PC values will be returned.
+        Default is ``False`` which indicates the fit for a set of
+        patterns should be optimized using the cumulative fit for all
+        the patterns, and one PC will be returned. If ``True``, then an
+        optimization is run for each individual pattern, and an array of
+        PC values is returned.
 
     Returns
     -------
@@ -84,7 +88,6 @@ def optimize(pats, indexer, PC0=None, batch=False):
     -----
     SciPy's Nelder-Mead minimization function is used with a tolerance
     `fatol` of 0.00001 between each iteration.
-
     """
     banddat = indexer.bandDetectPlan.find_bands(pats)
     npoints = banddat.shape[0]
@@ -150,14 +153,22 @@ def optimize_pso(pats, indexer, PC0=None, batch=False):
     Parameters
     ----------
     pats : numpy.ndarray
-        EBSD patterns.
+        EBSD pattern(s), of shape
+        ``(n detector rows, n detector columns)``,
+        or ``(n patterns, n detector rows, n detector columns)``.
     indexer : pyebsdindex.ebsd_index.EBSDIndexer
         EBSD indexer instance storing all relevant parameters for band
         detection.
     PC0 : list, optional
-        Initial guess of PC. If not given, `indexer.PC` is used.
+        Initial guess of PC. If not given, ``indexer.PC`` is used. If
+        ``indexer.vendor`` is ``"EMSOFT"``, the PC must be four numbers,
+        the final number being the pixel size.
     batch : bool, optional
-        Default is False.
+        Default is ``False`` which indicates the fit for a set of
+        patterns should be optimized using the cumulative fit for all
+        the patterns, and one PC will be returned. If ``True``, then an
+        optimization is run for each individual pattern, and an array of
+        PC values is returned.
 
     Returns
     -------

diff --git a/setup.py b/setup.py
@@ -96,4 +96,5 @@
     # Files to include when distributing package (see also MANIFEST.in)
     packages=find_packages(),
     package_dir={"pyebsdindex": "pyebsdindex"},
+    include_package_data=True,
 )