Refactor shared script helpers

README.md

@@ -26,11 +26,14 @@ Current features:
 - video filenames use the beginning timestamp by subtracting rounded duration from the video metadata timestamp
 - Sony-style video sidecars like `C0011.MP4` plus `C0011M01.XML` are moved and renamed with the video
 - automatic photo burst/HDR grouping per camera
+- optional panorama project (`.pto`) grouping and reference updates
 - inferred subsecond metadata for grouped same-second photo bursts
 
-The working directory is determined from the dragged items. A single dragged folder is the working directory. For multiple dragged files/folders, their last common ancestor is the working directory. Automatic burst/HDR group folders are created inside that working directory.
+The working directory is determined from the dragged items. A single dragged folder is the working directory. For multiple dragged files/folders, their last common ancestor is the working directory. Automatic burst/HDR and `.pto` group folders are created inside that working directory.
 
-If dragged folders contain files in subdirectories, `photo_metadata.py` asks whether ungrouped files should be moved into the working directory. The default is to leave them in their existing subdirectories.
+If dragged folders contain files in subdirectories and grouping is enabled, ungrouped files are moved into the working directory too. This makes the run organize everything into a deterministic flat reset state, with grouped files in their group folders and the remaining files directly in the working directory. If grouping is disabled, the script asks whether to flatten subdirectory files into the working directory.
+
+Panorama project files use the `.pto` extension. When enabled, every media file referenced by a `.pto` file belongs to the same group. If those files already belong to burst/HDR groups, the groups are merged. `.pto` files are moved into the group folder with their referenced files, renamed from the first and last referenced media stems, and their file references are rewritten to the new relative paths.
 
 Reference-clock correction is useful when one photo shows a reliable clock. For example, if `DSC01234.JPG` has camera metadata `2026:06:02 22:10:00`, but the clock in the photo shows `22:13:25`, choose reference mode, enter `DSC01234.JPG` as the source, and enter `22:13:25` as the correct time. The script computes a `+00:03:25` shift and applies that correction to the selected files. If you omit the date in the correct time, the script chooses the date closest to the source timestamp, within 12 hours.
 
@@ -42,14 +45,14 @@ Fast manual grouping for selected files:
 python3 grouping.py path/to/file/or/directory [...]
 ```
 
-It does not ask questions. It sorts the selected filesystem items by name and moves them into one folder named `[first stem]-[last stem]`.
+It does not ask questions. It recursively collects all files inside the dragged files/folders, sorts those files by name, and moves them into one folder named `[first stem]-[last stem]`.
 
-Manual grouping uses filesystem items, not media-file detection:
+Manual grouping uses the same working-directory rule as `photo_metadata.py`:
 
-- one file creates `[file stem]-[file stem]` and moves that file into it
-- one directory acts as if its contents were given; if it contains only one subdirectory, that rule repeats
-- one empty directory does nothing
-- multiple files/folders are grouped as selected, without flattening folder contents
+- one dragged folder is the working directory
+- multiple dragged files/folders use their last common ancestor as the working directory
+- the group folder is created inside the working directory
+- all collected files are flattened into that group folder
 
 ### `view_metadata.py`
 
@@ -77,6 +80,19 @@ The important choices are:
 
 The old `-G` style shows broad groups like `EXIF`, `File`, or `QuickTime`. That is readable, but it can hide where inside a container a value came from. Family 1 groups, from `-G1`, show more exact locations like `IFD0`, `ExifIFD`, `MakerNotes`, or `Track1`, but sometimes lose the broader context. `-G0:1` combines both, so it is the most useful default for debugging metadata without changing which normal tags are extracted. The organization option changes labels, not the underlying metadata extraction; `-a` and `-u` are the parts that affect whether duplicate or unknown printed tags are included.
 
+### `copy_metadata.py`
+
+Copy meaningful metadata from one file to another:
+
+```bash
+python3 copy_metadata.py
+python3 copy_metadata.py source.jpg destination.jpg
+```
+
+If run without files, it asks for source and destination paths. If exactly two files are dragged onto it, it asks which one is the source. Any other number of dragged files is an error.
+
+The script copies normal metadata with ExifTool `-TagsFromFile`, while excluding file/system tags, composite tags, image dimensions, pixel dimensions, and resolution fields that should remain specific to the destination file.
+
 ## Requirements
 
 - Python 3.10 or newer