From 7f74e01a9598f66c33a52f5522ba2aa291973918 Mon Sep 17 00:00:00 2001 From: Bill Clay Date: Sun, 26 Jan 2025 21:59:03 +0100 Subject: [PATCH 1/3] "custom sort" documentation additions, v.0 --- .../digital-asset-management/custom-sort.md | 72 +++++++++++++++++++ .../metadata-tagging.md | 2 +- .../digital-asset-management/sequence.md | 27 +++++++ .../lighttable-modes/filemanager.md | 8 ++- .../lighttable-modes/zoomable-lighttable.md | 4 +- content/lighttable/overview.md | 10 ++- content/lighttable/undo-redo.md | 4 +- .../utility-modules/shared/export.md | 2 +- .../utility-modules/shared/filmstrip.md | 3 + .../utility-modules/shared/tagging.md | 2 + content/overview/sidecar-files/sidecar.md | 4 +- content/overview/user-interface/filmstrip.md | 2 +- content/overview/workflow/export.md | 4 +- 13 files changed, 135 insertions(+), 9 deletions(-) create mode 100644 content/lighttable/digital-asset-management/custom-sort.md create mode 100644 content/lighttable/digital-asset-management/sequence.md diff --git a/content/lighttable/digital-asset-management/custom-sort.md b/content/lighttable/digital-asset-management/custom-sort.md new file mode 100644 index 0000000000..83cbdac787 --- /dev/null +++ b/content/lighttable/digital-asset-management/custom-sort.md @@ -0,0 +1,72 @@ +--- +title: custom sort +id: custom-sort +draft: true +weight: 80 +author: "wbclay" +--- + +Setting _sort by_ > "custom sort" presents images in any sequence you define. Images are initally ordered by an image property (import order, image capture time, file name, etc.) but you can then incrementally alter any "custom sort" sequence by drag-and-drop as desired. Be careful: an erroneous drag-and-drop can easily ruin one or more painstakingly-created image sequences. + +### cautions {#cautions} + +- "Undo" __does not reverse__ drag-and-drop resequencing. + +- Drag-and-drop resequencing is __always__ enabled in lighttable filemanager and in the filmstrip, but any resulting __changes are invisible__ if _sort by_ > "custom sort" is not in effect. + +- Ensure any image you drag is __not selected__ unless you want to reposition the entire currently selected set. + +- Aim your "drops" accurately: verify the correct target is __highlighted__ before dropping! + +- "custom sort" positions are lost if images are removed from darktable or their tags are detached or deleted ([why?](../../../overview/sidecar-files/sidecar.md/#fn:1)). + +### _which_ custom sort sequence? + +Collection type determines which [image sequence](../../lighttable/digital-asset-management/sequence.md) drag-and-drop changes. If the collection's primary selection criterion is _tag_, a __tag-based__ "custom sort" sequence is altered. Otherwise, the __global__ "custom sort" sequence is altered. Collection filters, if any, do not affect which sequence drag-and-drop changes. + +When _sort by_ > "custom sort" is in effect, dragged-and-dropped images are immediately presented in their new tag-based or global "custom sort" sequence. + +### what to drag, where to drop? + +While viewing a collection in filemanager or the filmstrip, you may drag any hovered-over (highlighted) image to any other image in the displayed collection. Empty space before, between, or after images is not a recognized drop target. + +- You may relocate a single image (unselected or sole selection) or a selected set of images by dragging one of them to desired position as follows: + +- Drop on the image you want a dragged image or selected set to __precede__ when _sort order_ is __"ascending"__. + +- Drop on the image you want a dragged image or selected set to __follow__ when _sort order_ is __"descending"__. + +### who's last? (or, in descending sort, first?) + +- An image dropped after the last image on lighttable is regarded as dropped __on the last image__, thus positioned before it. +- To change the last image in an "ascending" "custom sort" display, drop it on the existing last image, then drag-and-drop that last image on its intended replacement. +- If you expect to use a "descending" sort, do the opposite to change the first image. + +### suggested process + +1. If you intend to present a collection in more than one "custom sort" sequence or if some images in a collection are included in other collections to be displayed with a different "custom sort", then it is probably preferable define tag-based collections. + +2. For tag-based "custom sort" only: +- Set _sort by_ to the image attribute and _sort order_ (ascending or descending) you want as your tag's initial sequence, +- Select the images to be sequenced, and +- in the right-hand panel at _tagging_, bottom half, add a new tag or click on an existing tag. +- The tag is now attached to the selected images in the displayed sequence. Note the tag's increased image count. +- Change _collections_ selection crierion to "tag" and choose the newly-applied tag. Note that the newly-tagged images are shown. +3. Long-distance drags are difficult because neither _filemanager_ nor _filmstrip_ scroll while you drag. Try to fit drag sources and targets onto the same screen by maximizing the the window and scrolling the display. If that's not sufficient: +- increase the number of images displayed (thus shrinking thumbnails) or +- hide images between drag source and drop target using _collection filters_ (e.g., by ranges of "datetime captured" or "image id"). +4. Rearrange the images as you desire: +- __Clear any active selection__: _selection_ > _select none_. +- Set _sort by_ > "custom sort" so you can verify your changes immediately. +- Remember the __[cautions](#cautions)__ above as you drag-and-drop. + +### corner cases + +drop-target moves or vanishes +: Resequencing, filtering out, or even deleting a "dropped-on" image does _not_ resequence images that were dropped on it earlier. They remain where the "dropped on" image was previously located. + +mixed-up tags +: As of this writing, resequencing behavior of collections based on multiple tags or on a mix of tagged and untagged images is not clear. Use "custom sort" on such collections with caution pending further research. + +tag editing considered harmful +: A change request laments that editing tags regenerates the related "tagged image" database table in an unspecified order, possibly losing any previous "custom sort." diff --git a/content/lighttable/digital-asset-management/metadata-tagging.md b/content/lighttable/digital-asset-management/metadata-tagging.md index 11c6a4af9f..ec22eb7bd8 100644 --- a/content/lighttable/digital-asset-management/metadata-tagging.md +++ b/content/lighttable/digital-asset-management/metadata-tagging.md @@ -14,4 +14,4 @@ Metadata (e.g. title, description) is free-format text that usually differs for # tagging -Tags are usually shared between multiple images and are used to categorise and group them. You can add tags to images in the [tagging](../../module-reference/utility-modules/shared/tagging.md) module. +Tags are usually shared between multiple images and are used to categorise, group, and/or [sequence](../../lighttable/digital-asset-management/sequence.md) them. You can add tags to images in the [tagging](../../module-reference/utility-modules/shared/tagging.md) module. diff --git a/content/lighttable/digital-asset-management/sequence.md b/content/lighttable/digital-asset-management/sequence.md new file mode 100644 index 0000000000..b633c207ab --- /dev/null +++ b/content/lighttable/digital-asset-management/sequence.md @@ -0,0 +1,27 @@ +--- +title: image seqence +id: sequence +draft: true +weight: 70 +author: "wbclay" +--- + +A collection's images are always presented in a specific _sort by_ sequence that determines the order of their display and export, which is often convenient to control (_e.g._, for a slideshow or document). + +You may choose an [image attribute](../../module-reference/utility-modules/shared/collections/#filtering-attributes) (filename, capture time, rating, title, etc.) as the sort criterion in the _sort by_ pull-down menu and icon at the left-hand-side of darktable's [top panel](../../../overview/user-interface/top-panel/) or combine multiple sort criteria by clicking on _new sort_ in the left panel at the bottom of the [collection filters](../../module-reference/utility-modules/shared/collection-filters/#sorting). + +Whatever sort criteria are chosen, a collection may contain some images you need to present in a different order. In such cases, darktable's [custom sort](../../lighttable/digital-asset-management/custom-sort.md) allows you to alter image sequence directly by dragging and dropping thumbnails in lighttable filemangager or the filmstrip. + +There are two distinct "custom sort" sequencing regimes: + +- One __global sequence__ over every image in a darktable repository. + +- Multiple __tag-based__ sequences, one for each tag associated with one or more images. + +When an image is imported into your darktable library, it is automatically positioned in the global sequence after all previously-imported images. A duplicated image is initially positioned in the global sequence immediately after its original, regardless of intervening image imports. + +Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is applied. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its origanal's tags and is positioned within each as a newly-tagged image. + +The __primary selection criterion__ of a collection determines which sequence drag-and-drop alters while working in lighttable filemanager or the filmstrip. If the primary collection criterion is "tag", drag-and-drop alters the chosen tag-based sequence(s). Otherwise, drag-and-drop alters the global sequence of all images in the library. + +The next section, [custom sort](../../lighttable/digital-asset-management/custom-sort.md), suggests how to efficiently and safely use drag-and-drop image resequencing. __Note its [cautions](./custom-sort.md#cautions).__ diff --git a/content/lighttable/lighttable-modes/filemanager.md b/content/lighttable/lighttable-modes/filemanager.md index 6c052e90ba..20ee443a0b 100644 --- a/content/lighttable/lighttable-modes/filemanager.md +++ b/content/lighttable/lighttable-modes/filemanager.md @@ -17,4 +17,10 @@ navigate : You can navigate through the images using the arrow keys (←/→/↑/↓) or by scrolling with your mouse. Press the Home key to scroll to the top of the collection, the End key to scroll to the bottom, and PageUp/PageDown to scroll up/down by a page. select -: You can select the image under the pointer by clicking on its thumbnail or by pressing Enter. A range of images can be selected by clicking on the first image and then Shift+clicking on the last one. Images can be added or removed from a selection by Ctrl+clicking on their thumbnails or by pressing Spacebar. +: You can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar. + +hover +: When the pointer hovers over any image's thumbnail, it is highlighted and its image implicitly selected for keyboard shortcuts. If that thumbnail is part of a currently-selected set, certain shortcuts will be applied to _all_ images of the set (for example, a numeric digit star rating). + +drag +: You can drag a thumbnail (__along with any selected set__ to which it may belong) to set its [custom sort](../../lighttable/digital-asset-management/custom-sort.md) position just before or after the image it's dropped upon. diff --git a/content/lighttable/lighttable-modes/zoomable-lighttable.md b/content/lighttable/lighttable-modes/zoomable-lighttable.md index 3b6db5b9a6..251b5ae519 100644 --- a/content/lighttable/lighttable-modes/zoomable-lighttable.md +++ b/content/lighttable/lighttable-modes/zoomable-lighttable.md @@ -18,8 +18,10 @@ navigate : Hold down the left mouse button and drag to move the lighttable around and navigate through your collection. select -: As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. A range of images can be selected by clicking on the first image and then Shift+clicking on the last one. Images can be added to or removed from a selection by Ctrl+clicking on their thumbnails or by pressing Spacebar. +: As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar. +hover +: Hovering over a thumbnail highlights and impicitly selects it for keyboard shortcuts as in filemanager mode. However, dragging moves the whole thumbnail display, so you cannot change images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order in this mode. --- **Hint:** you may find that image thumbnails are slow to load when zooming quickly through a large collection. One way to speed up the navigation is to generate a cache containing all the thumbnails using the [`darktable-generate-cache`](../../special-topics/program-invocation/darktable-generate-cache.md) command. diff --git a/content/lighttable/overview.md b/content/lighttable/overview.md index e4b55c5257..2d7893582f 100644 --- a/content/lighttable/overview.md +++ b/content/lighttable/overview.md @@ -10,7 +10,9 @@ The lighttable view allows you to view and manage your image collection. The centre view contains thumbnails of your images -- how they are displayed depends on which [mode](./lighttable-modes/_index.md) you are working in. -While the mouse is over an image thumbnail or images are selected, there are a number of actions you can perform with keyboard shortcuts: +While the mouse is over an image thumbnail or images are selected, there are a number of actions you can perform: + +# keyboard shortcuts - `F1, F2, F3, F4, F5` adds or removes a color label (red, yellow, green, blue, purple, respectively). A color label will be added if _any_ selected image does not currently have the label; otherwise the label will be removed @@ -33,3 +35,9 @@ While the mouse is over an image thumbnail or images are selected, there are a n - `W ` fully zooms into the current image while the key is pressed - `Ctrl+W ` fully zooms into the current image and show areas in focus + +# drag-and-drop + +- You may change the sequence of images displayed, processed, or exported when _sort by_ is set to [custom sort](../../lighttable/digital-asset-management/custom-sort.md) by dragging and dropping their thumbnails. + +- Use of this feature requires careful attention. __Note its [cautions](./digital-asset-management/custom-sort.md#cautions).__ diff --git a/content/lighttable/undo-redo.md b/content/lighttable/undo-redo.md index a050a02064..405ca6d202 100644 --- a/content/lighttable/undo-redo.md +++ b/content/lighttable/undo-redo.md @@ -6,6 +6,8 @@ weight: 30 author: "people" --- -Most changes made within the lighttable are recorded and can be reverted to a previous state. This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. +Most changes made within the lighttable are recorded and can be reverted to a previous state.[^1] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. + +[^1]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip. Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any). diff --git a/content/module-reference/utility-modules/shared/export.md b/content/module-reference/utility-modules/shared/export.md index 9f425b8062..d4380e5563 100644 --- a/content/module-reference/utility-modules/shared/export.md +++ b/content/module-reference/utility-modules/shared/export.md @@ -20,7 +20,7 @@ target storage : The type of location to store your selected images. A number of different back-ends are implemented, including file on disk, LaTeX book template and various web albums. Depending on the selected target, you will be asked to provide additional information, such as filenames or account name and password. filename template -: Define the folder and file to which the image will be exported. This can be automatically generated using several pre-defined variables. See the [variables](../../../special-topics/variables.md) section for details. +: Define the folder and file to which the image will be exported. This can be automatically generated using several pre-defined variables. For example, `$(SEQUENCE)` in a template records sequence number of the image exported to the target. See the [variables](../../../special-topics/variables.md) section for details. output directory selector : The button beside the filename template entry opens a dialog to select the parent directory for export. diff --git a/content/module-reference/utility-modules/shared/filmstrip.md b/content/module-reference/utility-modules/shared/filmstrip.md index 754ed327e3..e497482d04 100644 --- a/content/module-reference/utility-modules/shared/filmstrip.md +++ b/content/module-reference/utility-modules/shared/filmstrip.md @@ -18,6 +18,8 @@ In the darkroom, the image currently being processed is selected and highlighted If you wish to select multiple images in the filmstrip, click to select the first image followed by either Ctrl+click to select or de-select further images, or Shift+click to select a range of images. +You may change the _custom sort_ order of images in the filmstrip by dragging and dropping thumbnails as described at [custom sort](../../../../lighttable/digital-asset-management/custom-sort.md). + The following shortcuts can be used to select images in the filmstrip: - `Ctrl+A` selects all images in the filmstrip @@ -26,6 +28,7 @@ The following shortcuts can be used to select images in the filmstrip: - `Ctrl+I` inverts the current selection + The following shortcuts can be used to perform operations on the selected images - `F1, F2, F3, F4, F5` adds or removes a color label (red, yellow, green, blue, purple, respectively). A color label will be added if _any_ selected image does not currently have the label; otherwise the label will be removed diff --git a/content/module-reference/utility-modules/shared/tagging.md b/content/module-reference/utility-modules/shared/tagging.md index acf372c68a..a4f1b3b7d6 100644 --- a/content/module-reference/utility-modules/shared/tagging.md +++ b/content/module-reference/utility-modules/shared/tagging.md @@ -21,6 +21,8 @@ tag : You can assign properties (name, private, category, synonyms and image order) to a tag. +: You can use tag names to define [collections](../collections/) that are displayed, processed, and exported in a _durable_ [custom sort](../../../lighttable/digital-asset-management/custom-sort/) order, unchanging when other collections sharing some of the same images are reordered. + node : Any path that forms part of a tag is a node. In the above example, "`places`", "`places|France`", "`places|France|Nord`" and "`places|France|Nord|Lille`" are all nodes. In the hierarchical tree view, the nodes form the branches and leaves of the tree. diff --git a/content/overview/sidecar-files/sidecar.md b/content/overview/sidecar-files/sidecar.md index 73093eb36e..7cd1939fa6 100644 --- a/content/overview/sidecar-files/sidecar.md +++ b/content/overview/sidecar-files/sidecar.md @@ -6,7 +6,9 @@ draft: false author: "people" --- -darktable is a non-destructive image editor and opens all images in read-only mode. Any data created within darktable (metadata, tags, and image processing steps) is stored in separate `.XMP` _sidecar_ files. These files are stored alongside the original Raw files and allow darktable to store information about the images as well as the full editing history without touching the original raw files. When you import an image into darktable for the first time, an XMP file is automatically generated. The generation of XMP files can be disabled in [preferences > storage > XMP sidecar files](../../preferences-settings/storage.md#xmp-sidecar-files) but this is not recommended in normal use. +darktable is a non-destructive image editor and opens all images in read-only mode. Most data created within darktable (metadata, tags, and image processing steps) is stored in separate `.XMP` _sidecar_ files.[^1] These files are stored alongside the original Raw files and allow darktable to store information about the images as well as the full editing history without touching the original raw files. When you import an image into darktable for the first time, an XMP file is automatically generated. The generation of XMP files can be disabled in [preferences > storage > XMP sidecar files](../../preferences-settings/storage.md#xmp-sidecar-files) but this is not recommended in normal use. + +[^1]: [custom sort](../../lighttable/digital-asset-management/custom-sort.md) sequence numbers __are not stored__ in sidecar files. They could be destructive if imported into another darktable image library -- including their orginal library after import, duplication, or image resequencing. For a given source image, multiple editing versions, called _duplicates_, can co-exist, sharing the same input image data but each having their own metadata, tags and processing steps. Each duplicate of a given image (named `._..xmp`, where `` represents the version number of that edit). Information for the initial edit -- the “duplicate” with version number zero -- is stored in the sidecar file named `..xmp`. The version number of each duplicate is displayed in the [image information](../../module-reference/utility-modules/shared/image-information.md) module in each of darktable's views. diff --git a/content/overview/user-interface/filmstrip.md b/content/overview/user-interface/filmstrip.md index bf1e7d3522..5557591a1e 100644 --- a/content/overview/user-interface/filmstrip.md +++ b/content/overview/user-interface/filmstrip.md @@ -8,6 +8,6 @@ author: "people" The filmstrip, when enabled, is shown at the bottom of the screen (except in the lighttable view, where it is replaced with the [timeline](../../module-reference/utility-modules/lighttable/timeline.md) module) and displays the images from the current [collection](../../lighttable/digital-asset-management/collections.md) (set in the lighttable view). You can navigate the filmstrip by scrolling with the mouse wheel. -The filmstrip allows you to interact with images while you are not in the lighttable view. For example, while developing an image in darkroom mode, you can switch to another image by double-clicking its thumbnail in the filmstrip. You can also rate and color-classify the images as you do in lighttable, as well as copy & paste the history stack using keyboard shortcuts. +The filmstrip allows you to interact with images while you are not in the lighttable view. For example, while developing an image in darkroom mode, you can switch to another image by double-clicking its thumbnail in the filmstrip. You can also rate and color-classify the images as you do in lighttable, as well as copy & paste the history stack using keyboard shortcuts. And as in lighttable, you can drag and drop thumbnails to change images' sequence in [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order. See the [filmstrip](../../module-reference/utility-modules/shared/filmstrip.md) module documentation for more information. diff --git a/content/overview/workflow/export.md b/content/overview/workflow/export.md index 95cfb61bad..face7dc573 100644 --- a/content/overview/workflow/export.md +++ b/content/overview/workflow/export.md @@ -14,6 +14,8 @@ darktable is a non-destructive editor, which means that all changes are recorded 2. Select which images to export (if you are in the lighttable view), open the export module, set _target storage_ to "file on disk" and select a location to save your images -- by default, they will be exported to a "darktable_exported" directory within the directory that contains your Raw file(s). Choose a "file format" of JPEG and keep the default settings. -3. Click the "export" button to save your processed images in the selected location. +3. If the exported collection's [image sequence](../../lighttable/digital-asset-management/sequence.md) is important (_e.g._, a slideshow or to merge photos into a document) and not reflected by file names, select appropriate "sort by" criteria and include `$(SEQUENCE)` in the export file name template. + +4. Click the "export" button to save your processed images in the selected location. _**Note:** While JPEG is useful for most purposes, if you wish to perform further edits in a raster editor like GIMP or Krita, it is normally better to export in TIFF format._ From d07f662b040c776fa7413e9cf7ef728c7ab5f91b Mon Sep 17 00:00:00 2001 From: Bill Clay Date: Thu, 30 Jan 2025 11:48:55 +0100 Subject: [PATCH 2/3] pre-submission edit, "custom sort" documentation additions, v.0 --- content/lighttable/digital-asset-management/custom-sort.md | 1 - content/lighttable/digital-asset-management/sequence.md | 7 +++---- content/lighttable/undo-redo.md | 4 ++-- .../module-reference/utility-modules/shared/filmstrip.md | 6 +++--- content/overview/user-interface/top-panel.md | 7 +++++-- 5 files changed, 13 insertions(+), 12 deletions(-) diff --git a/content/lighttable/digital-asset-management/custom-sort.md b/content/lighttable/digital-asset-management/custom-sort.md index 83cbdac787..68576090e6 100644 --- a/content/lighttable/digital-asset-management/custom-sort.md +++ b/content/lighttable/digital-asset-management/custom-sort.md @@ -1,7 +1,6 @@ --- title: custom sort id: custom-sort -draft: true weight: 80 author: "wbclay" --- diff --git a/content/lighttable/digital-asset-management/sequence.md b/content/lighttable/digital-asset-management/sequence.md index b633c207ab..2748aa474d 100644 --- a/content/lighttable/digital-asset-management/sequence.md +++ b/content/lighttable/digital-asset-management/sequence.md @@ -1,16 +1,15 @@ --- title: image seqence id: sequence -draft: true weight: 70 author: "wbclay" --- -A collection's images are always presented in a specific _sort by_ sequence that determines the order of their display and export, which is often convenient to control (_e.g._, for a slideshow or document). +A collection's images are always presented in a specific _sort by_ sequence that determines the order of their display, processing, and export, which it is often convenient to control (_e.g._, for a slideshow or document). You may choose an [image attribute](../../module-reference/utility-modules/shared/collections/#filtering-attributes) (filename, capture time, rating, title, etc.) as the sort criterion in the _sort by_ pull-down menu and icon at the left-hand-side of darktable's [top panel](../../../overview/user-interface/top-panel/) or combine multiple sort criteria by clicking on _new sort_ in the left panel at the bottom of the [collection filters](../../module-reference/utility-modules/shared/collection-filters/#sorting). -Whatever sort criteria are chosen, a collection may contain some images you need to present in a different order. In such cases, darktable's [custom sort](../../lighttable/digital-asset-management/custom-sort.md) allows you to alter image sequence directly by dragging and dropping thumbnails in lighttable filemangager or the filmstrip. +Whatever _sort by_ criterion is chosen, a collection may contain some images you need to present in a different order. In such cases, darktable's [custom sort](../../lighttable/digital-asset-management/custom-sort.md) allows you to alter image sequence directly by dragging and dropping thumbnails in lighttable filemangager or the filmstrip. There are two distinct "custom sort" sequencing regimes: @@ -20,7 +19,7 @@ There are two distinct "custom sort" sequencing regimes: When an image is imported into your darktable library, it is automatically positioned in the global sequence after all previously-imported images. A duplicated image is initially positioned in the global sequence immediately after its original, regardless of intervening image imports. -Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is applied. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its origanal's tags and is positioned within each as a newly-tagged image. +Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is attached. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its origanal's tags and is positioned within each as a newly-tagged image. The __primary selection criterion__ of a collection determines which sequence drag-and-drop alters while working in lighttable filemanager or the filmstrip. If the primary collection criterion is "tag", drag-and-drop alters the chosen tag-based sequence(s). Otherwise, drag-and-drop alters the global sequence of all images in the library. diff --git a/content/lighttable/undo-redo.md b/content/lighttable/undo-redo.md index 405ca6d202..7b20f8a091 100644 --- a/content/lighttable/undo-redo.md +++ b/content/lighttable/undo-redo.md @@ -6,8 +6,8 @@ weight: 30 author: "people" --- -Most changes made within the lighttable are recorded and can be reverted to a previous state.[^1] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. +Most changes made within the lighttable are recorded and can be reverted to a previous state.[^2] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. -[^1]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip. +[^2]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip. Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any). diff --git a/content/module-reference/utility-modules/shared/filmstrip.md b/content/module-reference/utility-modules/shared/filmstrip.md index e497482d04..589ada2296 100644 --- a/content/module-reference/utility-modules/shared/filmstrip.md +++ b/content/module-reference/utility-modules/shared/filmstrip.md @@ -12,13 +12,13 @@ The filmstrip can be used to quickly switch between images. The images shown are The filmstrip can be switched on and off using the shortcut Ctrl+F. The height of the filmstrip panel can be changed by clicking and dragging its top border. -Quickly navigate through the images in the filmstrip by scrolling with the mouse. Increase scroll speed with Shift+scroll. Change the height of the filmstrip with Ctrl+scroll or by clicking+dragging the top of the panel. In the darkroom you can change the photo currently being processed by clicking on another image in the filmstrip. +Quickly navigate through the images in the filmstrip by scrolling with the mouse. Increase scroll speed with Shift+scroll. Change the height of the filmstrip with Ctrl+scroll or by clicking+dragging the top of the panel. Change the _custom sort_ order of images by dragging and dropping thumbnails as described at [custom sort](../../../../lighttable/digital-asset-management/custom-sort.md). -In the darkroom, the image currently being processed is selected and highlighted. Click on or hover over an image on the filmstrip with your mouse to select it (in order to act on it with a keyboard shortcut) without changing the image being processed. Double-click on an image to open it for editing. +In the darkroom, the image currently being processed is selected and highlighted. Click on or hover over a different image on the filmstrip with your mouse in order to act on it with a keyboard shortcut _without changing the image being processed_. Double-click on an image to open it for editing. If you wish to select multiple images in the filmstrip, click to select the first image followed by either Ctrl+click to select or de-select further images, or Shift+click to select a range of images. -You may change the _custom sort_ order of images in the filmstrip by dragging and dropping thumbnails as described at [custom sort](../../../../lighttable/digital-asset-management/custom-sort.md). + The following shortcuts can be used to select images in the filmstrip: diff --git a/content/overview/user-interface/top-panel.md b/content/overview/user-interface/top-panel.md index bafc8c42df..330dfc01de 100644 --- a/content/overview/user-interface/top-panel.md +++ b/content/overview/user-interface/top-panel.md @@ -12,8 +12,11 @@ The top panel appears in all darktable views and provides access to common funct # On the left-hand-side -filter / sort -: Choose how to filter and sort the images. Criteria can be altered in the [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module or by clicking on the ![top-panel_filter-preferences icon](./top-panel/top-panel_filter-preferences.png#icon) icon. +![top-panel_filter-preferences icon](./top-panel/top-panel_filter-preferences.png#icon)filter +: Choose which of a [collection's](../../lighttable/digital-asset-management/collections/) images are displayed, making them available for different [views](../..//overview/user-interface/views/) or selection and [action](../../module-reference/utility-modules/lighttable/selected-image/). Criteria can be altered in the [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module or by clicking the icon. + +sort by +: Choose the property that orders the displayed [image sequence](../../lighttable/digital-asset-management/sequence ). ![top-panel_sort-order icon](./top-panel/top-panel_sort-order.png#icon) sort order : Switch the sort order (ascending / descending). From 49a604f9fc5cdfb7510b93924915adb8118d3f04 Mon Sep 17 00:00:00 2001 From: Bill Clay Date: Sun, 2 Feb 2025 08:55:54 +0100 Subject: [PATCH 3/3] revisions responding to first review; new "collection" definition clarification MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit reviewer issues: i1 spurious drags, especially on tablets i2 are drops on the source image harmless? mostly, but not if multi-image group involved. i3 nonspecific tag edit issue; not found; my tests show no such problem; deleted i4 mixed tags or tagged + untagged resequencing, need clarity collection definition revisions i5 Existing "collection" descriptions allow inference that collections may specify multiple image properties. Not so(?), at least in recent DT versions. I have made new clarity edits in a few places, one significant revision of old text, and one new "custom sort" caution. revisions to my inital pull request content 1.1.4, top panel, filter: one-word style edit 2.3, undo/redo: change footnote 2 to 1 (gratuitous uniqueness beyond section boundary?) 2.4.2 zoomable lighttable, hover: two-word clarity edit 2.5.1 collections (first modified in this commit): ¶1, one-word clarity edit (i5); ¶3 collection criterion; new footnote 1 (i4, i5) 2.5.6 image sequence: ¶6, typo corrected; ¶7 revise, single collection criterion (i5) 2.5.7 custom sort, cautions: new 3rd bullet item (i4); footnote 1 (i1, i4) which custom sort: minor clarity edits what to drag: new 3rd item (i1, i2); relocated 4th item, from former "corner cases" topic, 1st item suggested process: item 1, one-word clarity edit former "corner cases:" removed, content relocated or deleted. Note: 2.5.7, footnote 1 may be Too Much Information. Second and later sentences can be summarized: Depending on several factors, drag-and-drop will have no effect, image relocation to collection tail or head, partial success, and/or complete success. --- .../digital-asset-management/collections.md | 6 ++-- .../digital-asset-management/custom-sort.md | 31 ++++++++++--------- .../digital-asset-management/sequence.md | 4 +-- .../lighttable-modes/zoomable-lighttable.md | 2 +- content/lighttable/undo-redo.md | 4 +-- content/overview/user-interface/top-panel.md | 2 +- 6 files changed, 26 insertions(+), 23 deletions(-) diff --git a/content/lighttable/digital-asset-management/collections.md b/content/lighttable/digital-asset-management/collections.md index f667d71e29..15ff156632 100644 --- a/content/lighttable/digital-asset-management/collections.md +++ b/content/lighttable/digital-asset-management/collections.md @@ -6,10 +6,12 @@ weight: 20 author: "people" --- -A collection is a set of images matching a given selection criteria. +A collection is a set of images matching a given selection criterion. The most basic kind of collection is a film roll, which contains all of the images that have been imported from a specific folder on disk. Whenever you [import](../../module-reference/utility-modules/lighttable/import.md) images from the filesystem, those images are organized in a film roll whose name is derived from that of their parent folder. -You can easily construct other kinds of collection based on various image attributes (Exif data, filename, tags etc.) in the [collections](../../module-reference/utility-modules/shared/collections.md) module. Multiple criteria can be logically combined to narrow or extend your collection. +You can easily construct other kinds of collection based on one of many image attributes (Exif data, filename, tags, etc.) in the [collections](../../module-reference/utility-modules/shared/collections.md) module.[^1] The [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module sets selection and exclusion criteria for many attributes to refine the focus of darktable's display, processing, and export of a collection. darktable retains a list of the most recently used collections for quick access. These can be accessed from the [recent collections](../../module-reference/utility-modules/shared/recent-collections.md) module. + +[^1]: While collections are based on a single attribute, the attribute's selection criterion may be multi-valued (_i.e._, range, wild-card expression, or non-leaf hierarchy node). diff --git a/content/lighttable/digital-asset-management/custom-sort.md b/content/lighttable/digital-asset-management/custom-sort.md index 68576090e6..5e791e9ec6 100644 --- a/content/lighttable/digital-asset-management/custom-sort.md +++ b/content/lighttable/digital-asset-management/custom-sort.md @@ -5,7 +5,7 @@ weight: 80 author: "wbclay" --- -Setting _sort by_ > "custom sort" presents images in any sequence you define. Images are initally ordered by an image property (import order, image capture time, file name, etc.) but you can then incrementally alter any "custom sort" sequence by drag-and-drop as desired. Be careful: an erroneous drag-and-drop can easily ruin one or more painstakingly-created image sequences. +Setting _sort by_ > "custom sort" presents images in any sequence you define. Images are initally ordered by an image property (import order, image capture time, file name, etc.) but you can then incrementally alter "custom sort" sequences by drag-and-drop. Be careful: an erroneous drag-and-drop can easily ruin one or more painstakingly-created image sequences. ### cautions {#cautions} @@ -13,6 +13,10 @@ Setting _sort by_ > "custom sort" presents images in any sequence you define. Im - Drag-and-drop resequencing is __always__ enabled in lighttable filemanager and in the filmstrip, but any resulting __changes are invisible__ if _sort by_ > "custom sort" is not in effect. +- Do not use "custom sort" for tag-based collections that specify a wild-card ("*" or "%") expression.[^1] + +[^1]: When a wild-card tag expression does not resolve to a __single__ tag, then drag-and-drop operates on only the first matching tag's sequence. If that tag is attached to a source image, the image is resequenced. If the same tag is also attached to the target image, the drop occurs there; if not, resequenced images appear at the collection's "custom sort" tail or head. If the first matching tag is not attached to a source image, the image is not repositioned. Collections preference "tag case sensitivity" is relevant beyond case: "insensitive" treats "%" (but not "*") as a string-match wild card. The global sequence is not affected in any of these cases. + - Ensure any image you drag is __not selected__ unless you want to reposition the entire currently selected set. - Aim your "drops" accurately: verify the correct target is __highlighted__ before dropping! @@ -21,7 +25,7 @@ Setting _sort by_ > "custom sort" presents images in any sequence you define. Im ### _which_ custom sort sequence? -Collection type determines which [image sequence](../../lighttable/digital-asset-management/sequence.md) drag-and-drop changes. If the collection's primary selection criterion is _tag_, a __tag-based__ "custom sort" sequence is altered. Otherwise, the __global__ "custom sort" sequence is altered. Collection filters, if any, do not affect which sequence drag-and-drop changes. +Collection type determines which [image sequence](../../lighttable/digital-asset-management/sequence.md) drag-and-drop changes. If the collection's selection criterion is _tag_, a __tag-based__ "custom sort" sequence is altered. Otherwise, the __global__ "custom sort" sequence is altered. Collection filters (even if tag-based) do not influence which sequence drag-and-drop changes. When _sort by_ > "custom sort" is in effect, dragged-and-dropped images are immediately presented in their new tag-based or global "custom sort" sequence. @@ -29,21 +33,27 @@ When _sort by_ > "custom sort" is in effect, dragged-and-dropped images are imme While viewing a collection in filemanager or the filmstrip, you may drag any hovered-over (highlighted) image to any other image in the displayed collection. Empty space before, between, or after images is not a recognized drop target. -- You may relocate a single image (unselected or sole selection) or a selected set of images by dragging one of them to desired position as follows: +You may relocate a single image (unselected or sole selection) or a selected set of images by dragging one of them to the desired position as follows: - Drop on the image you want a dragged image or selected set to __precede__ when _sort order_ is __"ascending"__. - Drop on the image you want a dragged image or selected set to __follow__ when _sort order_ is __"descending"__. +- Abort an accidental drag by dropping the dragged image _outside_ of the thumbnail display. If all peripheral panels are hidden, then drop the dragged image on __itself__. If multiple images were selected, the entire selected set will be relocated to that spot. + +- If the "dropped on" image is subsequently resequenced, filtered out, or even deleted, the dropped image(s) remain where the "dropped on" image was located. + ### who's last? (or, in descending sort, first?) - An image dropped after the last image on lighttable is regarded as dropped __on the last image__, thus positioned before it. + - To change the last image in an "ascending" "custom sort" display, drop it on the existing last image, then drag-and-drop that last image on its intended replacement. + - If you expect to use a "descending" sort, do the opposite to change the first image. ### suggested process -1. If you intend to present a collection in more than one "custom sort" sequence or if some images in a collection are included in other collections to be displayed with a different "custom sort", then it is probably preferable define tag-based collections. +1. If you intend to present a collection in more than one "custom sort" sequence or if some images in a collection are included in other collections to be displayed with a different global "custom sort", then tag-based collections should be used. 2. For tag-based "custom sort" only: - Set _sort by_ to the image attribute and _sort order_ (ascending or descending) you want as your tag's initial sequence, @@ -51,21 +61,12 @@ While viewing a collection in filemanager or the filmstrip, you may drag any hov - in the right-hand panel at _tagging_, bottom half, add a new tag or click on an existing tag. - The tag is now attached to the selected images in the displayed sequence. Note the tag's increased image count. - Change _collections_ selection crierion to "tag" and choose the newly-applied tag. Note that the newly-tagged images are shown. + 3. Long-distance drags are difficult because neither _filemanager_ nor _filmstrip_ scroll while you drag. Try to fit drag sources and targets onto the same screen by maximizing the the window and scrolling the display. If that's not sufficient: - increase the number of images displayed (thus shrinking thumbnails) or - hide images between drag source and drop target using _collection filters_ (e.g., by ranges of "datetime captured" or "image id"). + 4. Rearrange the images as you desire: - __Clear any active selection__: _selection_ > _select none_. - Set _sort by_ > "custom sort" so you can verify your changes immediately. - Remember the __[cautions](#cautions)__ above as you drag-and-drop. - -### corner cases - -drop-target moves or vanishes -: Resequencing, filtering out, or even deleting a "dropped-on" image does _not_ resequence images that were dropped on it earlier. They remain where the "dropped on" image was previously located. - -mixed-up tags -: As of this writing, resequencing behavior of collections based on multiple tags or on a mix of tagged and untagged images is not clear. Use "custom sort" on such collections with caution pending further research. - -tag editing considered harmful -: A change request laments that editing tags regenerates the related "tagged image" database table in an unspecified order, possibly losing any previous "custom sort." diff --git a/content/lighttable/digital-asset-management/sequence.md b/content/lighttable/digital-asset-management/sequence.md index 2748aa474d..de1c1f0e26 100644 --- a/content/lighttable/digital-asset-management/sequence.md +++ b/content/lighttable/digital-asset-management/sequence.md @@ -19,8 +19,8 @@ There are two distinct "custom sort" sequencing regimes: When an image is imported into your darktable library, it is automatically positioned in the global sequence after all previously-imported images. A duplicated image is initially positioned in the global sequence immediately after its original, regardless of intervening image imports. -Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is attached. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its origanal's tags and is positioned within each as a newly-tagged image. +Tagged images are sequenced within each attached tag in the order that the tag is attached. Selected sets of images are tagged in order of the _sort by_ setting in effect at the moment the tag is attached. Newly-tagged images are initially positioned after all images previously associated with that tag. A duplicated image inherits all of its original's tags and is positioned within each as a newly-tagged image. -The __primary selection criterion__ of a collection determines which sequence drag-and-drop alters while working in lighttable filemanager or the filmstrip. If the primary collection criterion is "tag", drag-and-drop alters the chosen tag-based sequence(s). Otherwise, drag-and-drop alters the global sequence of all images in the library. +A collection's __selection criterion__ determines which sequence drag-and-drop alters while working in lighttable filemanager or the filmstrip. Drag-and-drop withn a tag-based collection alters a designated tag's sequence. Otherwise, drag-and-drop alters the global sequence of all images in the library. The next section, [custom sort](../../lighttable/digital-asset-management/custom-sort.md), suggests how to efficiently and safely use drag-and-drop image resequencing. __Note its [cautions](./custom-sort.md#cautions).__ diff --git a/content/lighttable/lighttable-modes/zoomable-lighttable.md b/content/lighttable/lighttable-modes/zoomable-lighttable.md index 251b5ae519..640e88480f 100644 --- a/content/lighttable/lighttable-modes/zoomable-lighttable.md +++ b/content/lighttable/lighttable-modes/zoomable-lighttable.md @@ -21,7 +21,7 @@ select : As with the filemanager mode, you can select the image under the pointer by clicking on its thumbnail or by pressing Enter. To select a range of images, click on the first image and then Shift+click on the last one. To add or remove images in a selection, Ctrl+click on a thumbnail or hover over a thumbnail and press Spacebar. hover -: Hovering over a thumbnail highlights and impicitly selects it for keyboard shortcuts as in filemanager mode. However, dragging moves the whole thumbnail display, so you cannot change images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order in this mode. +: Hovering over a thumbnail highlights and impicitly selects it for keyboard shortcuts as in filemanager mode. However, dragging pans the entire thumbnail display, so you cannot change images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order in this mode. --- **Hint:** you may find that image thumbnails are slow to load when zooming quickly through a large collection. One way to speed up the navigation is to generate a cache containing all the thumbnails using the [`darktable-generate-cache`](../../special-topics/program-invocation/darktable-generate-cache.md) command. diff --git a/content/lighttable/undo-redo.md b/content/lighttable/undo-redo.md index 7b20f8a091..405ca6d202 100644 --- a/content/lighttable/undo-redo.md +++ b/content/lighttable/undo-redo.md @@ -6,8 +6,8 @@ weight: 30 author: "people" --- -Most changes made within the lighttable are recorded and can be reverted to a previous state.[^2] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. +Most changes made within the lighttable are recorded and can be reverted to a previous state.[^1] This includes modifications to color labels, ratings, geo-localization, tags, metadata, orientation, copy/paste of history, image duplication, or application of a style. Note that the facility to undo/redo actions is unlimited in the number of steps while in the lighttable view, but it is reset each time you switch to a different view. -[^2]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip. +[^1]: "Undo" __cannot reverse__ changes made in images' [custom sort](../../lighttable/digital-asset-management/custom-sort.md) order by dragging-and-dropping thumbnails in lighttable filemanager and the filmstrip. Press Ctrl+Z to undo the last modification and Ctrl+Y to redo the last undone modification (if any). diff --git a/content/overview/user-interface/top-panel.md b/content/overview/user-interface/top-panel.md index 330dfc01de..fe2eb5a78c 100644 --- a/content/overview/user-interface/top-panel.md +++ b/content/overview/user-interface/top-panel.md @@ -13,7 +13,7 @@ The top panel appears in all darktable views and provides access to common funct # On the left-hand-side ![top-panel_filter-preferences icon](./top-panel/top-panel_filter-preferences.png#icon)filter -: Choose which of a [collection's](../../lighttable/digital-asset-management/collections/) images are displayed, making them available for different [views](../..//overview/user-interface/views/) or selection and [action](../../module-reference/utility-modules/lighttable/selected-image/). Criteria can be altered in the [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module or by clicking the icon. +: Choose which of a [collection's](../../lighttable/digital-asset-management/collections/) images are displayed, making them available to different [views](../..//overview/user-interface/views/) for selection and [action](../../module-reference/utility-modules/lighttable/selected-image/). Criteria can be altered in the [collection filters](../../module-reference/utility-modules/shared/collection-filters.md) module or by clicking the icon. sort by : Choose the property that orders the displayed [image sequence](../../lighttable/digital-asset-management/sequence ).