Differences

This shows you the differences between two versions of the page.

--- rotation_settings [2026/03/21 10:11] – created - external edit 127.0.0.1
+++ rotation_settings [2026/10/20 18:18] (current) – Documentation: Preview quality filter, thresholds, manual test and logs admin
@@ Line 121: / Line 121: @@
+===== Preview quality filter =====
+When generating thumbs from a video, some frames may be almost black, white or heavily blurred. **Preview quality filter** automatically skips these obvious defects during import.
+The options are in **Rotation - Settings - Preview quality filter**. **Enable preview quality filter** defaults to **Off**. The checks require **Image Lib = ImageMagick** and a correct **Path to IM**. They are skipped with GD. Processing runs on the CPU; no GPU or external service is needed.
+==== Understanding the thresholds ====
+All four fields use percentages from 0 to 100. **Set an individual threshold to zero to disable that check.** A thumb is rejected if any enabled check fails.
+^ Field ^ Default ^ When the thumb is rejected ^
+| **Dark pixels** | 98% | The share of almost-black pixels reaches the threshold. Pixels with brightness at or below 2% count as almost black. |
+| **Light pixels** | 98% | The share of almost-white pixels reaches the threshold. Pixels with brightness above 98% count as almost white. |
+| **Minimum brightness variation** | 1% | Brightness variation is below the threshold: the image is almost uniform. |
+| **Minimum edge detail** | 0.5% | The edge-detail score is below the threshold: the image may be heavily blurred. |
+For example, with **Dark pixels = 98**, a thumb with 99% almost-black pixels is rejected. If 90% of its pixels are almost black, that particular check passes, but the other checks still run.
+Lower **Dark pixels** and **Light pixels** thresholds make filtering stricter. For **Minimum brightness variation** and **Minimum edge detail**, increasing the threshold makes filtering stricter. These last two scores describe image properties; they are not probabilities that a thumb is bad.
+==== Testing and enabling the filter ====
+  - In **Thumb Settings**, select **Image Lib = ImageMagick**, check **Path to IM**, and save that selection.
+  - Open **Preview quality filter**. Start with **Enable preview quality filter = Off** and the default thresholds.
+  - Enter a direct HTTP/HTTPS image URL in **Test image** and click **Test image**. The server downloads the image, so the URL must be accessible from the server.
+  - Review the result: **PASSES these thresholds** means the image passes your thresholds; **REJECTED by these thresholds** means it is rejected. The measured scores and rejection reasons appear below.
+  - Test several usable thumbs and several obviously bad ones. Adjust the thresholds and repeat the test if necessary.
+  - Once the results suit your content, set **Enable preview quality filter = On** and save the settings.
+**Test image uses the four current threshold values from the form without saving them.** It works even when automatic filtering is off. Clicking this button does not enable the filter or save settings.
+==== Import behaviour ====
+The filter checks local thumbs, including thumbs generated with a crop profile and images copied without resizing. Additional crops are also checked; if an additional crop is rejected, the corresponding thumb candidate is skipped altogether. Processing continues with the other candidates.
+Remote-only hotlinks are not checked. If an image has already been downloaded for an MD5 check, the filter can check that file too. Enabling this option does not start a new scan of previously saved thumbs.
+For example, if the filter rejects 5 of 30 candidates, import continues with the remaining candidates. If no thumbs remain, the import fails. The existing **Grab error action** setting determines whether to **Mark as grab error** or **Delete gallery**.
+If ImageMagick cannot complete the analysis, the error is logged. An analysis error does not count as an image defect, so this filter retains the candidate.
+==== Errors and logs ====
+The manual test allows 15 seconds for each download attempt and up to 5 seconds to connect. A failed request may be retried without Referer, with the same timeout. The browser waits up to 30 seconds for the test response, then displays a timeout error.
+Download errors include the HTTP status or cURL error details. If the test stays on **Loading and checking image**, look in **logs/admin_area.log**. Entries start with **Preview quality test:** and identify the download start, transition to analysis, result or error, and elapsed time.
+Run this command from the script installation directory to watch those entries:
+<code bash>
+tail -f logs/admin_area.log | grep --line-buffered 'Preview quality test:'
+</code>
+During automatic import, results and analysis errors are written to **logs/gallery_grabber.log**. Manual-test downloads use temporary files that are removed after a successful check or an error.
+==== Limitations ====
+Only the first frame of an animated image is checked. For analysis, the image is reduced to at most 320 x 320 pixels and converted to grayscale; the source file is unchanged.
+This filter looks for obvious defects. It does not judge the scene, faces or visual appeal, and does not select the best frame from a video. Text or a sharp background can mask a blurred subject, while a valid image with a smooth background can receive a low edge-detail score. Test the thresholds on your own thumbs with **Test image** before enabling automatic filtering.
 ===== Test Positions End =====