Add ffmpeg load_frame (#2770)

* Add ffmpeg::load_frame

* Add ffmpeg::save_frame

* Check for supported encoders

* Add documentation

* Add pfeatherstone suggestions and enable only for RGB images

* Remove the pixel format setting, as it is not needed

* Fix formatting in error message

* Set pixel format in ffmpeg::save_frame

* Fix formatting

* Remove ffmpeg::save_frame

dlib/media/ffmpeg_abstract.h

@@ -1013,6 +1013,22 @@ namespace dlib
             !*/
         };
 
+// ---------------------------------------------------------------------------------------------------
+
+        template <typename image_type>
+        std::enable_if_t<is_image_type<image_type>::value, void>
+        load_frame(
+            image_type& image,
+            const std::string& file_name
+        );
+        /*!
+            requires
+                - image_type must be a type conforming to the generic image interface.
+            ensures
+                - reads the first frame of the image or video pointed by file_name and
+                  loads into image.
+        !*/
+
 // ---------------------------------------------------------------------------------------------------
 
         template <

dlib/media/ffmpeg_demuxer.h

@@ -1034,6 +1034,19 @@ namespace dlib
 
 // ---------------------------------------------------------------------------------------------------
 
+        template <typename image_type>
+        std::enable_if_t<is_image_type<image_type>::value, void>
+        load_frame(image_type& image, const std::string& file_name)
+        {
+            demuxer reader(file_name);
+            frame f;
+
+            if (!reader.is_open() || !reader.read(f) || !f.is_image())
+                throw error("ffmpeg::load_frame: error while loading " + file_name);
+
+            convert(f, image);
+        }
+
     }
 }
 

dlib/media/ffmpeg_utils.h

@@ -313,22 +313,22 @@ namespace dlib
         template<class PixelType>
         struct pix_traits {};
 
-        template<> struct pix_traits<uint8_t>           {constexpr static AVPixelFormat fmt = AV_PIX_FMT_GRAY8; };
-        template<> struct pix_traits<rgb_pixel>         {constexpr static AVPixelFormat fmt = AV_PIX_FMT_RGB24; };
-        template<> struct pix_traits<bgr_pixel>         {constexpr static AVPixelFormat fmt = AV_PIX_FMT_BGR24; };
-        template<> struct pix_traits<rgb_alpha_pixel>   {constexpr static AVPixelFormat fmt = AV_PIX_FMT_RGBA;  };
-        template<> struct pix_traits<bgr_alpha_pixel>   {constexpr static AVPixelFormat fmt = AV_PIX_FMT_BGRA;  };
+        template<> struct pix_traits<uint8_t>           { constexpr static AVPixelFormat fmt = AV_PIX_FMT_GRAY8; };
+        template<> struct pix_traits<rgb_pixel>         { constexpr static AVPixelFormat fmt = AV_PIX_FMT_RGB24; };
+        template<> struct pix_traits<bgr_pixel>         { constexpr static AVPixelFormat fmt = AV_PIX_FMT_BGR24; };
+        template<> struct pix_traits<rgb_alpha_pixel>   { constexpr static AVPixelFormat fmt = AV_PIX_FMT_RGBA;  };
+        template<> struct pix_traits<bgr_alpha_pixel>   { constexpr static AVPixelFormat fmt = AV_PIX_FMT_BGRA;  };
 
 // ---------------------------------------------------------------------------------------------------
 
         template<class SampleType>
         struct sample_traits {};
 
-        template<> struct sample_traits<uint8_t> {constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_U8; };
-        template<> struct sample_traits<int16_t> {constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_S16; };
-        template<> struct sample_traits<int32_t> {constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_S32; };
-        template<> struct sample_traits<float>   {constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_FLT; };
-        template<> struct sample_traits<double>  {constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_DBL; };
+        template<> struct sample_traits<uint8_t> { constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_U8; };
+        template<> struct sample_traits<int16_t> { constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_S16; };
+        template<> struct sample_traits<int32_t> { constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_S32; };
+        template<> struct sample_traits<float>   { constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_FLT; };
+        template<> struct sample_traits<double>  { constexpr static AVSampleFormat fmt = AV_SAMPLE_FMT_DBL; };
 
 // ---------------------------------------------------------------------------------------------------