feat: preserve full-range colour when converting YUVJ frames via swscale

swscale assumes limited (MPEG, 16-235) input range by default. Mapping a
full-range JPEG format (YUVJ*) to its non-J equivalent for the conversion
therefore washes the colours out, because full-range luma/chroma gets
treated as limited.

Add pix_fmt_is_jpeg_range() and zm_sws_set_input_range(), which sets
srcRange=1 on the context when the original source format was full range.
Apply it at every conversion site that takes decoded frames: Image::Assign
and both SWScale::Convert overloads. Monitor::setupConvertContext already
did this inline with a hand-rolled switch and colorspace block; replace
that with the shared helpers to remove the duplication.

Add tests/zm_swscale_range.cpp: converting a Y=16 YUVJ420P image to RGB24
keeps luma ~16 (full range) rather than being crushed to ~0 (limited).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: connortechnology

src/zm_ffmpeg.cpp

@@ -577,6 +577,43 @@ enum AVPixelFormat fix_deprecated_pix_fmt(enum AVPixelFormat fmt) {
   }
 }
 
+bool pix_fmt_is_jpeg_range(enum AVPixelFormat fmt) {
+  // The deprecated YUVJ* formats carry full-range (0-255) luma/chroma, as
+  // opposed to the limited/broadcast range (16-235) of their non-J equivalents.
+  switch (fmt) {
+  case AV_PIX_FMT_YUVJ411P:
+  case AV_PIX_FMT_YUVJ420P:
+  case AV_PIX_FMT_YUVJ422P:
+  case AV_PIX_FMT_YUVJ440P:
+  case AV_PIX_FMT_YUVJ444P:
+    return true;
+  default:
+    return false;
+  }
+}
+
+void zm_sws_set_input_range(struct SwsContext *ctx, enum AVPixelFormat original_src_fmt) {
+  // swscale assumes limited (MPEG) input range by default. When the decoded
+  // source was a full-range JPEG format (YUVJ*) that got mapped to its non-J
+  // equivalent by fix_deprecated_pix_fmt(), swscale would otherwise treat the
+  // full-range samples as limited and wash the colours out. Tell it the input
+  // is full range so the YUV->RGB / YUV->YUV maths is correct. Pass the
+  // ORIGINAL (pre-fix) format so we can tell whether the source was full range.
+  if (!pix_fmt_is_jpeg_range(original_src_fmt)) return;
+
+  int *inv_table, *table;
+  int srcRange, dstRange, brightness, contrast, saturation;
+  // Returns < 0 when the conversion does not expose colorspace details (e.g.
+  // RGB->RGB); nothing to correct in that case.
+  if (sws_getColorspaceDetails(ctx, &inv_table, &srcRange, &table, &dstRange,
+                               &brightness, &contrast, &saturation) < 0)
+    return;
+  if (srcRange == 1) return;  // already full range
+  srcRange = 1;
+  sws_setColorspaceDetails(ctx, inv_table, srcRange, table, dstRange,
+                           brightness, contrast, saturation);
+}
+
 bool is_video_stream(const AVStream * stream) {
   if (stream->codecpar->codec_type == AVMEDIA_TYPE_VIDEO) {
     return true;

src/zm_ffmpeg.h

@@ -252,6 +252,11 @@ void zm_dump_codecpar(const AVCodecParameters *par);
 
 int check_sample_fmt(const AVCodec *codec, enum AVSampleFormat sample_fmt);
 enum AVPixelFormat fix_deprecated_pix_fmt(enum AVPixelFormat );
+bool pix_fmt_is_jpeg_range(enum AVPixelFormat );
+// Correct swscale's default limited-range assumption when the original decoded
+// source was a full-range JPEG (YUVJ*) format. Call after (re)creating the
+// context, passing the ORIGINAL pre-fix_deprecated_pix_fmt source format.
+void zm_sws_set_input_range(struct SwsContext *ctx, enum AVPixelFormat original_src_fmt);
 
 bool is_video_stream(const AVStream *);
 bool is_audio_stream(const AVStream *);

src/zm_image.cpp

@@ -376,7 +376,8 @@ bool Image::Assign(const AVFrame *frame) {
   // format to swscale. Passing YUVJ420P/YUVJ422P/etc directly makes swscale emit
   // "deprecated pixel format used, make sure you did set range correctly" (seen
   // in nph-zms). This mirrors what SWScale::Convert already does.
-  const AVPixelFormat src_fmt = fix_deprecated_pix_fmt(static_cast<AVPixelFormat>(frame->format));
+  const AVPixelFormat orig_src_fmt = static_cast<AVPixelFormat>(frame->format);
+  const AVPixelFormat src_fmt = fix_deprecated_pix_fmt(orig_src_fmt);
 
   // If source and destination format + dimensions match, do a direct plane
   // copy instead of running through sws_scale. This avoids the overhead of
@@ -418,6 +419,7 @@ bool Image::Assign(const AVFrame *frame) {
     Error("Unable to create conversion context");
     return false;
   }
+  zm_sws_set_input_range(sws_convert_context, orig_src_fmt);
   bool result = Assign(frame, sws_convert_context);
   update_function_pointers();
   return result;

src/zm_monitor.cpp

@@ -2946,28 +2946,8 @@ int Monitor::Capture() {
 
 bool Monitor::setupConvertContext(const AVFrame *input_frame, const Image *image) {
   AVPixelFormat imagePixFormat = image->AVPixFormat();
-  AVPixelFormat inputPixFormat;
-  bool changeColorspaceDetails = false;
-  switch (input_frame->format) {
-  case AV_PIX_FMT_YUVJ420P:
-    inputPixFormat = AV_PIX_FMT_YUV420P;
-    changeColorspaceDetails = true;
-    break;
-  case AV_PIX_FMT_YUVJ422P:
-    inputPixFormat = AV_PIX_FMT_YUV422P;
-    changeColorspaceDetails = true;
-    break;
-  case AV_PIX_FMT_YUVJ444P:
-    inputPixFormat = AV_PIX_FMT_YUV444P;
-    changeColorspaceDetails = true;
-    break;
-  case AV_PIX_FMT_YUVJ440P:
-    inputPixFormat = AV_PIX_FMT_YUV440P;
-    changeColorspaceDetails = true;
-    break;
-  default:
-    inputPixFormat = (AVPixelFormat)input_frame->format;
-  }
+  AVPixelFormat origPixFormat = (AVPixelFormat)input_frame->format;
+  AVPixelFormat inputPixFormat = fix_deprecated_pix_fmt(origPixFormat);
 
   convert_context = sws_getContext(
                       input_frame->width,
@@ -2988,17 +2968,9 @@ bool Monitor::setupConvertContext(const AVFrame *input_frame, const Image *image
           image->Width(), image->Height(),
           av_get_pix_fmt_name(imagePixFormat)
          );
-    if (changeColorspaceDetails) {
-      // change the range of input data by first reading the current color space and then setting it's range as yuvj.
-      int dummy[4];
-      int srcRange, dstRange;
-      int brightness, contrast, saturation;
-      sws_getColorspaceDetails(convert_context, (int**)&dummy, &srcRange, (int**)&dummy, &dstRange, &brightness, &contrast, &saturation);
-      const int* coefs = sws_getCoefficients(SWS_CS_DEFAULT);
-      srcRange = 1; // this marks that values are according to yuvj
-      sws_setColorspaceDetails(convert_context, coefs, srcRange, coefs, dstRange,
-                               brightness, contrast, saturation);
-    }
+    // Mark the input as full range when the source was a YUVJ* format so the
+    // conversion maths doesn't crush full-range luma into limited range.
+    zm_sws_set_input_range(convert_context, origPixFormat);
   }
   return (convert_context != nullptr);
 }

src/zm_swscale.cpp

@@ -58,7 +58,8 @@ int SWScale::Convert(
   AVFrame *out_frame
 ) {
 
-  AVPixelFormat format = fix_deprecated_pix_fmt((AVPixelFormat)in_frame->format);
+  AVPixelFormat orig_format = (AVPixelFormat)in_frame->format;
+  AVPixelFormat format = fix_deprecated_pix_fmt(orig_format);
   /* Get the context */
   swscale_ctx = sws_getCachedContext(swscale_ctx,
                                      in_frame->width, in_frame->height, format,
@@ -68,6 +69,7 @@ int SWScale::Convert(
     Error("Failed getting swscale context");
     return -6;
   }
+  zm_sws_set_input_range(swscale_ctx, orig_format);
   /* Do the conversion */
   if (!sws_scale(swscale_ctx,
                  in_frame->data, in_frame->linesize, 0, in_frame->height,
@@ -114,6 +116,7 @@ int SWScale::Convert(
     return -4;
   }
 
+  const enum _AVPIXELFORMAT orig_in_pf = in_pf;
   in_pf = fix_deprecated_pix_fmt(in_pf);
 
   /* Warn if the input or output pixelformat is not supported */
@@ -155,6 +158,7 @@ int SWScale::Convert(
     Error("Failed getting swscale context");
     return -6;
   }
+  zm_sws_set_input_range(swscale_ctx, orig_in_pf);
 
   /* Fill in the buffers. The alignments describe how the caller's buffers
    * are actually laid out — they are facts about the buffers, not tuning

tests/CMakeLists.txt

@@ -23,6 +23,7 @@ set(TEST_SOURCES
   zm_onvif_renewal.cpp
   zm_onvif_wsse.cpp
   zm_pixformat.cpp
+  zm_swscale_range.cpp
   zm_poly.cpp
   zm_time.cpp
   zm_utils.cpp

tests/zm_swscale_range.cpp

@@ -0,0 +1,64 @@
+/*
+ * This file is part of the ZoneMinder Project. See AUTHORS file for Copyright information
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation; either version 2 of the License, or (at your
+ * option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "zm_catch2.h"
+
+#include "zm_ffmpeg.h"
+#include "zm_swscale.h"
+
+#include <cstdlib>
+#include <vector>
+
+TEST_CASE("pix_fmt_is_jpeg_range identifies full-range YUVJ formats", "[swscale]") {
+  REQUIRE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUVJ420P));
+  REQUIRE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUVJ422P));
+  REQUIRE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUVJ444P));
+  REQUIRE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUVJ440P));
+
+  REQUIRE_FALSE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUV420P));
+  REQUIRE_FALSE(pix_fmt_is_jpeg_range(AV_PIX_FMT_YUV422P));
+  REQUIRE_FALSE(pix_fmt_is_jpeg_range(AV_PIX_FMT_RGB24));
+  REQUIRE_FALSE(pix_fmt_is_jpeg_range(AV_PIX_FMT_GRAY8));
+}
+
+// Colorimetric regression: a full-range JPEG (YUVJ420P) frame carries luma in
+// 0-255. swscale defaults to limited (16-235) input range, which would crush a
+// dark grey Y=16 down to ~0 (black). zm_sws_set_input_range() must mark the
+// input full range so Y=16 survives as ~16.
+TEST_CASE("SWScale treats YUVJ420P input as full range when converting to RGB", "[swscale]") {
+  const int w = 16, h = 16;
+  const uint8_t Y = 16;  // full range -> ~16; limited range -> ~0
+
+  // YUVJ420P planar: Y plane (w*h), then U and V (w/2*h/2). Neutral chroma=128.
+  std::vector<uint8_t> in(SWScale::GetBufferSize(AV_PIX_FMT_YUVJ420P, w, h, 1), 128);
+  std::fill(in.begin(), in.begin() + w * h, Y);
+
+  std::vector<uint8_t> out(SWScale::GetBufferSize(AV_PIX_FMT_RGB24, w, h, 1), 0);
+
+  SWScale scaler;
+  REQUIRE(scaler.init());
+  int r = scaler.Convert(in.data(), in.size(), out.data(), out.size(),
+                         AV_PIX_FMT_YUVJ420P, AV_PIX_FMT_RGB24, w, h, 1, 1);
+  REQUIRE(r == 0);
+
+  // Full-range interpretation keeps luma ~16; limited-range would crush to ~0.
+  REQUIRE(out[0] >= 12);
+  REQUIRE(out[0] <= 20);
+  // Neutral chroma -> grey, so the three channels stay equal.
+  REQUIRE(std::abs(static_cast<int>(out[0]) - static_cast<int>(out[1])) <= 2);
+  REQUIRE(std::abs(static_cast<int>(out[1]) - static_cast<int>(out[2])) <= 2);
+}