dtourolle
c2cfacd7d3
denoise.md §15: why Best became one network, how it compares with the mixture and Medium on real photographs and the chart, the candidates that fell short, the file names, the saved-edit numbering, and the timings on the 3050 -- 0.51-0.54 s whole-frame, 0.95 s in tiles, against 2.60 s for the mixture in tiles. The manual lists Bilinear, Fast and Best, says an edit made with Medium opens with Best, and gives the new time; Medium's close-up goes.
515 lines
26 KiB
Markdown
515 lines
26 KiB
Markdown
# DarkRoom, shown
|
||
|
||
A tour of what the application does, one picture per thing. Every image on
|
||
this page was captured from the desktop build driving itself — nothing is a
|
||
mock-up, and nothing has been retouched outside DarkRoom. Where a feature is
|
||
better seen moving, it moves.
|
||
|
||
The requirements behind each feature are in [requirements.md](../dev/requirements.md);
|
||
the reasoning is in the design documents linked from each section. This page
|
||
is only about what you see.
|
||
|
||
The photographs are the author's. None show a person.
|
||
|
||
## Opening a library
|
||
|
||
DarkRoom opens on a library: a folder on this machine, a folder a sync
|
||
client keeps, or a Nextcloud account. A folder needs no password and uploads
|
||
nothing. `Choose folder…` opens your desktop's own folder dialogue, which can
|
||
make a new folder too; the folder used last stays on the screen with
|
||
`Open folder` beside it, and `Choose another…` in place of `Choose folder…`.
|
||
On a Nextcloud account the library folder is chosen in a browser of the
|
||
server, whose `New folder` makes one there. (The browser is not pictured:
|
||
these recordings have no server behind them. Nor is the folder dialogue,
|
||
which is your desktop's rather than DarkRoom's.)
|
||
|
||
|
||
|
||
Once a folder is named, it is the library — you are not asked for it again,
|
||
and `Open library` opens it whole. `Subfolder…` narrows the scan to part of
|
||
it. The formats ticked are what the scan looks for; RAW is on and JPEG off
|
||
by default, because a RAW editor's sensible default is the file the camera
|
||
wrote first. `Change library`, at the foot of the sidebar, comes back here.
|
||
|
||
|
||
|
||
## The library
|
||
|
||
|
||
|
||
Photographs are ordered by capture time, with a month heading where each
|
||
begins. The strip on the left is the timeline — drag it to jump to a year.
|
||
The bar above the grid filters by rating, flag, colour label and where the
|
||
file is (on this device, or only on the server).
|
||
|
||
### Rating and flagging
|
||
|
||
Hover a cell and the stars appear; click one. The filter chips above the grid
|
||
count what each rating holds, and clicking `3+` shows only those. From the
|
||
keyboard, `0` to `5` set the stars on the photograph under the pointer or on
|
||
the selection; `P` picks, `X` rejects and `U` takes the flag off, and `Flag`
|
||
on the selection bar does the same with the pointer. In
|
||
develop the same keys judge the open photograph and stay on it, and the top
|
||
bar carries its stars and `Pick` and `Reject`; the roll marks each frame's
|
||
flag and stars.
|
||
|
||
|
||
|
||
Colour labels work as Lightroom's do: `6` red, `7` yellow, `8` green, `9`
|
||
blue, on the photograph under the pointer or on the selection, and the same
|
||
key again takes the label off. `Label` on the selection bar offers all five,
|
||
purple included, and `None`. Each label is drawn with its initial on it, so
|
||
it reads without telling the colours apart, and the filter bar has a chip for
|
||
each. In develop, the top bar names the open photograph's label and sets it,
|
||
and the same keys work there.
|
||
|
||
|
||
|
||
### Getting about
|
||
|
||
Drag the timeline to scrub through years; Ctrl and the wheel resize the
|
||
thumbnails. On a desktop a scrollbar beside the grid says how far through the
|
||
library the view is — drag its thumb, or click the track to move a page — and
|
||
the sidebar, the develop column and Settings have one too whenever they run
|
||
past the window. On a tablet they scroll by flick alone, and a thin line at
|
||
the right-hand edge shows where the view is while it moves, fading once it
|
||
stops; it is only a picture, and a flick that starts on it scrolls the list.
|
||
|
||
A panorama gets a wider cell: about twice as wide as it is tall and it spans
|
||
two columns, then three, then four for the widest — whichever leaves the least
|
||
of the cell empty — with a thumbnail made for that width. One that would not
|
||
fit in what is left of a row starts the next, so the grid still reads in the
|
||
order the photographs were taken; the arrows walk it in that order, and up and
|
||
down go to whatever is above or below. On a tablet, or with too few columns to
|
||
put it beside anything, a panorama takes the whole row.
|
||
|
||
`Help` in the header, or `F1`, opens the controls and shortcuts: every key and
|
||
gesture, screen by screen, with `See it` beside those this page shows, and
|
||
`Manual` to open this page. In develop it is the `?` beside `Settings`.
|
||
|
||
|
||
|
||
|
||
|
||
### Selecting several
|
||
|
||
`Select` in the header — or Ctrl-click — starts a selection. Shift-click picks
|
||
a range. The bar at the foot of the grid is everything a selection can be done
|
||
to: collections, keywords, presets, export, and merging to a panorama.
|
||
|
||
|
||
|
||
`Keywords` on that bar opens a sheet; type a word and press return, and it
|
||
is on every photograph selected. The list below the field is every keyword
|
||
the library has, ticked where the selection carries it.
|
||
|
||
|
||
|
||
### Collections
|
||
|
||
`+` at the head of the sidebar makes one. Drag a photograph — or the whole
|
||
selection — onto its row to file it there; click the row to see it. A
|
||
photograph can be in several, and the badge on its cell counts them.
|
||
|
||
|
||
|
||
Collections nest. Drag one onto another to put it inside; `+` with a
|
||
collection selected — or `New collection inside` from its menu — makes a
|
||
child. A parent shows everything its children hold, and its count says so.
|
||
Right-click a row (hold it, on a tablet) for the menu: rename, nest,
|
||
move back to the top level, keep it offline, delete.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### Bursts
|
||
|
||
Frames taken a moment apart that look alike fold into one cell, with a badge
|
||
counting them. Click the badge — tap it, on a tablet — to open the burst in
|
||
the grid, and again to fold it back. A folded burst shows its earliest frame;
|
||
to have it show another, open it and click the ring on the frame you want.
|
||
|
||
With faces indexed, narrowing the grid to a person puts `Eyes open` beside
|
||
their name on the filter bar, which leaves out the frames where they blinked.
|
||
|
||
### Duplicate originals
|
||
|
||
A library put together by hand often holds the same RAW more than once — a
|
||
dated folder, a `bck` folder beside it, a renamed copy another program
|
||
exported. When the catalog finds files with the same camera, capture time
|
||
and size in more than one place, `Duplicate originals` appears under the
|
||
trash in the sidebar with how many there are; Settings offers the same page
|
||
beside the other whole-library passes.
|
||
|
||
The page lists each group with its picture and its paths. One copy is
|
||
marked `Stays`: the one outside a folder named like a backup (`bck`,
|
||
`backup`, `copy`, `old`…), then the one still named the way the camera named
|
||
it (`_MG_4623`, `IMG_0001`, `DSC_0042`), then the one catalogued first. Tap
|
||
another path to keep that copy instead, and untick `Include` to leave a
|
||
group alone.
|
||
|
||
Nothing moves until `Check` has read the first and last megabyte of every
|
||
copy and each copy's sidecar. A group whose files differ, or whose copies
|
||
carry two different edits, is marked skipped and says why — two edits of
|
||
one frame are kept for virtual copies. What the check reads is kept, so a
|
||
second visit costs nothing. The line under each group says what the copy
|
||
that stays will gain: the highest rating, every keyword and collection, a
|
||
flag or label the copies agree on, faces and the names on them, and the
|
||
edit if only a copy had one. Where the copies disagree on a flag or a
|
||
label, the one that stays keeps its own and the line says so.
|
||
|
||
|
||
|
||
`Move N copies to trash` does it, one group at a time: each group is merged
|
||
and its spare copies moved together, or not at all. The copies go to the
|
||
trash, not away — select them in the trash view and `Restore` puts them
|
||
back where they were.
|
||
|
||
## Developing a photograph
|
||
|
||
Click a thumbnail to open it. The column on the right is every adjustment;
|
||
the strip at its head narrows it to one group.
|
||
|
||
|
||
|
||
|
||
|
||
### Light
|
||
|
||
Exposure, contrast, highlights, shadows, blacks, whites and a tone curve.
|
||
Hold `Before` to see the photograph as it was.
|
||
|
||
|
||
|
||
`Tone Mapping`, last in the group, is how the scene is fitted onto the
|
||
screen, and it runs after every other adjustment. `White Point` says how many
|
||
stops above middle grey reach white — raise it to bring a bright sky back
|
||
from white, lower it for a brighter, punchier picture — and `Contrast` sets
|
||
the slope of the curve between. Every adjustment above it works on the scene
|
||
as the camera recorded it, highlights beyond white included, so pulling the
|
||
highlights recovers what the sensor caught rather than what the screen could
|
||
show. A JPEG has been fitted to a screen already, by the camera, so on a
|
||
JPEG these two do nothing.
|
||
|
||
|
||
|
||
### Looking closer
|
||
|
||
Double-click for 1:1; drag to move about; double-click again to fit. The
|
||
wheel zooms to any amount in between. Past 1:1 the file's own pixels are
|
||
drawn as hard-edged blocks rather than smoothed, so what you see is what
|
||
the sensor recorded.
|
||
|
||
|
||
|
||
### AI denoise
|
||
|
||
How every raw is developed. `AI Denoise`, at the top of the Adjust panel,
|
||
replaces how the camera's raw data is turned into colour: a network trained
|
||
on this library's own photographs removes the noise and the blotches of
|
||
colour that come with it, while keeping the fine detail. Look at it at
|
||
1:1, where noise lives.
|
||
|
||
`Method` chooses how:
|
||
|
||
- `Best`, the default: clean skies and sharp lettering, edges kept as
|
||
crisp as the camera recorded them.
|
||
- `Fast`: a smaller network, taught the same way. Visibly noisier at very
|
||
high ISO than `Best`, but still far cleaner than none, and quicker.
|
||
- `Bilinear`: the camera's ordinary conversion, noise and all.
|
||
|
||
A photograph last edited with `Medium`, which earlier versions offered,
|
||
opens with `Best`.
|
||
|
||
The photograph shows the camera's ordinary conversion while the network
|
||
works, with its progress in the bar at the top, and changes when it is
|
||
done — on a laptop's graphics card, about a second for a 20-megapixel
|
||
photograph with `Best`, reading the file included; longer on a processor
|
||
alone or on the tablet. After installing, the graphics card spends up to a
|
||
quarter of an hour preparing each network, once, in the background; the
|
||
photographs developed meanwhile take a little longer. The result is kept, so a photograph opened again,
|
||
or exported, does not wait a second time, and switching back to a method
|
||
already used is quick.
|
||
`Strength` eases it off: below 100 % it puts back some of what was removed,
|
||
as grain without colour, for a picture that does not look too smooth.
|
||
|
||
The lamp and railing of a night frame at ISO 8000, at 1:1, by each method:
|
||
|
||
| Bilinear | Fast |
|
||
|---|---|
|
||
|  |  |
|
||
| **Best** | |
|
||
|  | |
|
||
|
||
It works on raw files from any camera with the usual colour pattern of
|
||
red, green and blue squares — not on JPEGs, and not yet on Fujifilm's
|
||
X-Trans. How noisy the camera is at each ISO was measured for the Canon
|
||
EOS 6D; for other cameras it is read from a DNG's own figures or
|
||
estimated from the photograph, and the finished job in the activity list
|
||
says which. An export uses
|
||
the method the photograph has.
|
||
|
||
### Moving between photographs
|
||
|
||
The roll along the foot of the canvas holds the photographs the grid was
|
||
showing; click one to open it. The right arrow, `D` or space opens the next,
|
||
and the left arrow or `A` the one before; held down, they go on past the
|
||
stretch the roll has loaded, through everything the grid would show. The
|
||
edit on screen is saved on the way, so stepping along a shoot loses nothing.
|
||
|
||
On a Nextcloud library a photograph may not be on this device yet. Its
|
||
thumbnail from the grid stands in at once; if the original has to come down,
|
||
the thumbnail dims under *Not on this device yet*, with how far the download
|
||
has got — `Downloading — 12.4 of 38.0 MB` — and a bar, and the photograph
|
||
opens when it lands. Step on before then and the one you step to is the one
|
||
that opens: a download that arrives late is kept for later and never takes
|
||
the place of the photograph whose name is showing. (Not pictured: a folder
|
||
library, which these recordings use, never has a photograph to wait for.)
|
||
|
||
### White balance from the photograph
|
||
|
||
Press `pick` in the White Balance group, then click something neutral —
|
||
a white wall, a grey card, the air conditioner here. The picker sets the
|
||
sliders from the photograph, not from where they were: below, the frame
|
||
is dragged cold first and one click puts it right. A blown highlight is
|
||
refused, since a clipped pixel has no colour left to balance.
|
||
|
||
|
||
|
||
### Composing
|
||
|
||
Crop by dragging the frame's corners, straighten with the slider, lock a
|
||
ratio from the chips. `Done composing` returns to the photograph.
|
||
|
||
|
||
|
||
`Vertical` and `Horizontal`, under `Straighten`, correct the lines that
|
||
converge when the camera is tilted up at a building; the crop refits to
|
||
what is left.
|
||
|
||
|
||
|
||
A crop that leaves a mask wholly outside the frame says so, and offers to
|
||
take the crop back or keep it.
|
||
|
||
|
||
|
||
### Local adjustments
|
||
|
||
`Local` in the rail turns the column into a mask stack. `Find subjects` runs a
|
||
segmentation model over the photograph; what it recognises appears as a list
|
||
of categories with how much of the frame each covers. Click one and it is a
|
||
mask — then every slider below edits only that region. A mask's slider adds to
|
||
the photograph's own rather than repeating it: contrast −20 in the mask over
|
||
−30 on the whole frame is −50 there, and +30 in the mask cancels the frame's
|
||
−30 inside it.
|
||
|
||
|
||
|
||
|
||
|
||
A mask is a stack of parts. Paint into it, subtract a gradient from it, grow
|
||
or shrink its edge, choose how it falls off. `Show masks as` draws the mask
|
||
tinted, as alpha, or as an outline; the eye on its row switches it off.
|
||
|
||
|
||
|
||
Linear and radial gradients, a tone range and a colour range are the other
|
||
ways to make one; each can be combined with any other. `∩ Intersect` keeps
|
||
only where the new part and the mask agree: below, a gradient over the
|
||
lower half, then two strokes that survive only where the gradient is.
|
||
|
||
|
||
|
||
### Repair
|
||
|
||
`Repair` in the rail: click a mark and it is covered from a source DarkRoom
|
||
chooses beside it. Drag either circle to move it; the size, feather and
|
||
opacity are in the panel. Heal blends; clone copies.
|
||
|
||
|
||
|
||
### Film
|
||
|
||
The `Film` chooser at the head of Adjust applies a spectral simulation of a
|
||
named stock; below it, the print exposure and push controls a film has and a
|
||
sensor does not. A stock takes the place of `Tone Mapping`: it is the last
|
||
thing that happens to the picture, so every other adjustment decides the
|
||
exposure the negative receives. The list opens over the column and scrolls on its own — by
|
||
wheel, drag or flick, or with `Up`, `Down` and `Enter` — down to the
|
||
black-and-white stocks at its end.
|
||
|
||
|
||
|
||
The film's sliders work on a mask as they do on the whole photograph, the way
|
||
a printer dodges and burns: in a layer, `Print Exposure` darkens or lightens
|
||
that region of the print, `Push` develops it further, and the stock stays the
|
||
one the photograph was made on. Where layers overlap, the photograph takes the
|
||
average of what they ask for. Below, a negative stock on an alpine frame, then
|
||
a gradient over the sky whose `Print Exposure` burns it in.
|
||
|
||
|
||
|
||
### History, snapshots, presets
|
||
|
||
Every change is a step; `Undo` and the History panel walk them. `Snapshot`
|
||
keeps the current state under a name. `Presets`, at the foot of the tool
|
||
rail on the left, opens a menu of presets beside the rail, over the photograph, filed in
|
||
folders that start closed: your own under `Yours`, then the ones DarkRoom
|
||
ships — `Essentials`, `Skies`, and `Film`, which holds `Colour`, `Cinema`
|
||
and `Black and white`, one measured stock each. Choosing a folder opens it;
|
||
choosing a preset applies it. The menu's last row, `Save or manage…`, opens
|
||
the presets sheet, which lists the same folders and saves the settings to
|
||
apply elsewhere, renames and deletes them, and imports Lightroom presets —
|
||
`Folder…` for a folder of them, `.xmp file…` for one.
|
||
|
||
A `/` in a name files the preset: `Portraits/Warm skin` is `Warm skin` in a
|
||
`Portraits` folder under `Yours`, and renaming it is how it moves. An
|
||
imported Lightroom folder keeps its groups the same way.
|
||
|
||
A shipped preset is a look: it changes what it names and leaves the
|
||
photograph's own corrections alone, as an imported Lightroom preset does.
|
||
Saving under a shipped preset's name makes your version the one that name
|
||
applies, marked *changed*; `Revert` brings the shipped one back, and renaming
|
||
yours makes it one of your own. A film preset carries its stock: choosing one
|
||
sets the `Film` chooser and leaves the rest of the edit where it was.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
### Copying settings
|
||
|
||
`Copy` in the top bar, or Ctrl+C, takes this photograph's settings; `Paste`,
|
||
or Ctrl+V, puts them on another, and says what it would paste — how many
|
||
adjustments, and whether the crop comes too. In the grid, `Paste to N` on the
|
||
selection bar pastes onto every photograph selected. Which kinds of edit a
|
||
copy carries is chosen in the presets sheet, or with Ctrl+Shift+C: a look carried
|
||
across a shoot usually leaves each frame's own crop alone.
|
||
|
||
## Merging a panorama
|
||
|
||
Select the frames, then `Merge to panorama` from the selection bar. The
|
||
frames are read, aligned, and drawn on the suggested projection with each one
|
||
outlined where it landed — twelve hand-held portrait frames across an alpine
|
||
valley, here. Change the projection (a 150° sweep on a flat perspective is
|
||
what the middle of the film shows, and why cylindrical is suggested), ask for
|
||
the border to be filled rather than cropped, then `Merge`. The composite is
|
||
written beside its sources as a DNG and is in the grid the moment it is
|
||
written — in a wide cell beside its frames, placed by when they were taken —
|
||
with the merge as the first step in its history. Its thumbnail is made during
|
||
the merge, from the finished picture, as develop will show it when you open
|
||
it; on a server library it is in the grid while the file is still uploading.
|
||
A second merge of the same frames is named `-pano-2`, never written over the
|
||
first.
|
||
|
||
Each frame has a box in the `Frames` list. Untick one to leave it out, and
|
||
the rest are aligned again at once, without reading the frames again; tick
|
||
it to bring it back. A frame that cannot be placed is named there with why,
|
||
and `Merge` stays off until it is unticked. Blown sky stays white in the
|
||
preview and in the composite.
|
||
|
||
A panorama is usually far wider than a graphics card can draw in one piece.
|
||
It opens in develop all the same, on a reduced copy that is drawn from the
|
||
full resolution wherever you zoom in, and it exports at full size. The same
|
||
goes for a panorama Lightroom stitched and saved as a DNG.
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
## Export
|
||
|
||
`Export` in the develop header, or `Export N` from a selection. Format,
|
||
size, colour space, sharpening and naming are in Settings, and apply to every
|
||
export until changed. Where the file goes is an album.
|
||
|
||
An album is a folder exports go to, listed under **Albums** in the sidebar,
|
||
below the collections. Press `+` there, or `New album…` in the export sheet
|
||
(`Ctrl+E`), name it, and choose its folder: on this device, in the system's
|
||
folder dialogue (on the tablet, Android's folder picker), or on the server,
|
||
in a browser that can make a folder as well as open one. Not inside the
|
||
library — a JPEG exported there would come back from the next scan as a
|
||
photograph of its own, and the browser says so rather than letting you.
|
||
|
||
|
||
|
||
The folder holds only the exported files. The album remembers which
|
||
photograph each came from, so selecting it in the sidebar shows the
|
||
originals behind its JPEGs — edit one and export it again. Albums reach your
|
||
other devices as collections do; a folder on this device does not, so an
|
||
album made on the desktop asks the tablet for a folder of its own.
|
||
Right-click an album, double-click it or press the arrow on its row to
|
||
rename it, give it another folder or delete it; deleting an album leaves
|
||
its files where they are.
|
||
|
||
|
||
|
||
|
||
|
||
An export with no album chosen is refused, and the header says so. With one
|
||
chosen, the buttons name it: `Export to Exports` in develop, `Export 4 to
|
||
Exports` on the selection bar.
|
||
|
||
|
||
|
||
## Settings
|
||
|
||
|
||
|
||
Background activity with progress, thumbnail and face indexing, how many
|
||
duplicate originals the library holds and the way to their review, storage
|
||
on this device, display and colour, export defaults, what is written to XMP
|
||
sidecars, the manual, and a diagnostics bundle for a bug report.
|
||
|
||
## People
|
||
|
||
Face detection and identity run over the library and group faces by person;
|
||
the `Identity` page is where suggestions are confirmed, rejected and split,
|
||
and `People` on the filter bar narrows the grid to someone. Not pictured
|
||
here, for the obvious reason — [faces.md](../dev/faces.md) has the design.
|
||
|
||
## Where things are written down
|
||
|
||
| Feature | Design |
|
||
|---|---|
|
||
| Local masks and segmentation | [segmentation.md](../dev/segmentation.md), [mask-editing.md](../dev/mask-editing.md) |
|
||
| Repair | [spot-removal.md](../dev/spot-removal.md) |
|
||
| Panorama | [panorama.md](../dev/panorama.md) |
|
||
| Faces and identity | [faces.md](../dev/faces.md) |
|
||
| Gestures, generated from the code | [gestures.md](../gestures.md) |
|
||
| Navigation and layout | [ui-navigation.md](../dev/ui-navigation.md) |
|
||
| Sync and storage | [storage.md](../dev/storage.md) |
|
||
|
||
## How this page is made
|
||
|
||
[`tools/manual/`](../../tools/manual/README.md) drives the desktop build on
|
||
a private X server and records each scene; `record.sh <library>` re-makes
|
||
every picture here. Run it after a change to the interface and commit what
|
||
changed. The pictures are in LFS.
|
||
|
||
The application carries this page. `cargo run -p traceability -- manual`
|
||
renders it to `index.html` beside it, which the packages install with the
|
||
pictures and the app opens from Help, from Settings, and from the "See it"
|
||
link beside a gesture on the help sheet. CI fails when the two differ.
|
||
|
||
Making it the first time turned up nine faults, each fixed in its own
|
||
commit before the pictures were taken: the folder picker could not choose
|
||
the top level, month headings overprinted each other, a category mask
|
||
widened the column off the window, the mask tint outlived its mode, the
|
||
first sync uploaded an empty thumbnail shard, a merge that ran out of GPU
|
||
memory left the page on Stop for ever, the export settings promised to ask
|
||
for a folder and did not, the keyword sheet sent its keys to the grid, and
|
||
an empty trash told you to check your library folder.
|