gratinglab 0.3.0__tar.gz → 0.3.2__tar.gz

{gratinglab-0.3.0/src/gratinglab.egg-info → gratinglab-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.0
+Version: 0.3.2
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/__init__.py

@@ -22,7 +22,7 @@ from .measured import MeasuredEfficiency, MeasurementProvenance
 from .resolution import ResolvingPower, resolving_power
 from .result import EfficiencyScan, OrderEfficiency, Provenance
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/config.py

@@ -172,7 +172,6 @@ GGP_N_POINTS = 2000          # Points in the exported profile
 GGP_APPLY_SMOOTHING = True   # Light smoothing to remove interpolation kinks
 GGP_SMOOTHING_WINDOW = 5     # Larger = smoother
 GGP_MIN_HALF_WIDTH = 10      # Skip grooves whose symmetric half-extent is <= this
-GGP_WRITE_HEADER = False     # Start the .ggp with "3 0 - Polygonal type" / "Period: 1 PSC: 1"
                              # many samples (i.e. clipped by the scan edge)
 
 # ============ FILE SELECTION ============

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/core/processing.py

@@ -303,21 +303,42 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         n_groups = max(1, n_rows // 3)
         rows_per_group = n_rows // n_groups
     
+    # `n_rows` rarely divides by `n_groups`, and where the leftover lines go
+    # decides whether the bands survive reading the scan the other way up.
+    # Giving them all to the last band -- what this did until 0.3.2 -- moves
+    # every boundary by `leftover` when the rows are reversed, so one scan read
+    # by two routes is cut into two different sets of bands. Harmless while the
+    # image is untouched (0.002 deg of blaze angle), but `align_grooves` shears
+    # each row by an amount that depends on its distance from the centre, and
+    # on a sheared image the same reshuffle cost 0.067 deg between the raw
+    # .spm and the Gwyddion .txt export of one grating.
+    #
+    # So the leftover comes off the centre line and the two ends instead, which
+    # leaves the set of bands unchanged under a reversal. Exactly unchanged
+    # when `n_rows` is odd, since only then does the centre line map to itself;
+    # with an even line count and an odd leftover, one line is still unbanded
+    # from the near side, and that much asymmetry cannot be removed.
+    #
+    # With an even band count the dropped centre line falls on a boundary. With
+    # an odd one the middle band spans it, so that band's `group_ranges` entry
+    # is a line wider than the band -- the same way a masked gap already widens
+    # one -- and a caller slicing by that range reads the extra line.
+    banded = rows_per_group * n_groups
+    leftover = n_rows - banded
+    centre_line = leftover % 2
+    per_end = (leftover - centre_line) // 2
+    rows = np.arange(per_end, n_rows - per_end)
+    if centre_line:
+        rows = rows[rows != (n_rows - 1) // 2]
+
     profiles_nm = []
     group_ranges = []
-    
+
     for i in range(n_groups):
-        # Calculate row range for this group
-        start_row = i * rows_per_group
-        
-        # For the last group, include any remaining rows
-        if i == n_groups - 1:
-            end_row = n_rows
-        else:
-            end_row = (i + 1) * rows_per_group
-        
+        band = rows[i * rows_per_group:(i + 1) * rows_per_group]
+
         # Extract and average rows in this group
-        group_data = data[start_row:end_row, :]
+        group_data = data[band, :]
         profile_avg = nan_mean_rows(group_data)
         
         # Convert to nm and subtract minimum
@@ -325,7 +346,7 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         
         profiles_nm.append(profile_nm)
         # In the image's own line numbers, so a masked gap shows as a wider band
-        group_ranges.append((int(kept_rows[start_row]), int(kept_rows[end_row - 1]) + 1))
+        group_ranges.append((int(kept_rows[band[0]]), int(kept_rows[band[-1]]) + 1))
     
     # Package metadata
     group_info = {
@@ -334,11 +355,17 @@ def raw_data_multi_group(data, scan_x_size, n_groups=10):
         'rows_per_group': rows_per_group,
         'group_ranges': group_ranges,
         'rows_excluded': rows_excluded,
+        # Lines inside the image that no band could take, left out at the
+        # centre and the ends to keep the stack symmetric. Distinct from
+        # `rows_excluded`, which counts lines masked or dropped as scars.
+        'rows_unbanded': int(leftover),
     }
     
     print(f"  Extracted {n_groups} row-group profiles")
     print(f"    Rows per group: {rows_per_group}")
     print(f"    Total rows used: {n_groups * rows_per_group} of {n_rows}")
+    if leftover:
+        print(f"    Lines outside the bands (centre and ends): {leftover}")
     if rows_excluded:
         print(f"    Lines excluded (masked or dropped): {rows_excluded} of {all_rows}")
     

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/gui/qt/boundary_view.py

@@ -131,17 +131,6 @@ class BoundaryView(QWidget):
         self.min_half_spin.valueChanged.connect(self.refresh)
         layout.addWidget(self.min_half_spin)
 
-        # Only the written file changes, not the profile, so no refresh.
-        self.header_check = QCheckBox("Write the PCGrate header")
-        self.header_check.setChecked(self._defaults.ggp_write_header)
-        self.header_check.setToolTip(
-            "Start the .ggp with the two lines\n"
-            "    3 0 - Polygonal type\n"
-            "    Period: 1 PSC: 1\n"
-            "Off by default: PCGrate's border-profile import\n"
-            "takes the points alone.")
-        layout.addWidget(self.header_check)
-
         self.export_btn = QPushButton("Export…")
         self.export_btn.setEnabled(False)
         self.export_btn.setToolTip(
@@ -214,7 +203,6 @@ class BoundaryView(QWidget):
             ggp_apply_smoothing=self.smoothing_check.isChecked(),
             ggp_smoothing_window=self.smoothing_spin.value(),
             ggp_min_half_width=self.min_half_spin.value(),
-            ggp_write_header=self.header_check.isChecked(),
         )
 
     @property
@@ -456,8 +444,7 @@ class BoundaryView(QWidget):
             metrics_path = os.path.splitext(path)[0] + '_metrics.txt'
             write_profile_metrics(metrics_path, self._profile.metrics)
         else:
-            write_ggp(path, t=self._profile.x_norm, y=self._profile.y_norm,
-                      header=self.header_check.isChecked())
+            write_ggp(path, t=self._profile.x_norm, y=self._profile.y_norm)
             metrics_path = os.path.splitext(path)[0] + '_metrics.txt'
             write_profile_metrics(metrics_path, self._profile.metrics)
         return path, metrics_path

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/io/spm.py

@@ -8,9 +8,9 @@ header section says where its bytes are and how to turn them into nanometres.
 
 The reader was written here instead of taken from a library because the format
 is small, this project depends on nothing beyond numpy/scipy/matplotlib, and
-the conversion has one pitfall (described below) that is best handled here.
+the conversion has two pitfalls (described below) that are best handled here.
 
-The pitfall is as follows. The height scale comes from a line like::
+The first is the height scale, which comes from a line like::
 
     \\@2:Z scale: V [Sens. ZsensSens] (0.0000000001872337 V/LSB) 0.804163 V
 
@@ -25,6 +25,20 @@ The result shows no visible sign of the error: the image is the right shape,
 the grooves are in the right places, and every blaze angle is silently
 incorrect. The reader was verified against a known export: with the right
 parameter, the peak-to-peak height matches to 1.0000.
+
+The second is the direction of the slow axis. The rows are returned reversed
+against the order the plane stores them, because that is what Gwyddion does
+and this project's measurements all came through Gwyddion exports. Gwyddion
+reverses every Nanoscope import unconditionally -- ``modules/file/nanoscope.c``
+calls ``gwy_data_field_invert(dfield, TRUE, FALSE, FALSE)`` straight after
+scaling the plane, and that first argument is ``yflipped``, documented as "the
+image will be flipped upside down". It does not consult ``\\Frame direction``,
+which reads ``Down`` on the files here.
+
+This showed up as a sign: the same grating measured -0.3722 deg of groove
+rotation read as a .spm and +0.3721 deg read as the Gwyddion .txt export of
+that scan. A flip does not move the blaze angle, so it went unnoticed until
+``groove_orientation`` began correcting for the rotation it reported.
 """
 from __future__ import annotations
 
@@ -299,7 +313,12 @@ def read_spm(path, channel: str = DEFAULT_CHANNEL,
         heights_nm = plane.reshape(described.rows, described.cols).astype(float) \
             * volts_per_lsb * nm_per_volt
 
-        return heights_nm * 1e-9, described.scan_x_size_um
+        # Reversed: see the module docstring. Gwyddion's importer flips every
+        # Nanoscope plane upside down, so its text export of a scan is
+        # row-reversed against the plane as stored, and this reader exists to
+        # agree with those exports -- the same reason DEFAULT_DIRECTION is
+        # Retrace.
+        return heights_nm[::-1] * 1e-9, described.scan_x_size_um
 
     available = list_channels(path)
     raise ValueError(

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/settings.py

@@ -131,7 +131,6 @@ class AnalysisSettings:
     ggp_apply_smoothing: bool = True
     ggp_smoothing_window: int = 5
     ggp_min_half_width: int = 10
-    ggp_write_header: bool = False  # the legacy two-line header; see io/ggp.py
 
     # Row groups
     use_row_groups: bool = True
@@ -188,7 +187,6 @@ class AnalysisSettings:
             ggp_apply_smoothing=getattr(config, 'GGP_APPLY_SMOOTHING', True),
             ggp_smoothing_window=getattr(config, 'GGP_SMOOTHING_WINDOW', 5),
             ggp_min_half_width=getattr(config, 'GGP_MIN_HALF_WIDTH', 10),
-            ggp_write_header=getattr(config, 'GGP_WRITE_HEADER', False),
             use_row_groups=config.USE_ROW_GROUPS,
             n_row_groups=config.N_ROW_GROUPS,
             show_2d_image=config.SHOW_2D_IMAGE,

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/facet-fitting.md

@@ -61,11 +61,11 @@ On the master sample:
 
 | FACET_TRIM | Mean blaze angle |
 |---|---|
-| 0.05 | 32.94° |
-| 0.10 | 33.23° |
-| 0.15 | 32.84° |
-| 0.20 | 31.58° |
-| 0.25 | 29.99° |
+| 0.05 | 32.89° |
+| 0.10 | 33.13° |
+| 0.15 | 32.71° |
+| 0.20 | 31.49° |
+| 0.25 | 29.94° |
 
 This is a 3.2° change across a plausible range of a single parameter, larger
 than most of the between-sample differences that this software is used to

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/file-formats.md

@@ -2,7 +2,8 @@
 
 Three input formats are supported: the Bruker/Veeco Nanoscope `.spm` file,
 the Asylum Research `.ibw` file, and a text export from Gwyddion. On the same
-scan the `.spm` and text routes agree to within 0.002°. The `.ibw` route has
+scan the `.spm` and text routes agree to within 0.005°, and to 0.000009°
+with groove-orientation correction off. The `.ibw` route has
 not yet been checked against a file from an instrument; see its section.
 
 ## Text exports
@@ -68,11 +69,34 @@ signal and does not represent topography; passing it through a blaze-angle
 pipeline produces a plausible-looking number with no physical meaning.
 
 Retrace is the default because it is the plane from which this project's
-existing Gwyddion exports were taken: it correlates 0.98 with the export, while
-Trace correlates 0.90. With this default the two input routes agree by
+existing Gwyddion exports were taken: it correlates 1.000000 with the export,
+while Trace correlates 0.92. With this default the two input routes agree by
 construction. Both directions image the same grooves and either is a legitimate
 choice, and the GUI offers a selector when a `.spm` is loaded.
 
+### Which way up
+
+The rows are returned reversed against the order the plane stores them.
+
+Gwyddion reverses the rows of every Nanoscope import, unconditionally:
+`modules/file/nanoscope.c` calls `gwy_data_field_invert(dfield, TRUE, FALSE,
+FALSE)` immediately after scaling the plane, and the first argument of that
+function is `yflipped`, documented as "the image will be flipped upside down".
+It does not consult `\Frame direction`, which reads `Down` on the files here.
+So a Gwyddion export is upside down against the plane as stored, and since
+every measurement this project has made came through such an export, the
+reader follows Gwyddion rather than the file.
+
+Reading the plane as stored, which is what this did until 0.3.2, left the two
+routes mirror images of each other. A flip does not move the blaze angle, so
+nothing showed until `groove_orientation` began measuring the groove rotation:
+the same grating then read -0.3722° as a `.spm` and +0.3721° as the Gwyddion
+export of that scan. Both routes now report +0.372°.
+
+With the rows the right way up, the plane and the export agree to 0.00027 nm
+rms on a scan 115 nm deep, which is the five significant digits the text export
+writes and nothing else.
+
 ### The height scale, and how to misread it
 
 Raw samples are integers. They are converted to nanometres using a line such
@@ -137,24 +161,36 @@ reader's was.
 
 ## The two routes compared
 
-The same scan was processed by both routes:
+The same scan was processed by both routes, at the current defaults:
 
 | Route | N | Mean blaze angle | σ | Period |
 |---|---|---|---|---|
-| Gwyddion `.txt` | 100 | 27.913° | 2.127° | 314.33 nm |
-| Raw `.spm` | 100 | 27.911° | 2.126° | 314.33 nm |
-
-The means differ by 0.002°, against a standard deviation of 2.13°.
-
-The results are not bit-identical, and they are not expected to be: the export
-was flattened by Gwyddion while the `.spm` is raw, and the two differ by 7 nm
-RMS. This software, however, flattens every row-group profile itself before
-fitting, which removes the same background. The Gwyddion flattening step is
-therefore redundant for this pipeline.
+| Gwyddion `.txt` | 100 | 27.888° | 2.053° | 313.89 nm |
+| Raw `.spm` | 100 | 27.883° | 2.049° | 313.89 nm |
+
+The means differ by 0.005°, against a standard deviation of 2.05°. With
+`groove_orientation` off both routes read 27.915°, σ 2.165°, 314.33 nm — the
+same to every digit printed, and 0.000009° apart in full. The 0.005° with the
+correction on is not a disagreement about the heights: it is the slow-axis
+size, which the `.spm` header gives as 1.56640625 µm while Gwyddion's
+`# Height:` line rounds it to 1.566, so the two shear in slightly different
+pixels.
+
+The underlying arrays agree to 0.00027 nm RMS on a scan 115 nm deep, which is
+the five significant digits the text export writes and nothing else: no per-row
+offset (0.00001 nm), no plane, and no scale difference. The export is the plane.
+
+That is not what this page said until 0.3.2. It reported a 7 nm RMS difference
+and explained it as Gwyddion's flattening, which the pipeline's own row-group
+flattening then removed. Both the figure and the explanation were artefacts of
+reading the plane upside down (see "Which way up"): comparing a grating with
+its own mirror image is what produced the 7 nm. Together with the finding
+below, the `_flatten` in that filename appears to describe nothing that was
+ever done to the data.
 
 A further finding was made during this verification: the `_flatten.0_00003`
 companion file beside the raw scan is byte-identical to it. Gwyddion never wrote
-modified data, and the flattening existed only in the text export.
+modified data, and on the evidence above the text export carries none either.
 
 ## Practical notes
 

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/reading-outputs.md

@@ -108,9 +108,9 @@ which is what PCGrate's border-profile import takes:
 0.000500 0.000001
 ```
 
-Tick "Write the PCGrate header" on the Boundary tab, or set
-`GGP_WRITE_HEADER = True`, to start it with the legacy
-`3 0 - Polygonal type` / `Period: 1 PSC: 1` lines instead.
+Files written before 0.3.0 may start with the legacy
+`3 0 - Polygonal type` / `Period: 1 PSC: 1` lines; they still load. A script
+that needs those lines can call `write_ggp(..., header=True)`.
 
 Both columns are normalised: x runs from 0 to 1 across exactly one period, and
 y is the height as a fraction of that period. A groove 0.33 deep in this file is

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/wiki/row-groups.md

@@ -22,6 +22,25 @@ straightforwardly add information.
 Each band is flattened independently, because the background tilt is not
 necessarily uniform across the image.
 
+## Where the leftover lines go
+
+A line count rarely divides by the number of bands. The lines left over are
+left out, from the centre line and from the two ends, so that the bands sit
+symmetrically about the middle of the image. The count is reported as
+`rows_unbanded`, separately from the lines dropped as scars or masked away.
+
+The placement matters because the same scan can arrive either way up: a
+Nanoscope `.spm` and the Gwyddion text export of that scan disagree about
+which end of the slow axis is stored first. Until 0.3.2 the leftover lines
+were given to the last band, which made every boundary move when the rows were
+reversed. On an image that `groove_orientation` has sheared, each line is
+shifted by an amount that depends on its distance from the centre, so the
+reshuffle changed what each band averaged: on one 401-line scan it moved the
+mean blaze angle by 0.067°, where the two readings of that scan now agree to
+0.005° with the correction on and 0.000009° with it off. Centred bands are the
+same set of bands read either way, so the measurement no longer depends on the
+direction of the slow axis.
+
 ## Why grooves at a scan edge are rejected
 
 `EDGE_EXCLUSION_PERIODS` (0.6 by default) discards any groove detected within

{gratinglab-0.3.0 → gratinglab-0.3.2}/src/gratinglab/metrology/workflows.py

@@ -205,8 +205,7 @@ def run_boundary_profile_export(settings=None, filename=None):
     stem = os.path.splitext(os.path.basename(filename))[0]
     ggp_path = os.path.join(RESULTS_DIR, f'averaged_groove_profile_{stem}.ggp')
     met_path = os.path.join(RESULTS_DIR, f'groove_analysis_metrics_{stem}.txt')
-    write_ggp(ggp_path, t=profile.x_norm, y=profile.y_norm,
-              header=settings.ggp_write_header)
+    write_ggp(ggp_path, t=profile.x_norm, y=profile.y_norm)
     write_profile_metrics(met_path, profile.metrics)
 
     print(f"\n  Groove depth: {profile.metrics['groove_depth']:.4f} of period")

{gratinglab-0.3.0 → gratinglab-0.3.2/src/gratinglab.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.0
+Version: 0.3.2
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause