Add Framing Tool

[digitalcarp]

Framing Tool

Adds a framing/borders tool under the resize tool. Lightroom and darktable have similar functionality.

Plenty of people share images on platforms like Instagram. The platforms restrict image sizes and aspect ratios. This features allows you to keep your image's aspect ratio by adding a simple colored border. Users can have the tool downscale their images to fit within certain dimensions. This way the user can use RawTherapee's resizing method and post-resize sharpening tools rather than relying on the platform's algorithms.

The standard framing method can be used to add buffer areas for full-bleed printing (#6791).

It's easier to do batch processing for regular users when you don't need to use Gimp scripting or ImageMagick to add borders on multiple images.

UI

Processing Pipeline Changes

Framing resize operation does not perform resizing on an already resized image. Instead, if needed, the initial resize parameters are adjusted before performing the actual resize.

Post-resize sharpening will apply to the framing resized image. The border will not be in the image data yet, so sharpening will not be affected by the framing tool.

The borders are drawn after the image is in the output colorspace (i.e. after lab2RgbOut()).

User Documentation

The framing tool adds a variable-sized border to your output image. It works in tandem with the Resize tool to downscale/upscale your image. Post-resize sharpening may be applied to the image as well.

Tool Settings

Method

• Standard - Add a border around the image. The image's size is preserved when adding the border.
• Fixed Frame - Fills a fixed-size frame with the border and places the image in the center of the frame. The image may be shrunk to fit the fixed frame dimensions and any border sizing requirements.
• Bounding Box - Add a border around the image. If the framed dimensions including image and borders exceeds the bounding box, the image (measured including borders) will be shrunk to fit the bounding box.

Aspect Ratio

Specify the aspect ratio of the frame in Standard and Bounding Box framing methods. If the border sizing constraint is too small to meet the aspect ratio (i.e image would be cut off), then the minimum borders needed to meet the aspect ratio is used. The aspect ratio of the post-Resize tool image can be used by selecting the "As Image" option.

Orientation

Specify the orientation of the frame aspect ratio. The orientation of the post-Resize tool image can be used by selecting the "As Image" option.

Framed Width/Height

Specify the bounding box of the frame in pixels for the Bounding Box framing method. Specify the fixed frame dimensions in pixels for the Fixed Frame method.

Allow Upscaling to Frame

In the Fixed Frame and Bounding Box framing methods, if the image is smaller than the maximum allowed size, upscale the image to its max size.

Sizing Method

Determines how the size of the border is calculated. The border sizing values refer to the size on one side of the image. For example, a 10px border will add 20px the the total height of your image after framing.

Relative

Specify the border size based on a percentage of the chosen.

Basis

• Auto - Choose whichever side is the limiting side for small border sizes based on aspect ratios.
• Width/Height - Choose the width/height as the reference length.
• Long/Short Edge - Choose the longer/shorter edge as the reference length.

If the basis side border is too small for the requested aspect ratio, the minimum possible value will be used.

Limit Minimum Size

If enabled, ensures a minimum border size for horizontal/vertical borders as specified by the Minimum Width/Height inputs.

Uniform Relative

Adds a uniform border that is the same size horizontally and vertically. The border size is determined based on the image size as in the Relative sizing method. The minimum width and height are automatically updated to match each other.

Absolute

Specify the fixed border size in pixels using the Border Width/Height inputs. The aspect ratio and orientation options are ignored in this mode.

Border Color

Choose the 16-bit RGB values of the border.

Limitations

• Downscaling limit is 32x32px (as in resize tool)
  • If the crop size is under 32x32, no downscaling is performed even if needed to fit frame.
  • Usually hit if the border size requirements are too high
• Upscaling limit is 16x crop size (as in resize tool)

Example Output

Framing Method: Standard
Sizing: Relative @ Auto 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 4800x3840
Adjusted Dimensions: 4800x3840
Output Dimensions: 5760x4608

Framing Method: Standard
Sizing: Relative @ Auto 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 500x400
Output Dimensions: 600x480

Framing Method: Standard (4:5 Portrait)
Sizing: Relative @ Height 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 500x400
Output Dimensions: 500x625

Framing Method: Standard (4:5 Portrait)
Sizing: Relative @ Height 10%
Min Size: W=200 H=100
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 500x400
Output Dimensions: 900x1125

Framing Method: Standard
Sizing: Absolute @ W=100 H=200
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 500x400
Output Dimensions: 700x800

Framing Method: Fixed Frame (400x500)
Sizing: Relative @ Auto 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 333x267
Output Dimensions: 400x500

Framing Method: Bounding Box (500x400) (4:5 Portrait)
Sizing: Relative @ Auto 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 267x213
Output Dimensions: 320x400

Framing Method: Bounding Box (800x1000) (4:5 Landscape)
Sizing: Relative @ Auto 10%
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 500x400
Output Dimensions: 600x480

Framing Method: Bounding Box (800x1000) (4:5 Landscape)
Sizing: Relative @ Auto 10%
Allow Upscaling To Frame: Yes
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 667x533
Output Dimensions: 800x640

Framing Method: Fixed Frame (80x100)
Sizing: Absolute @ W=100 H=200
Crop Dimensions: 4800x3840
Resize Dimensions: 500x400
Adjusted Dimensions: 40x32
Output Dimensions: 80x100

[Lawrence37]

Thank you very much for working on this!

I briefly tried the framing feature. I have some feedback for you to consider while I continue testing.

1. The resize is applied twice while the image area and frame size are correct. For example, with a starting image of size 1000x1000 pixels, a scale factor of 0.50, and an absolute border size of 100 pixels, the resulting image has a total size of 700x700 pixels. The perimeter consists of a 100 pixel wide border and the interior image area is 500x500 pixels. This part is correct. However, the photo is 250x250 pixels in the upper-left corner of the image area. The rest is filled with black.
2. A border/frame tool is a frequently-requested feature. In the current state, the frame tool is not easily discoverable because it is located within the resize tool. This can be improved by either making the framing tool stand-alone in the GUI or by renaming the resize tool to something like "Resize & Framing".
3. In the absence of a way to see the border in the editor preview, it is hard to visualize the border color. Implementing the editor preview is complex, so I don't expect it to happen soon. A color indicator in the framing tool could be enough for now.
4. Some, and maybe most, users will find it strange that the color values range from 0 to 65535. Perhaps the GUI should present it as a percentage (i.e [0-100]) or with the more familiar [0-255] range?
5. The documentation should say that the border color values are in linear space with the primaries of the output profile (at least, that is what I observed). I welcome any discussion about what color space to use. The primaries of the output profile makes sense to me. I'm not so sure about using linear space instead of the output profile's TRC.
6. It would be nice if there was an option to apply a uniform border relative to the image size. For example, an image that is 4000x3000 pixels with a border that is 0.05 times the long edge would result in a border that is 200 pixels thick on all sides. This would be great for default processing profiles because the cropped and scaled image dimensions are not known in advanced and one might want a consistent look.
7. The equality operator for ProcParams doesn't consider the framing parameters. This is evident when using the external editor feature. After adjusting the framing parameters and resending to the external editor, the image is the same. That's because the image is not regenerated if the ProcParams is equal the the previous one.

[Lawrence37]

I shared this pull request in the forum because I think it deserves exposure (no pun intended). https://discuss.pixls.us/t/border-framing-tool-in-development/46636

[digitalcarp]

1. Fixed
2. Renamed to "Resize & Framing" as framing interacts with resize and post-resize sharpening
3. Added a color indicator on the bottom
4. Changed to [0, 255] range
5. I'm not an expert on color theory so you'll have to provide guidance for any changes you'd like. I'm happy to leave it as is and adjust in a future PR if required.
6. Implemented as "Uniform Relative". Updating PR user doc section to reflect.
7. Fixed

Examples for 6)

Framing Method: Standard
Sizing: Relative @ Auto 10%
Crop Dimensions: 1250x1000
Resize Dimensions: 625x500
Adjusted Dimensions: 625x500
Output Dimensions: 750x600

Framing Method: Standard
Sizing: Uniform Relative @ Auto 10%
Crop Dimensions: 1250x1000
Resize Dimensions: 625x500
Adjusted Dimensions: 625x500
Output Dimensions: 750x625

[Lawrence37]

Nice! Let me review.

[Lawrence37]

The fixes and improvements are working as expected. There are a few more issues I found, listed here with the associated test case:

1. With a 3:2 image, standard method, 4:3 aspect ratio (as image), relative sizing to the short edge, 0.05 size: There is no border.
2. With standard method, relative sizing, minimum width/height of 1 or 2: The minimum is not enforced.
3. With standard method, uniform relative sizing: The basis has no effect. The size is always relative to the image width.
4. With a 3:2 image, 200x200 bounding box, uniform relative sizing to the short edge, 0.05 size: There is no left/right border even if a minimum width is set.
5. With a 3:2 image, 200x200 bounding box, uniform relative sizing to the short edge, 0.5 size: The total image size is 96x80, which is too small.
6. With a 3:2 image, 200x200 fixed frame, uniform relative sizing, auto basis, 0.05 size: There is no left/right border. With a 2:3 image, there is no top/bottom border.

Regarding the color, the indicator works fine if the output and display profiles are sRGB. It will need to be more sophisticated to handle other profiles. I can help with that.

[digitalcarp]

Thanks for testing! I've fixed all 6 issues. To make testing a little less click intensive, I've uploaded some partial .pp3 files for CLI use. Please find them here. They are numbered by order of appearance in this PR.

There is a utility bash script that runs them all. Please read the script for how to use/internet safety.

I'll do some more testing over the week.