Set up workspace. Document lossless limitations rather than broken tests (#446)

Author: IanButterworth

Project.toml

@@ -25,3 +25,6 @@ ImageCore = "0.8, 0.9, 0.10"
 PrecompileTools = "1"
 Scratch = "1"
 julia = "1.10"
+
+[workspace]
+projects = ["test", "docs"]

docs/Project.toml

@@ -1,5 +1,9 @@
 [deps]
+VideoIO = "d6d074c3-1acf-5d4c-9a43-ef38773959a2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
 [compat]
 Documenter = "1"
+
+[sources]
+VideoIO = {path = ".."}

docs/src/writing.md

@@ -69,10 +69,12 @@ VideoIO.close_video_out!
 ```
 
 ## Supported Colortypes
-Encoding of the following image element color types currently supported:
+Encoding of the following image element color types is currently supported:
 - `UInt8`
 - `Gray{N0f8}`
+- `Gray{N6f10}`
 - `RGB{N0f8}`
+- `RGB{N6f10}`
 
 ## Encoder Options
 
@@ -101,5 +103,11 @@ If lossless encoding of `RGB{N0f8}` is required, _true_ lossless requires passin
 If lossless encoding of `Gray{N0f8}` or `UInt8` is required, `crf=0` should be set, as well as `color_range=2` to ensure full 8-bit pixel color representation. i.e.
 ```(color_range=2, crf=0, preset="medium")```
 
+### 10-bit Limitations
+Pixel-exact round-trip encoding is **not** guaranteed for 10-bit types (`Gray{N6f10}` and `RGB{N6f10}`):
+
+- **`Gray{N6f10}`**: libx264 stores the data as `yuv420p10le` internally. On decode, the Y-plane values are converted back via a YUV→gray sws transform, which introduces small rounding errors (~1–10 counts out of 1023). The video is still perceptually lossless, but bitwise identical frames cannot be guaranteed.
+- **`RGB{N6f10}`**: libx264rgb does not support 10-bit RGB. Frames are silently downsampled to 8-bit (`bgr24`) during encoding, making this inherently lossy. For 10-bit RGB, consider a codec that natively supports it (e.g. `ffv1`).
+
 ### Encoding Performance
 See [`util/lossless_video_encoding_testing.jl`](https://github.com/JuliaIO/VideoIO.jl/blob/master/util/lossless_video_encoding_testing.jl) for testing of losslessness, speed, and compression as a function of h264 encoding preset, for 3 example videos.

test/Project.toml

@@ -1,4 +1,5 @@
 [deps]
+VideoIO = "d6d074c3-1acf-5d4c-9a43-ef38773959a2"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
 ColorVectorSpace = "c3611d14-8923-5661-9e6a-0046d554d3a4"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -11,3 +12,6 @@ Profile = "9abbd945-dff8-562f-b5e8-e1ebf5ef1b79"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[sources]
+VideoIO = {path = ".."}

test/reading.jl

@@ -130,21 +130,10 @@
             if occursin("annie_oakley", name)
                 framestack = VideoIO.load(testvid_path)
                 @test length(framestack) == VideoIO.TestVideos.videofiles[name].numframes
-                # TODO: Replace this with a content check as summarysize is not stable across julia versions
-                if VERSION < v"1.6.3" || VERSION > v"1.11.0-0"
-                    @test_broken Base.summarysize(framestack) == VideoIO.TestVideos.videofiles[name].summarysize
-                else
-                    @test Base.summarysize(framestack) == VideoIO.TestVideos.videofiles[name].summarysize
-                end
+                # summarysize is not stable across Julia versions, so only test frame count
                 f = File{DataFormat{:OGG}}(testvid_path)
                 framestack = VideoIO.fileio_load(f)
                 @test length(framestack) == VideoIO.TestVideos.videofiles[name].numframes
-                # TODO: Replace this with a content check as summarysize is not stable across julia versions
-                if VERSION < v"1.6.3" || VERSION > v"1.11.0-0"
-                    @test_broken Base.summarysize(framestack) == VideoIO.TestVideos.videofiles[name].summarysize
-                else
-                    @test Base.summarysize(framestack) == VideoIO.TestVideos.videofiles[name].summarysize
-                end
                 path, io = mktemp()
                 f = File{DataFormat{:MP4}}(path * ".mp4")
                 VideoIO.fileio_save(f, framestack)

test/writing.jl

@@ -74,18 +74,18 @@ end
                             img = read(f)
                             test_img = scanline_arg ? parent(img) : img
                             i = 1
+                            # N6f10 types are not losslessly roundtripped by libx264/libx264rgb:
+                            # libx264 encodes gray10le as yuv420p10le internally, and libx264rgb
+                            # does not support 10-bit RGB at all (silently encodes as 8-bit).
+                            # Pixel-exact roundtrip is therefore not expected for N6f10.
                             if el in [Gray{N0f8}, RGB{N0f8}]
                                 @test test_img == img_stack[i]
-                            else
-                                @test_broken test_img == img_stack[i]
                             end
                             while !eof(f) && i < n
                                 read!(f, img)
                                 i += 1
                                 if el in [Gray{N0f8}, RGB{N0f8}]
                                     @test test_img == img_stack[i]
-                                else
-                                    @test_broken test_img == img_stack[i]
                                 end
                             end
                             @test i == n