Skip to content

Improve (documentation of) Framing module #21191

@NKlug

Description

@NKlug

Is your feature request related to a problem? Please describe.

I am struggling to use the framing module properly.
My workflow is the following: The image in darktable has size $(w_1, h_1)$ and let's say aspect $a_1 = \frac{h_1}{w_1}$. My print should have size $(w_2, h_2)$ and aspect $a_2 = \frac{h_2}{w_2}$.
I want to add framing accordingly, but I am not sure which values to enter in the framing module.

As an example, let's say $(w_1, h_1) = (1000\mathrm{px}, 1500\mathrm{px})$ and thus $a_1 = \frac{3}{2}$ and $a_2 = \frac{4}{3}$ with $(w_2, h_2) = (1250\mathrm{px}, 1667\mathrm{px})$.
I enter aspect 4:3. Now I get the following results:

  • basis width, auto, shorter, border size 20%: expected width: $\frac{w_1}{1-0.2} = 1250\mathrm{px}$. Actual width $1313\mathrm{px}$. not as expected ❌
  • basis height, longer, border size 10% : expected height: $\frac{h_1}{1-0.1} = 1667\mathrm{px}$. Actual height $1667\mathrm{px}$. as expected ✔️

There was also confusion about frame sizes in #20296 .

Describe the solution you'd like
The size of the final image and the frame size should be consistent and predictable. The user should not have to manually check whether the resulting frame sizes are actually the ones that were expected.

To achieve this, I suggest the following:

  1. Improve documentation by adding the formulas used to calculate the frame size (horizontal and vertical) based on the selected options. I only partially figured them out by trial and error.
  2. Add a short paragraph about how to obtain correct frames for the workflow described above.
  3. Add documentation about the meaning of basis. What does auto, width, height, longer, shorter do exactly?
  4. Reduce complexity by reducing the number of options for basis. Maybe two (width, height) are sufficient?
  5. The current formula to compute the frame size $x$ for the above use case is or at least should be, as far as I can see, $x = 1 - \frac{w_1}{w_2} = \frac{w_2 - w_1}{w_2} .$
    For this specific use case it would be more convenient to use $x = \frac{w_2}{w_1}.$
    Evaluate whether it makes sense to use the second formula. There might be use cases that I am unaware of where the current formula is more convenient , though.

Alternatives
None
Additional context
None

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions