pingmapper 5.5.1__tar.gz → 5.5.3__tar.gz

{pingmapper-5.5.1 → pingmapper-5.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.5.1
+Version: 5.5.3
 Summary: Open-source interface for processing recreation-grade side scan sonar datasets and reproducibly mapping benthic habitat
 Author: Cameron Bodine, Daniel Buscombe, Iury T Simoes-Sousa
 Author-email: bodine.cs@gmail.email

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/class_rectObj.py

@@ -2724,6 +2724,8 @@ class rectObj(sonObj):
             img = self.sonDat.copy()
             if son:
                 img = self._reserve_zero_for_nodata(img, preserve_zeros=True)
+                if bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)):
+                    img = self._apply_display_enhancements(img)
             apply_post_rect_colormap = use_16bit and self._rect_colormap_selected(son=son)
             source_scale_bounds = None
             if apply_post_rect_colormap:
@@ -2747,6 +2749,8 @@ class rectObj(sonObj):
             out = np.flip(np.flip(np.flip(out,1),0),1)
             if use_16bit:
                 out = out.astype(np.float32)
+            elif bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)):
+                out = out.astype(np.float32)
             else:
                 out = out.astype('uint8')
 
@@ -2780,7 +2784,10 @@ class rectObj(sonObj):
                     out16 = out16_raw
                 self._write_rect_geotiff(gtiff, out16, epsg, transform, colormap=None)
             else:
-                out8 = np.clip(out, 0, 255).astype(np.uint8)
+                if bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)):
+                    out8 = self._convert_son_dat_to_uint8(out)
+                else:
+                    out8 = np.clip(out, 0, 255).astype(np.uint8)
                 self._write_rect_geotiff(gtiff, out8, epsg, transform, colormap=self.son_colorMap)
 
             del out, img
@@ -2815,6 +2822,8 @@ class rectObj(sonObj):
             img = self.sonDat
             if son:
                 img = self._reserve_zero_for_nodata(img, preserve_zeros=True)
+                if bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)):
+                    img = self._apply_display_enhancements(img)
             apply_post_rect_colormap = son and use_16bit and self._rect_colormap_selected(son=son)
             source_scale_bounds = None
             if apply_post_rect_colormap:
@@ -2887,6 +2896,8 @@ class rectObj(sonObj):
             out = np.flip(np.flip(np.flip(out,1),0),1)
             if son and use_16bit:
                 out = out.astype(np.float32)
+            elif son and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False))):
+                out = out.astype(np.float32)
             else:
                 out = out.astype('uint8')
 
@@ -2926,7 +2937,10 @@ class rectObj(sonObj):
                 self._write_rect_geotiff(gtiff, out16, epsg, transform, colormap=None)
             else:
                 colormap = self.son_colorMap if son else class_colormap
-                out8 = np.clip(out, 0, 255).astype(np.uint8)
+                if son and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False))):
+                    out8 = self._convert_son_dat_to_uint8(out)
+                else:
+                    out8 = np.clip(out, 0, 255).astype(np.uint8)
                 self._write_rect_geotiff(gtiff, out8, epsg, transform, colormap=colormap)
 
             del out

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/class_sonObj.py

@@ -30,6 +30,7 @@
 # SOFTWARE.
 
 import os, sys
+from skimage import exposure
 
 # Add 'pingmapper' to the path, may not need after pypi package...
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -708,10 +709,34 @@ class sonObj(object):
         else:
             time_table = pd.read_csv(time_table)
 
+        if 'start_seconds' not in time_table.columns or 'end_seconds' not in time_table.columns:
+            raise ValueError("time_table must contain 'start_seconds' and 'end_seconds' columns.")
+
+        # Normalize to numeric and drop unusable rows.
+        time_table['start_seconds'] = pd.to_numeric(time_table['start_seconds'], errors='coerce')
+        time_table['end_seconds'] = pd.to_numeric(time_table['end_seconds'], errors='coerce')
+        time_table = time_table.dropna(subset=['start_seconds', 'end_seconds'])
+
+        if time_table.empty:
+            return sonDF
+
+        son_time = pd.to_numeric(sonDF[time_col], errors='coerce')
+        son_min = son_time.min()
+
+        # Auto-detect relative clip ranges when sonar time is epoch-like and
+        # clip-table values are small. This allows 0..N seconds-from-start.
+        tt_max = np.nanmax(np.abs(time_table[['start_seconds', 'end_seconds']].to_numpy(dtype=float)))
+        use_relative_seconds = np.isfinite(son_min) and son_min > 1e8 and np.isfinite(tt_max) and tt_max < 1e7
+
+        offset = float(son_min) if use_relative_seconds else 0.0
+
         for i, row in time_table.iterrows():
 
-            start = row['start_seconds']
-            end = row['end_seconds']
+            start = float(row['start_seconds']) + offset
+            end = float(row['end_seconds']) + offset
+
+            if end < start:
+                start, end = end, start
 
             # dfFilt = sonDF[(sonDF['time_s'] >= start) & (sonDF['time_s'] <= end)]
             sonDF.loc[(sonDF[time_col] >= start) & (sonDF[time_col] <= end) & (sonDF[filtCol] == True), filtTimeCol] = True
@@ -1238,6 +1263,19 @@ class sonObj(object):
                         if np.isfinite(wf) and wf > 0:
                             dat = dat * (2.0 ** (-float(wf)))
 
+                if bool(getattr(self, '_use_cerulean_power_scale', False)):
+                    dat = dat.astype(np.float32, copy=False)
+                    if hasattr(self, 'minPwrDb') and hasattr(self, 'maxPwrDb') and i < len(self.minPwrDb) and i < len(self.maxPwrDb):
+                        min_db = self.minPwrDb[i]
+                        max_db = self.maxPwrDb[i]
+                        if np.isfinite(min_db) and np.isfinite(max_db) and (max_db > min_db):
+                            # Issue #206: Cerulean pwr_results[] are normalized
+                            # uint16 values that must be rescaled with min/max dB.
+                            dat_db = float(min_db) + (dat / 65535.0) * (float(max_db) - float(min_db))
+                            # Keep values non-negative for downstream intensity
+                            # processing while preserving the per-ping dB span.
+                            dat = dat_db - float(min_db)
+
                 n_samples = min(len(dat), sonDat.shape[0])
                 if n_samples <= 0:
                     skipped_reads += 1
@@ -1268,6 +1306,168 @@ class sonObj(object):
         self.sonDat = self._convert_son_dat_to_uint8(sonDat)
         return
 
+    def _apply_display_enhancements(self, sonDat):
+        """Optional display-stage intensity transforms before uint8 mapping.
+
+        These transforms are intended to improve perceptual contrast of exported
+        sonograms while keeping the processing pipeline opt-in and backward-
+        compatible by default.
+        """
+        use_db = bool(getattr(self, 'sonar_db_transform', False))
+        use_clahe = bool(getattr(self, 'sonar_clahe', False))
+
+        if not use_db and not use_clahe:
+            return sonDat
+
+        arr = self._apply_display_db_transform(sonDat)
+        if arr.size == 0:
+            return arr
+
+        valid = arr > 0
+        if not np.any(valid):
+            return arr
+
+        if use_clahe:
+            clip_limit = float(getattr(self, 'sonar_clahe_clip_limit', 0.01))
+            if (not np.isfinite(clip_limit)) or clip_limit <= 0:
+                clip_limit = 0.01
+
+            global_bounds = None
+            if bool(getattr(self, 'sonar_clahe_global', True)):
+                global_bounds = self._ensure_clahe_global_bounds()
+
+            if global_bounds is not None:
+                arr01 = self._normalize_with_bounds(arr, global_bounds[0], global_bounds[1])
+            else:
+                max_val = float(np.nanmax(arr))
+                if not (np.isfinite(max_val) and max_val > 0):
+                    return arr
+                arr01 = np.clip(arr / max_val, 0.0, 1.0)
+
+            try:
+                arr01 = exposure.equalize_adapthist(arr01, clip_limit=clip_limit)
+                arr = np.asarray(arr01, dtype=np.float32) * 255.0
+            except MemoryError:
+                arr = self._apply_clahe_chunked(arr01, clip_limit)
+            except np.core._exceptions._ArrayMemoryError:
+                arr = self._apply_clahe_chunked(arr01, clip_limit)
+
+        # Preserve no-data convention for empty samples.
+        arr[~valid] = 0.0
+        return arr
+
+    def _apply_display_db_transform(self, sonDat):
+        arr = np.asarray(sonDat, dtype=np.float32)
+        if arr.size == 0:
+            return arr
+
+        arr[~np.isfinite(arr)] = 0.0
+        arr[arr < 0] = 0.0
+
+        valid = arr > 0
+        if not np.any(valid):
+            return arr
+
+        if bool(getattr(self, 'sonar_db_transform', False)):
+            # Use the smallest positive intensity as the log floor to avoid
+            # collapsing zeros to -inf and to preserve relative low amplitudes.
+            floor = float(np.nanmin(arr[valid]))
+            if (not np.isfinite(floor)) or floor <= 0:
+                floor = 1.0
+            arr = np.maximum(arr, floor)
+            arr = 20.0 * np.log10(arr)
+            arr = arr - np.nanmin(arr)
+
+        arr[~valid] = 0.0
+        return arr
+
+    def _ensure_clahe_global_bounds(self):
+        if not bool(getattr(self, 'sonar_clahe_global', True)):
+            return None
+
+        cache = getattr(self, '_sonar_clahe_global_bounds', None)
+        if isinstance(cache, tuple) and len(cache) == 2:
+            lo, hi = cache
+            if np.isfinite(lo) and np.isfinite(hi) and hi > lo:
+                return cache
+
+        if not hasattr(self, 'sonMetaDF'):
+            self._loadSonMeta()
+
+        if not hasattr(self, 'sonMetaDF') or self.sonMetaDF is None or len(self.sonMetaDF) == 0:
+            return None
+
+        saved_sonDat = getattr(self, 'sonDat', None)
+        saved_sonDat16 = getattr(self, 'sonDat16', None)
+        saved_pingMax = getattr(self, 'pingMax', None)
+
+        chunk_ids = pd.unique(self.sonMetaDF['chunk_id'])
+        sample_cap = int(getattr(self, 'sonar_clahe_global_sample_cap', 200000))
+        if sample_cap <= 0:
+            sample_cap = 200000
+
+        sampled_vals = []
+        for chunk in chunk_ids:
+            self._getScanChunkSingle(int(chunk))
+            arr = self._apply_display_db_transform(self.sonDat)
+            valid = arr > 0
+            if not np.any(valid):
+                continue
+
+            vals = arr[valid].astype(np.float32, copy=False)
+            if vals.size > sample_cap:
+                idx = np.linspace(0, vals.size - 1, sample_cap, dtype=np.int64)
+                vals = vals[idx]
+            sampled_vals.append(vals)
+
+        if len(sampled_vals) == 0:
+            self.sonDat = saved_sonDat
+            self.sonDat16 = saved_sonDat16
+            self.pingMax = saved_pingMax
+            return None
+
+        pooled = np.concatenate(sampled_vals)
+        lo = float(np.nanpercentile(pooled, 1.0))
+        hi = float(np.nanpercentile(pooled, 99.5))
+        if (not np.isfinite(lo)) or (not np.isfinite(hi)) or hi <= lo:
+            lo = float(np.nanmin(pooled))
+            hi = float(np.nanmax(pooled))
+
+        if (not np.isfinite(lo)) or (not np.isfinite(hi)) or hi <= lo:
+            self.sonDat = saved_sonDat
+            self.sonDat16 = saved_sonDat16
+            self.pingMax = saved_pingMax
+            return None
+
+        self._sonar_clahe_global_bounds = (lo, hi)
+        self.sonDat = saved_sonDat
+        self.sonDat16 = saved_sonDat16
+        self.pingMax = saved_pingMax
+        return self._sonar_clahe_global_bounds
+
+    def _apply_clahe_chunked(self, arr01, clip_limit):
+        """Apply CLAHE in row-wise stripes to reduce peak memory usage."""
+        src = np.asarray(arr01, dtype=np.float32)
+        h, w = src.shape
+        if h == 0 or w == 0:
+            return src
+
+        # Keep per-stripe working set bounded. equalize_adapthist promotes to
+        # float64 internally, so we target moderate stripe sizes.
+        stripe_rows = int(getattr(self, 'sonar_clahe_rows_per_chunk', 512))
+        if stripe_rows <= 0:
+            stripe_rows = 512
+        stripe_rows = min(stripe_rows, h)
+
+        out = np.empty_like(src, dtype=np.float32)
+        for start in range(0, h, stripe_rows):
+            end = min(start + stripe_rows, h)
+            stripe = src[start:end, :]
+            stripe_eq = exposure.equalize_adapthist(stripe, clip_limit=clip_limit)
+            out[start:end, :] = np.asarray(stripe_eq, dtype=np.float32) * 255.0
+
+        return out
+
     def _apply_tvg(self, sonDat):
         sonDat = np.asarray(sonDat, dtype=np.float32)
 
@@ -1979,7 +2179,8 @@ class sonObj(object):
                     k,
                     imgOutPrefix,
                     tileFile='.jpg',
-                    colormap=False):
+                    colormap=False,
+                    apply_display_enhancement=True):
         '''
         Using currently saved ping ping returns stored in self.sonDAT,
         saves an unrectified image of the sonar echogram.
@@ -2016,7 +2217,15 @@ class sonObj(object):
             data = self._prepare_export_uint16(self.sonDat)
             data = self._reserve_zero_for_nodata(data)
         else:
-            data = self.sonDat.astype('uint8') # Get the sonar data
+            arr = self.sonDat
+            if apply_display_enhancement and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False))):
+                arr = self._apply_display_enhancements(arr)
+
+            if np.issubdtype(np.asarray(arr).dtype, np.floating):
+                data = self._convert_son_dat_to_uint8(arr)
+            else:
+                data = np.clip(arr, 0, 255).astype(np.uint8)
+
             data = self._reserve_zero_for_nodata(data)
 
         # File name zero padding
@@ -2039,7 +2248,8 @@ class sonObj(object):
                     k,
                     imgOutPrefix,
                     tileFile='.jpg',
-                    colormap=False):
+                    colormap=False,
+                    apply_display_enhancement=True):
         '''
         Using currently saved ping ping returns stored in self.sonDAT,
         saves an unrectified image of the sonar echogram.
@@ -2077,7 +2287,15 @@ class sonObj(object):
             data = self._prepare_export_uint16(self.sonDat)
             data = self._reserve_zero_for_nodata(data)
         else:
-            data = self.sonDat.astype('uint8') # Get the sonar data
+            arr = self.sonDat
+            if apply_display_enhancement and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False))):
+                arr = self._apply_display_enhancements(arr)
+
+            if np.issubdtype(np.asarray(arr).dtype, np.floating):
+                data = self._convert_son_dat_to_uint8(arr)
+            else:
+                data = np.clip(arr, 0, 255).astype(np.uint8)
+
             data = self._reserve_zero_for_nodata(data)
 
         # File name zero padding
@@ -2147,40 +2365,44 @@ class sonObj(object):
         if self.wcp:
             # Do speed correction
             export_16bit = bool(getattr(self, 'export_16bit', False)) and not bool(getattr(self, 'son8bit', False))
-            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit)
+            pre_spd_enhance = (not export_16bit) and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)))
+            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit, pre_spd_enhance=pre_spd_enhance)
 
             if self.sonDat is not np.nan:
-                self._writeTilesPlot(chunk, imgOutPrefix='wcp', tileFile=tileFile, colormap=True)
+                self._writeTilesPlot(chunk, imgOutPrefix='wcp', tileFile=tileFile, colormap=True, apply_display_enhancement=not pre_spd_enhance)
             else:
                 pass
 
         if self.wcm:
             # Do speed correction
             export_16bit = bool(getattr(self, 'export_16bit', False)) and not bool(getattr(self, 'son8bit', False))
-            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, mask_wc=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit)
+            pre_spd_enhance = (not export_16bit) and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)))
+            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, mask_wc=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit, pre_spd_enhance=pre_spd_enhance)
 
             if self.sonDat is not np.nan:
-                self._writeTilesPlot(chunk, imgOutPrefix='wcm', tileFile=tileFile, colormap=True)
+                self._writeTilesPlot(chunk, imgOutPrefix='wcm', tileFile=tileFile, colormap=True, apply_display_enhancement=not pre_spd_enhance)
             else:
                 pass
 
         if self.wcr_src:
             # Do speed correction
             export_16bit = bool(getattr(self, 'export_16bit', False)) and not bool(getattr(self, 'son8bit', False))
-            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, src=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit)
+            pre_spd_enhance = (not export_16bit) and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)))
+            self._doSpdCor(chunk, spdCor=spdCor, mask_shdw=mask_shdw, src=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit, pre_spd_enhance=pre_spd_enhance)
 
             if self.sonDat is not np.nan:
-                self._writeTilesPlot(chunk, imgOutPrefix='src', tileFile=tileFile, colormap=True)
+                self._writeTilesPlot(chunk, imgOutPrefix='src', tileFile=tileFile, colormap=True, apply_display_enhancement=not pre_spd_enhance)
             else:
                 pass
 
         if self.wco:
             # Do speed correction
             export_16bit = bool(getattr(self, 'export_16bit', False)) and not bool(getattr(self, 'son8bit', False))
-            self._doSpdCor(chunk, spdCor=spdCor, mask_bed=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit)
+            pre_spd_enhance = (not export_16bit) and (bool(getattr(self, 'sonar_db_transform', False)) or bool(getattr(self, 'sonar_clahe', False)))
+            self._doSpdCor(chunk, spdCor=spdCor, mask_bed=True, maxCrop=maxCrop, do_egn=self.egn, stretch_wcp=True, integer=not export_16bit, pre_spd_enhance=pre_spd_enhance)
 
             if self.sonDat is not np.nan:
-                self._writeTilesPlot(chunk, imgOutPrefix='wco', tileFile=tileFile, colormap=True)
+                self._writeTilesPlot(chunk, imgOutPrefix='wco', tileFile=tileFile, colormap=True, apply_display_enhancement=not pre_spd_enhance)
             else:
                 pass
 
@@ -2200,7 +2422,8 @@ class sonObj(object):
                   son=True, 
                   integer=True, 
                   do_egn=False, 
-                  stretch_wcp=False):
+                  stretch_wcp=False,
+                  pre_spd_enhance=False):
 
         if not hasattr(self, 'sonMetaDF'):
             self._loadSonMeta()
@@ -2248,6 +2471,10 @@ class sonObj(object):
 
             sonDat = self.sonDat
 
+            if pre_spd_enhance and not export_16bit:
+                sonDat = self._apply_display_enhancements(sonDat)
+                self.sonDat = sonDat
+
             if spdCor == 0:
                 # Don't do speed correction
                 pass
@@ -2310,7 +2537,12 @@ class sonObj(object):
                                 clip=False, preserve_range=True)#.astype('uint8')
 
             if integer:
-                self.sonDat = sonDat.astype('uint8')
+                if pre_spd_enhance and np.issubdtype(np.asarray(sonDat).dtype, np.floating):
+                    # CLAHE outputs 0..1 floats; convert with robust scaling so
+                    # display-enhanced data does not collapse to near-black.
+                    self.sonDat = self._convert_son_dat_to_uint8(sonDat)
+                else:
+                    self.sonDat = sonDat.astype('uint8')
             else:
                 self.sonDat = sonDat
 
@@ -2413,6 +2645,12 @@ class sonObj(object):
             self._use_jsf_weighting = True
             self._ensure_jsf_global_scale_max(sonMetaAll)
 
+        self._use_cerulean_power_scale = False
+        if 'min_pwr_db' in sonMeta.columns and 'max_pwr_db' in sonMeta.columns:
+            self.minPwrDb = pd.to_numeric(sonMeta['min_pwr_db'], errors='coerce').to_numpy(dtype=float)
+            self.maxPwrDb = pd.to_numeric(sonMeta['max_pwr_db'], errors='coerce').to_numpy(dtype=float)
+            self._use_cerulean_power_scale = True
+
         # Load chunk's sonar data into memory
         self._loadSonChunk()
         # Do PPDRC filter
@@ -2427,7 +2665,12 @@ class sonObj(object):
             del self.bytesPerSample
         if hasattr(self, 'weightingFactor'):
             del self.weightingFactor
+        if hasattr(self, 'minPwrDb'):
+            del self.minPwrDb
+        if hasattr(self, 'maxPwrDb'):
+            del self.maxPwrDb
         self._use_jsf_weighting = False
+        self._use_cerulean_power_scale = False
 
         return
     
@@ -2477,6 +2720,12 @@ class sonObj(object):
             self._use_jsf_weighting = True
             self._ensure_jsf_global_scale_max(sonMetaAll_full)
 
+        self._use_cerulean_power_scale = False
+        if 'min_pwr_db' in sonMeta.columns and 'max_pwr_db' in sonMeta.columns:
+            self.minPwrDb = pd.to_numeric(sonMeta['min_pwr_db'], errors='coerce').to_numpy(dtype=float)
+            self.maxPwrDb = pd.to_numeric(sonMeta['max_pwr_db'], errors='coerce').to_numpy(dtype=float)
+            self._use_cerulean_power_scale = True
+
         # Load chunk's sonar data into memory
         self._loadSonChunk()
 
@@ -2489,7 +2738,12 @@ class sonObj(object):
             del self.bytesPerSample
         if hasattr(self, 'weightingFactor'):
             del self.weightingFactor
+        if hasattr(self, 'minPwrDb'):
+            del self.minPwrDb
+        if hasattr(self, 'maxPwrDb'):
+            del self.maxPwrDb
         self._use_jsf_weighting = False
+        self._use_cerulean_power_scale = False
 
         return
 

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/class_sonObj_nadirgaptest.py

@@ -686,10 +686,34 @@ class sonObj(object):
         else:
             time_table = pd.read_csv(time_table)
 
+        if 'start_seconds' not in time_table.columns or 'end_seconds' not in time_table.columns:
+            raise ValueError("time_table must contain 'start_seconds' and 'end_seconds' columns.")
+
+        # Normalize to numeric and drop unusable rows.
+        time_table['start_seconds'] = pd.to_numeric(time_table['start_seconds'], errors='coerce')
+        time_table['end_seconds'] = pd.to_numeric(time_table['end_seconds'], errors='coerce')
+        time_table = time_table.dropna(subset=['start_seconds', 'end_seconds'])
+
+        if time_table.empty:
+            return sonDF
+
+        son_time = pd.to_numeric(sonDF[time_col], errors='coerce')
+        son_min = son_time.min()
+
+        # Auto-detect relative clip ranges when sonar time is epoch-like and
+        # clip-table values are small. This allows 0..N seconds-from-start.
+        tt_max = np.nanmax(np.abs(time_table[['start_seconds', 'end_seconds']].to_numpy(dtype=float)))
+        use_relative_seconds = np.isfinite(son_min) and son_min > 1e8 and np.isfinite(tt_max) and tt_max < 1e7
+
+        offset = float(son_min) if use_relative_seconds else 0.0
+
         for i, row in time_table.iterrows():
 
-            start = row['start_seconds']
-            end = row['end_seconds']
+            start = float(row['start_seconds']) + offset
+            end = float(row['end_seconds']) + offset
+
+            if end < start:
+                start, end = end, start
 
             # dfFilt = sonDF[(sonDF['time_s'] >= start) & (sonDF['time_s'] <= end)]
             sonDF.loc[(sonDF[time_col] >= start) & (sonDF[time_col] <= end) & (sonDF[filtCol] == True), filtTimeCol] = True

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/default_params.json

@@ -25,6 +25,10 @@
     "egn_stretch_factor":0.5,
     "tone_gamma":1.0,
     "tone_gain":1.0,
+    "sonar_db_transform":false,
+    "sonar_clahe":false,
+    "sonar_clahe_global":true,
+    "sonar_clahe_clip_limit":0.01,
     "wcp":false,
     "wcm":true,
     "wcr":false,

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/gui_main.py

@@ -207,7 +207,7 @@ def gui(batch: bool):
     tip_speed_min = ml_tip('Minimum vessel speed filter in m/s. 0=no minimum speed filter.')
     tip_speed_max = ml_tip('Maximum vessel speed filter in m/s. 0=no maximum speed filter.')
     tip_aoi = ml_tip('Optional polygon shapefile (.shp) to spatially filter sonar records to area of interest.')
-    tip_time_filter = ml_tip('Option to filter sonar records by time range using start/end seconds.')
+    tip_time_filter = ml_tip('Filter by start/end time ranges. Use either relative seconds from recording start (e.g., 0-2000) or absolute Unix seconds.')
     # Cropping
     text_crop = sg.Text('Crop Range [m]', size=(22,1))
     in_crop = sg.Input(key='cropRange', default_text=default_params['cropRange'], size=(10,1), tooltip=tip_crop)
@@ -280,6 +280,9 @@ def gui(batch: bool):
     tip_egn_factor = ml_tip('Percent clip amount used by EGN Stretch Factor when Percent Clip is selected.')
     tip_gamma = ml_tip('Tone curve control. <1 brightens mid-tones, >1 darkens mid-tones.')
     tip_gain = ml_tip('Linear brightness multiplier. >1 brightens overall intensity, <1 darkens.')
+    tip_db = ml_tip('Apply 20*log10 transform before final 8-bit mapping. Helps reveal low-amplitude detail.')
+    tip_clahe = ml_tip('Apply adaptive histogram equalization (CLAHE) after dB transform for local contrast boost.')
+    tip_clahe_clip = ml_tip('CLAHE clip limit. Lower values are gentler; higher values increase local contrast.')
     # EGN
     check_egn = sg.Checkbox('Empiracal Gain Normalization (EGN)', key='egn', default=default_params['egn'], tooltip=tip_egn)
 
@@ -306,8 +309,43 @@ def gui(batch: bool):
         default_value=float(default_params['tone_gain']),
         tooltip=tip_gain,
     )
+    check_sonar_db = sg.Checkbox(
+        'Display dB Transform',
+        key='sonar_db_transform',
+        default=default_params.get('sonar_db_transform', False),
+        tooltip=tip_db,
+    )
+    check_sonar_clahe = sg.Checkbox(
+        'Display CLAHE',
+        key='sonar_clahe',
+        default=default_params.get('sonar_clahe', False),
+        tooltip=tip_clahe,
+    )
+    check_sonar_clahe_global = sg.Checkbox(
+        'Global CLAHE reference',
+        key='sonar_clahe_global',
+        default=default_params.get('sonar_clahe_global', True),
+        tooltip='Use one project-wide intensity reference before CLAHE so chunk brightness stays consistent. This adds a prepass, but reduces chunk-to-chunk contrast shifts.',
+    )
+    text_clahe_clip = sg.Text('CLAHE Clip Limit', size=(20,1))
+    in_clahe_clip = sg.Input(
+        key='sonar_clahe_clip_limit',
+        default_text=default_params.get('sonar_clahe_clip_limit', 0.01),
+        size=(10,1),
+        tooltip=tip_clahe_clip,
+    )
 
-    col_egn_1 = sg.Column([[text_egn_gamma, slide_egn_gamma], [text_egn_gain, slide_egn_gain]], pad=0)
+    col_egn_1 = sg.Column(
+        [
+            [text_egn_gamma, slide_egn_gamma],
+            [text_egn_gain, slide_egn_gain],
+            [check_sonar_db],
+            [check_sonar_clahe],
+            [check_sonar_clahe_global],
+            [text_clahe_clip, in_clahe_clip],
+        ],
+        pad=0,
+    )
     col_egn_2 = sg.Column([[check_egn], [text_egn_stretch, combo_egn_stretch], [text_egn_factor, in_egn_factor]], pad=0)
     # Add to layout
     layout.append([sg.HorizontalSeparator()])
@@ -804,6 +842,10 @@ def gui(batch: bool):
             'egn_stretch_factor':float(values['egn_stretch_factor']),
             'tone_gamma':float(values['tone_gamma']),
             'tone_gain':float(values['tone_gain']),
+            'sonar_db_transform':values['sonar_db_transform'],
+            'sonar_clahe':values['sonar_clahe'],
+            'sonar_clahe_global':values['sonar_clahe_global'],
+            'sonar_clahe_clip_limit':float(values['sonar_clahe_clip_limit']),
             'wcp':values['wcp'],
             'wcm':values['wcm'],
             'wcr':values['wcr'],

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/main_readFiles.py

@@ -718,6 +718,10 @@ def read_master_func(logfilename='',
                      egn_stretch_factor=1,
                      tone_gamma=1.0,
                      tone_gain=1.0,
+                     sonar_db_transform=False,
+                     sonar_clahe=False,
+                     sonar_clahe_global=True,
+                     sonar_clahe_clip_limit=0.01,
                      wcp=False,
                      wcm=False,
                      wcr=False,
@@ -1038,6 +1042,9 @@ def read_master_func(logfilename='',
         son.son8bit = sonar_obj.son8bit
         if hasattr(sonar_obj, 'sample_dtype'):
             son.sample_dtype = sonar_obj.sample_dtype
+        elif file_type == '.svlog':
+            # Cerulean pwr_results are uint16 values in little-endian order.
+            son.sample_dtype = '<u2'
         if hasattr(sonar_obj, 'export_raw_16bit'):
             son.export_raw_16bit = sonar_obj.export_raw_16bit
         if hasattr(son, 'sample_dtype'):
@@ -1201,6 +1208,12 @@ def read_master_func(logfilename='',
             son.cropRange = cropRange
             son.tone_gamma = tone_gamma
             son.tone_gain = tone_gain
+            son.sonar_db_transform = bool(sonar_db_transform)
+            son.sonar_clahe = bool(sonar_clahe)
+            son.sonar_clahe_global = bool(sonar_clahe_global)
+            son.sonar_clahe_clip_limit = float(sonar_clahe_clip_limit)
+            if son.sonar_clahe:
+                son._ensure_clahe_global_bounds()
             # Do range crop, if necessary
             if cropRange > 0.0:
                 if file_type == '.xtf' and _is_sidescan_beam(getattr(son, 'beamName', '')):
@@ -1394,6 +1407,12 @@ def read_master_func(logfilename='',
             son.wcp = wcp
             son.tone_gamma = tone_gamma
             son.tone_gain = tone_gain
+            son.sonar_db_transform = bool(sonar_db_transform)
+            son.sonar_clahe = bool(sonar_clahe)
+            son.sonar_clahe_global = bool(sonar_clahe_global)
+            son.sonar_clahe_clip_limit = float(sonar_clahe_clip_limit)
+            if son.sonar_clahe:
+                son._ensure_clahe_global_bounds()
 
             beam = son.beamName
             if wcr:

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper/main_rectify.py

@@ -126,6 +126,10 @@ def rectify_master_func(logfilename='',
                         egn_stretch_factor=1,
                         tone_gamma=1.0,
                         tone_gain=1.0,
+                        sonar_db_transform=False,
+                        sonar_clahe=False,
+                        sonar_clahe_global=True,
+                        sonar_clahe_clip_limit=0.01,
                         wcp=False,
                         wcm=False,
                         wcr=False,
@@ -368,6 +372,12 @@ def rectify_master_func(logfilename='',
         son.rect_wcr = rect_wcr
         son.export_16bit = bool(export_16bit) and (not bool(getattr(son, 'son8bit', True)))
         son.export_colormap_uint8 = bool(export_colormap_uint8)
+        son.sonar_db_transform = bool(sonar_db_transform)
+        son.sonar_clahe = bool(sonar_clahe)
+        son.sonar_clahe_global = bool(sonar_clahe_global)
+        son.sonar_clahe_clip_limit = float(sonar_clahe_clip_limit)
+        if son.sonar_clahe:
+            son._ensure_clahe_global_bounds()
 
     # ############################################################################
     # # Rectify Heading sonar imagery - Pingwise, not Rubbersheeting             #
@@ -462,6 +472,12 @@ def rectify_master_func(logfilename='',
     for son in portstar:
         son.rect_wcp = rect_wcp
         son.rect_wcr = rect_wcr
+        son.sonar_db_transform = bool(sonar_db_transform)
+        son.sonar_clahe = bool(sonar_clahe)
+        son.sonar_clahe_global = bool(sonar_clahe_global)
+        son.sonar_clahe_clip_limit = float(sonar_clahe_clip_limit)
+        if son.sonar_clahe:
+            son._ensure_clahe_global_bounds()
 
     if (rect_wcp and rubberSheeting) or (rect_wcr and rubberSheeting):
         # Always use COG for rubber sheeting

pingmapper-5.5.3/pingmapper/version.py

@@ -0,0 +1 @@
+__version__ = '5.5.3'

{pingmapper-5.5.1 → pingmapper-5.5.3}/pingmapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pingmapper
-Version: 5.5.1
+Version: 5.5.3
 Summary: Open-source interface for processing recreation-grade side scan sonar datasets and reproducibly mapping benthic habitat
 Author: Cameron Bodine, Daniel Buscombe, Iury T Simoes-Sousa
 Author-email: bodine.cs@gmail.email

pingmapper-5.5.1/pingmapper/version.py

@@ -1 +0,0 @@
-__version__ = '5.5.1'