triplot 1.1.0__py3-none-any.whl

dscpanel/__init__.py

@@ -0,0 +1,4 @@
+"""Triplot (DSC-Panel until 1.0.0): an interactive panel for stacked DSC
+scans from TRIOS files."""
+
+__version__ = "1.1.0"

dscpanel/__main__.py

@@ -0,0 +1,155 @@
+"""The entry point: `triplot`, `triplot-gui`, or `python -m dscpanel`.
+
+Files named on the command line are opened, so the program can be the "open
+with" target for a `.tri` and can be started from a data folder with
+`triplot *.tri`.
+
+Two subcommands sit beside that, and neither of them starts a window:
+`register` puts the program in the Start Menu (and `--remove` takes it out
+again), and `alias` gives it whatever name the user would rather type. Both
+are opt-in and reversible; see `register.py` for why that matters.
+"""
+
+import argparse
+import sys
+
+from . import __version__, branding
+
+
+#: Words that mean "do not open a window". Checked BEFORE argparse, because a
+#: subcommand and an optional list of file paths cannot both be positional:
+#: `paths` with nargs="*" swallows the subcommand name and argparse then
+#: rejects its arguments ("invalid choice: 'dscp'").
+COMMANDS = ("register", "alias")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog=branding.EXE_NAME,
+        description="{} - {}".format(branding.APP_NAME, branding.DESCRIPTION),
+        epilog="subcommands: {} (each takes --help)".format(
+            ", ".join(COMMANDS)))
+    parser.add_argument("paths", nargs="*",
+                        help="TRIOS .tri or .txt files, or a saved session")
+    parser.add_argument("--version", action="version",
+                        version="{} {}".format(branding.APP_NAME, __version__))
+    return parser
+
+
+def build_command_parser():
+    parser = argparse.ArgumentParser(prog=branding.EXE_NAME)
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    reg = subs.add_parser(
+        "register", help="put {} in the Start Menu".format(branding.APP_NAME))
+    reg.add_argument("--remove", action="store_true",
+                     help="take it out again")
+    reg.add_argument("--desktop", action="store_true",
+                     help="a desktop shortcut as well (Windows)")
+    reg.add_argument("--clean-legacy", action="store_true",
+                     help="remove what this program's older names left behind")
+    reg.add_argument("--list", action="store_true",
+                     help="show what is registered")
+    reg.add_argument("--dry-run", action="store_true",
+                     help="say what would happen and change nothing")
+
+    ali = subs.add_parser("alias",
+                          help="start the program under another name too")
+    ali.add_argument("name", nargs="?", help="the name you would rather type")
+    ali.add_argument("--remove", action="store_true", help="take it away")
+    ali.add_argument("--list", action="store_true", help="show the aliases")
+    ali.add_argument("--dry-run", action="store_true")
+    return parser
+
+
+def _register(args):
+    from . import register
+    if args.list:
+        for line in register.describe():
+            print(line)
+        return 0
+    if args.clean_legacy:
+        removed = register.clean_legacy(dry_run=args.dry_run)
+        print("would remove:" if args.dry_run else "removed:",
+              len(removed), "item(s)")
+        for path in removed:
+            print("   ", path)
+        return 0
+    if args.remove:
+        removed = register.unregister(dry_run=args.dry_run)
+        print("would remove:" if args.dry_run else "removed:", len(removed))
+        for path in removed:
+            print("   ", path)
+        return 0
+    made = register.register(desktop=args.desktop, dry_run=args.dry_run)
+    print("would write:" if args.dry_run else "wrote:")
+    for kind, path in made:
+        print("    {:<14} {}".format(kind, path))
+    print("started by: {}".format(" ".join(register.launcher())))
+    return 0
+
+
+def _alias(args):
+    from . import register
+    if args.list or not args.name:
+        found = register.aliases()
+        print("\n".join(found) if found
+              else "no aliases (try: {} alias tp)".format(branding.EXE_NAME))
+        return 0
+    path = register.alias(args.name, remove=args.remove, dry_run=args.dry_run)
+    verb = "would remove" if (args.remove and args.dry_run) else (
+        "removed" if args.remove else
+        ("would write" if args.dry_run else "wrote"))
+    print("{} {}".format(verb, path))
+    if not args.remove and not args.dry_run:
+        print("open a new terminal, then: {}".format(args.name))
+    return 0
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    # The first start under a new name brings the old name's preferences,
+    # presets and registration manifest along (`branding.py`), BEFORE the
+    # log, the style or `register --clean-legacy` read that folder.
+    branding.adopt_legacy_dir()
+    if argv and argv[0] in COMMANDS:
+        args = build_command_parser().parse_args(argv)
+        return _register(args) if args.command == "register" else _alias(args)
+    args = build_parser().parse_args(argv)
+    # Imported HERE rather than at the top, so `--version`, `register` and
+    # `alias` do not pay for Qt - which is most of the start-up time.
+    from PySide6.QtWidgets import QApplication
+    from .core import log, style
+    from .ui.window import MainWindow
+
+    # The log first: an error from here on goes into it, and one inside a Qt
+    # slot no longer ends the program (`core/log.py`).
+    log.install()
+
+    # The user's house style (Edit > Settings). Loaded HERE and not by the
+    # window, so a window made by a test or a tool never reads the defaults
+    # of whoever happens to run it.
+    style.load_preferences()
+    app = QApplication.instance() or QApplication(sys.argv[:1])
+    app.setApplicationName(branding.APP_NAME)
+    app.setOrganizationName(branding.SETTINGS_ORG)
+    app.setApplicationDisplayName(branding.APP_NAME)
+    window = MainWindow()
+    log.on_error = window.show_error
+    # Where it was last time; maximized the first time.
+    if window.restore_layout():
+        window.show()
+    else:
+        window.showMaximized()
+    sessions = [p for p in args.paths
+                if str(p).lower().endswith(branding.SESSION_EXT)]
+    if sessions:
+        window.open_session(sessions[0])
+    others = [p for p in args.paths if p not in sessions]
+    if others:
+        window.open_files(others)
+    return app.exec()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dscpanel/branding.py

@@ -0,0 +1,142 @@
+"""Every place the program says its own name, in ONE module.
+
+The name was expected to change, and it did: "DSC-Panel" was the working
+title until 1.1.0, the first release on PyPI, as Triplot. A
+name that is spelled out in twenty places is a name nobody dares to change.
+So:
+
+* the window title, the Start Menu shortcut, the file-type id, the settings
+  folder and the manifest of what was registered all read from here;
+* `LEGACY_NAMES` lists every name this program has been called before, so a
+  release under a new name can take the OLD name's shortcuts, file type and
+  aliases away. That is the whole deregistration plan: the new version knows
+  what the old one installed, because the old name is still written down.
+
+What a rename costs, with this module in place:
+
+1. change `APP_NAME`, `EXE_NAME`, `PROG_ID` and `SETTINGS_ORG`/`SETTINGS_APP`
+   here, and add the outgoing values to `LEGACY_NAMES`;
+2. change the two entry-point lines in `pyproject.toml` (and the
+   distribution's name there, if it goes too);
+3. uninstall the old distribution (this removes the old command), install
+   the new one;
+4. run `<new command> register --clean-legacy`, which reads `LEGACY_NAMES`
+   and the registration manifest and removes what the old name left behind.
+
+The user's folder (`app_dir`: preferences, presets, the manifest) is named
+after the program too, so the first start under a new name copies the old
+one's across (`adopt_legacy_dir`) - the house style, the presets and the
+window's place survive, and so does the manifest the cleanup reads.
+
+Nothing else in the program contains the name as a literal. A test enforces
+that (`tests/test_branding.py`).
+"""
+
+import os
+import sys
+
+#: What the program calls itself in the window title and the Start Menu.
+APP_NAME = "Triplot"
+
+#: The command, and the base name of every shortcut and shim that is created.
+EXE_NAME = "triplot"
+
+#: The windowed entry point, which a shortcut prefers so no console appears.
+EXE_NAME_GUI = "triplot-gui"
+
+#: The Explorer file-type id for the session file, under HKCU\Software\Classes.
+PROG_ID = "Triplot.Session"
+
+#: The session file's extension. Kept through the rename to Triplot: it names
+#: what the file holds (a DSC figure), and every saved figure has it.
+SESSION_EXT = ".dscpanel"
+
+#: A style preset's extension (`core/presets.py`): JSON inside, named so a
+#: dropped one is known for what it is.
+PRESET_EXT = ".dscstyle"
+
+#: QSettings coordinates. Changing these forgets the user's window geometry,
+#: which is why they are written down rather than derived from APP_NAME.
+SETTINGS_ORG = "ACH"
+SETTINGS_APP = "Triplot"
+
+#: Names this program has gone by. (name, exe, prog_id) for each, oldest
+#: first. `register --clean-legacy` walks this list and removes anything it
+#: finds: Start Menu shortcuts, desktop shortcuts, PATH shims and the file
+#: association. Add the outgoing values here as part of a rename; never
+#: remove an entry, because somebody's machine may still be carrying it.
+LEGACY_NAMES = (
+    ("DSC-Panel", "dsc-panel", "DscPanel.Session"),     # until 1.0.0
+)
+
+#: A one-line description, for shortcut tooltips and the About box.
+DESCRIPTION = "Stacked DSC scans from TRIOS files"
+
+#: The program's public page, for the About box. It carries the name, so it
+#: is written here and nowhere else (and changes with a rename).
+HOMEPAGE = "https://pypi.org/project/triplot/"
+
+#: The copyright line from LICENSE, for the About box.
+COPYRIGHT = ("Christian Nelle (@p3rAsperaAdAstra), AG Henke, "
+             "TU Dortmund. MIT licence.")
+
+
+def app_dir(app_name=None, exe_name=None):
+    """Where the registration manifest and any user data live.
+
+    Per user, never per install, so a reinstall does not lose track of the
+    shortcuts the last install made. With a name, the folder a program of
+    that name used (a `LEGACY_NAMES` entry's first two).
+    """
+    app_name = app_name or APP_NAME
+    exe_name = exe_name or EXE_NAME
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        return os.path.join(base, app_name)
+    if sys.platform == "darwin":
+        return os.path.expanduser(
+            "~/Library/Application Support/" + app_name)
+    base = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return os.path.join(base, exe_name)
+
+
+def adopt_legacy_dir():
+    """Copy the newest older name's folder to `app_dir()`, the first time.
+
+    Only when `app_dir()` does not exist yet: once it does, it is this
+    name's own and nothing is copied over it. The old folder stays where it
+    is (an older install may still be using it); its logs are not copied,
+    because a log is named after the program that wrote it. Returns the
+    folder copied from, or None. Never raises: a copy that fails leaves the
+    program starting with the built-in style, as on a new machine.
+    """
+    import shutil
+    target = app_dir()
+    try:
+        if os.path.exists(target):
+            return None
+        for app_name, exe_name, _prog_id in reversed(LEGACY_NAMES):
+            source = app_dir(app_name, exe_name)
+            if os.path.isdir(source) and source != target:
+                shutil.copytree(source, target, ignore=shutil.ignore_patterns(
+                    "*.log", "*.log.*"))
+                return source
+    except (OSError, shutil.Error):
+        return None
+    return None
+
+
+def manifest_path():
+    """The file listing what this program has registered on this machine.
+
+    Written by `register`, read by `register --remove` and
+    `register --clean-legacy`. It exists so that removal takes away exactly
+    what was added, rather than guessing at paths a future version might get
+    wrong.
+    """
+    return os.path.join(app_dir(), "registration.json")
+
+
+def window_title(subject=""):
+    """`APP_NAME`, with the open session or file in front of it."""
+    return "{} - {}".format(subject, APP_NAME) if subject else APP_NAME

dscpanel/core/arrange.py

@@ -0,0 +1,143 @@
+"""Arranging scans: the operators that move several at once.
+
+UI-free, and every function returns CHANGES - `[(scan, "offset", value), ...]`
+- rather than applying them. The window pushes that list through the undo
+stack, so "distribute evenly" is one Ctrl+Z like every other action, and these
+functions stay testable without a window.
+
+The baseline alignment is the one piece of real arithmetic. It is the
+`y_align` from the DSC_Plotter template, with the numerical machinery taken
+out: minimising `sum w (ref - (curve + c))^2` over one number `c` has a
+closed form, `c = weighted mean of (ref - curve)`, so the template's
+`scipy.optimize.minimize_scalar` per curve is not needed and neither is
+scipy.
+"""
+
+import numpy as np
+
+
+def _monotonic(x, y):
+    """`(x, y)` sorted and de-duplicated, ready for `np.interp`.
+
+    A DSC segment is not sorted in temperature - it reverses at the ends, and
+    a cooling scan runs backwards - so anything that interpolates has to sort
+    first. Duplicate x values are averaged rather than dropped, because
+    dropping one silently prefers whichever sample came first.
+
+    A flagged sample (NaN in either) is left out: `np.interp` over one gives
+    NaN, and a NaN offset is a curve drawn nowhere and saved so (review
+    F11).
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    measured = np.isfinite(x) & np.isfinite(y)
+    x, y = x[measured], y[measured]
+    order = np.argsort(x, kind="stable")
+    x, y = x[order], y[order]
+    unique, index, inverse = np.unique(x, return_index=True,
+                                       return_inverse=True)
+    if len(unique) != len(x):
+        counts = np.bincount(inverse)
+        y = np.bincount(inverse, weights=y) / np.maximum(counts, 1)
+        x = unique
+    return x, y
+
+
+def align_to(reference, scans, curve_of, window=(0.0, 1.0), points=2000):
+    """Offsets that lay each scan on top of `reference` where they overlap.
+
+    `curve_of(scan)` gives `(x, y)` as drawn. `window` is the part of the
+    common x range the curves should agree over, as fractions - the default
+    is all of it, and `(0, 0.4)` is the template's "match the start", which
+    is what you want when the interesting difference is at the end.
+
+    A scan with no overlap is left where it is rather than moved to a
+    meaningless place.
+    """
+    ref_x, ref_y = curve_of(reference)
+    if ref_x is None or len(ref_x) < 2:
+        return []
+    ref_x, ref_y = _monotonic(ref_x, ref_y)
+    if len(ref_x) < 2:
+        return []
+    changes = []
+    for scan in scans:
+        if scan is reference:
+            continue
+        x, y = curve_of(scan)
+        if x is None or len(x) < 2:
+            continue
+        x, y = _monotonic(x, y)
+        if len(x) < 2:
+            continue
+        lo = max(float(ref_x[0]), float(x[0]))
+        hi = min(float(ref_x[-1]), float(x[-1]))
+        if hi <= lo:
+            continue
+        grid = np.linspace(lo, hi, int(points))
+        a = np.interp(grid, ref_x, ref_y)
+        b = np.interp(grid, x, y)
+        frac = (grid - lo) / max(hi - lo, 1e-12)
+        weight = np.where((frac >= window[0]) & (frac <= window[1]), 1.0, 0.1)
+        shift = float(np.sum(weight * (a - b)) / np.sum(weight))
+        changes.append((scan, "offset", float(scan.offset) + shift))
+    return changes
+
+
+def stack(scans, step, first=0.0):
+    """Give the scans offsets `first`, `first + step`, ... in list order.
+
+    The order is the one the caller hands over, which is the outliner's -
+    what you see top to bottom is what gets stacked top to bottom.
+    """
+    changes = []
+    for i, scan in enumerate(scans):
+        changes.append((scan, "offset", float(first) + i * float(step)))
+    return changes
+
+
+def distribute(scans):
+    """Even spacing between the topmost and bottommost scan, order kept.
+
+    The two ends stay where they are - somebody put them there - and
+    everything between them is spread evenly, which is the gesture you want
+    after dragging eight scans roughly into place.
+    """
+    scans = [s for s in scans]
+    if len(scans) < 3:
+        return []
+    ordered = sorted(scans, key=lambda s: s.offset)
+    lo = float(ordered[0].offset)
+    hi = float(ordered[-1].offset)
+    if hi == lo:
+        return []
+    step = (hi - lo) / (len(ordered) - 1)
+    changes = []
+    for i, scan in enumerate(ordered):
+        value = lo + i * step
+        if abs(value - scan.offset) > 1e-12:
+            changes.append((scan, "offset", value))
+    return changes
+
+
+def suggested_step(scans, curve_of, fraction=0.6):
+    """A sensible vertical spacing for a stack, in the current unit.
+
+    The tallest scan's own span times `fraction`: enough that curves do not
+    sit on top of one another, not so much that the stack runs off the plot.
+    Measured rather than guessed, because a spacing that is right in W/g is
+    wrong by a factor of a thousand in mW.
+    """
+    spans = []
+    for scan in scans:
+        x, y = curve_of(scan)
+        if y is None or not len(y):
+            continue
+        y = np.asarray(y, dtype=float)
+        y = y[np.isfinite(y)]
+        if not len(y):
+            continue
+        spans.append(float(np.max(y) - np.min(y)))
+    if not spans:
+        return 0.0
+    return max(spans) * float(fraction)