Update README.md: add benchmark numbers (#45)

* Update README.md: add x86-64 benchmark numbers

* Add improvements based on testing results

* Sort properties in Directory.Build.props

* Update README.md

Author: vbaderks

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.8.0 - 2024-8-21]
+## [0.8.0 - 2024-8-23]
 
 ### Added
 

CharLSDotNet.sln

@@ -23,7 +23,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CharLS.Managed.Test", "test
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CharLS.Managed.Benchmark", "benchmark\CharLS.Managed.Benchmark.csproj", "{43E730B3-BCBC-40A8-8F32-72FC278300D5}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{A9E95F06-F2ED-46F9-8AE7-9EBE15768205}"
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "samples", "{A9E95F06-F2ED-46F9-8AE7-9EBE15768205}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Convert", "samples\Convert\Convert.csproj", "{601E8408-2608-403C-B1E6-E78244506CAB}"
 EndProject

Directory.Build.props

@@ -16,6 +16,7 @@
     <ChecksumAlgorithm>SHA256</ChecksumAlgorithm>    <!-- Use Sha256 for checksums in PDBs (default is SHA1) -->
     <AccelerateBuildsInVisualStudio>true</AccelerateBuildsInVisualStudio><!-- Enable faster builds in Visual Studio 2022 17.5 and newer. -->
     <GenerateDocumentationFile>True</GenerateDocumentationFile>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
 
     <!-- Version information -->
     <Version>0.8.0</Version>
@@ -27,7 +28,6 @@
     <!-- Build to a folder outside the source folders, making it easier to clean. -->
     <OutputPath>$(MSBuildThisFileDirectory)build\binaries\$(Configuration)\</OutputPath>
     <BaseIntermediateOutputPath>$(MSBuildThisFileDirectory)build\intermediates\$(MSBuildProjectName)\</BaseIntermediateOutputPath>
-    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
 
     <!-- Static Analysis -->
     <AnalysisLevel>latest-All</AnalysisLevel>

README.md

@@ -5,41 +5,65 @@
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/team-charls/charls-dotnet/blob/main/LICENSE.md)
 [![Build and Test](https://github.com/team-charls/charls-dotnet/actions/workflows/dotnet.yml/badge.svg)](https://github.com/team-charls/charls-dotnet/actions/workflows/dotnet.yml)
 [![Coverage Status](https://coveralls.io/repos/github/team-charls/charls-dotnet/badge.svg)](https://coveralls.io/github/team-charls/charls-dotnet)
+[![NuGet](https://img.shields.io/nuget/v/CharLS.Managed.svg)](https://www.nuget.org/packages/CharLS.Managed)
 
 CharLS .NET is a C# JPEG-LS library implementation.  
 JPEG-LS (ISO-14495-1) is a lossless/near-lossless compression standard for continuous-tone images.
 
-## IMPORTANT : WORK IN PROGRESS
-
-This project is considered work in progress and NOT ready for general use. The following functionality is planned / implemented:
-
-* [X] Decode 8 bit images, interleave mode: none
-* [X] Decode 8 bit images, interleave mode: line
-* [X] Decode 8 bit images, interleave mode: sample
-* [X] Decode 8 bit images, nearLossless != 0. interleave mode: none, line, sample
-* [X] Decode 16 bit images, interleave mode: none
-* [X] Decode 16 bit images, interleave mode: line
-* [X] Decode 16 bit images, interleave mode: sample
-* [X] Encode 8 bit images, interleave mode: none
-* [X] Encode 8 bit images, interleave mode: line
-* [X] Encode 8 bit images, interleave mode: sample
-* [X] Encode\Decode 8 bit images HP color transformation
-* [X] Encode 16 bit images, interleave mode: none
-* [X] Encode 16 bit images, interleave mode: line
-* [X] Encode 16 bit images, interleave mode: sample
-* [X] Encode\Decode 16 bit images HP color transformation
-* [X] Encode\Decode 4 component images
-* [X] Support for SPIFF Header
-* [ ] General code clean-up
-* [ ] Good code coverage
-* [ ] Performance tuning
-* [ ] Release NuGet package
-
 ## Features
 
 * .NET 8.0 class library.
 * Support for the .NET platforms: Windows, Linux and macOS.
 
+## Performance
+
+A couple of benchmarks have been executed to assist to decide which codec to use.
+The following codecs were measured:
+
+|Codec         |Version|Release date|Description|
+|------------  |-------|------------|----------------------------------------------|
+|CharLS.Managed| 0.8.0 |2024-08-23  |C# implementation                             |
+|CharLS.Native | 3.2.0 |2023-09-24  |C# wrapper around C++ implementation          |
+|cscharls      | 0.1.1 |2017-04-24  |C# implementation                             |
+|charls-js     | 2.1.1 |2021-10-07  |WebAssembly implementation based on C++ source|
+
+and the following test images were used:
+
+|Image name    |Width  |Height|Bits per sample|Components|Description               |
+|------------  |------:|-----:|--------------:|---------:|--------------------------|
+|Tulips        |    512|   512|              8|         1|Monochrome image of tulips|
+|MG1           |   3064|  4664|             12|         1|Monochrome medical image  |
+|Delta E       |   3072|  2048|              8|         3|Artificial RGB image      |
+
+The benchmarks were performed on 2 hardware platforms: x86 and ARM64.  
+The column 'NEAR' defines the allowed error, 0 means lossless encoding.  
+The column 'ILV' defines the interleave mode used to encode the image.
+
+### x86-64 Platform
+
+Characteristics of the test environment: AMD Ryzen 9 5950X, .NET 8.0.8 (X64 RyuJIT AVX2)  
+WebAssembly engine: Chrome V8 12.8.374.21
+
+|Operation      |NEAR|ILV   |CharLS.Managed|CharLS.Native|cscharls |charls-js|
+|---------------|---:|------|-------------:|------------:|--------:|--------:|
+|Decode Tulips  |   0|None  |        5.0 ms|       3.6 ms|  10.4 ms|   5.6 ms|
+|Decode MG1     |   0|None  |      292.3 ms|     205.0 ms| 676.3 ms| 335.2 ms|
+|Decode Delta E |   0|Sample|       80.0 ms|      89.4 ms|        -|  89.5 ms|
+|Encode Tulips  |   0|None  |        7.1 ms|       4.7 ms|  11.8 ms|        -|
+|Encode MG1     |   0|None  |      404.3 ms|     256.3 ms| 695.8 ms|        -|
+
+## Arm64 Platform
+
+Characteristics of the test environment: Snapdragon Compute Platform, .NET 8.0.8 (Arm64 RyuJIT AdvSIMD)  
+WebAssembly engine: Chrome V8 12.8.374.21
+
+|Operation      |NEAR|ILV   |CharLS.Managed|CharLS.Native|cscharls |charls-js|
+|---------------|---:|------|-------------:|------------:|--------:|--------:|
+|Decode Tulips  |   0|None  |        7.2 ms|       4.7 ms|  14.3 ms|  10.5 ms|
+|Decode MG1     |   0|None  |      431.7 ms|     261.8 ms|1019.4 ms| 542.1 ms|
+|Encode Tulips  |   0|None  |        9.6 ms|       5.5 ms|  15.7 ms|        -|
+|Encode MG1     |   0|None  |      564.0 ms|     318.6 ms|1017.2 ms|        -|
+
 ## How to use
 
 CharLS.Managed can be added to your C# project using the dotnet command line or the NuGet Package Manager in Visual Studio.
@@ -62,12 +86,16 @@ A sample application is included in the GitHub repository that demonstrates how
  git clone https://github.com/team-charls/charls-dotnet.git
 ```
 
-* Use the .NET 8.0 CLI or Visual Studio 2022 (v17.10 or newer) to build the solution file CharLSDotNet.sln. For example: `dotnet build && dotnet test && dotnet publish` to build the nuget package.
+* Use the .NET 8.0 CLI or Visual Studio 2022 (v17.11 or newer) to build the solution file CharLSDotNet.sln.  
+ For example: `dotnet build && dotnet test && dotnet publish` to build the NuGet package.  
+ Building can be done on all supported .NET SDK platforms: Windows, Linux or macOS
 
-### Building Windows DLLs and code signing all components
+### Code signing the assembly and the NuGet package
 
-Building the NuGet package with signed Windows DLLs can only be done on the Window platform with Visual Studio 2022 or with Build tools for Visual Studio 2022.
-To support code signing with a code signing certificate, stored on a smart card, a Windows command file is available: `create-signed-nuget-package.cmd`.
+Building the NuGet package with a signed assembly DLL and NuGet package can only be done
+on the Window platform with Visual Studio 2022 or with Build tools for Visual Studio 2022.
+To support code signing with a code signing certificate, stored on a smart card, a
+Windows command file is available: `create-signed-nuget-package.cmd`.
 Instructions:
 
 * Open a Visual Studio Developer Command Prompt
@@ -76,8 +104,9 @@ Instructions:
 * Execute the command `create-signed-nuget-package.cmd certificate-thumb-print time-stamp-url`  
  The certificate thumbprint and time stamp URL arguments are depending on the used code signing certificate.
 
- All DLLs and the NuGet package itself will be signed.
+All assembly DLLs and the NuGet package itself will be signed.
 
 ## About the JPEG-LS image compression standard
 
-More information about JPEG-LS can be found in the [README](https://github.com/team-charls/charls/blob/master/README.md) from the C++ CharLS project.
+More information about JPEG-LS can be found in the [README](https://github.com/team-charls/charls/blob/master/README.md)
+from the C++ CharLS project.

src/ErrorCode.cs

@@ -246,7 +246,7 @@ public enum ErrorCode
     InvalidArgumentColorTransformation = 109,
 
     /// <summary>
-    /// The argument for the size parameter is outside the valid range.
+    /// The size of a buffer parameter is outside the valid range.
     /// </summary>
     InvalidArgumentSize = 110,
 

src/JpegLSDecoder.cs

@@ -362,15 +362,16 @@ public void Decode(Span<byte> destination, int stride = AutoCalculateStride)
         }
         else
         {
-            if (stride < minimumStride)
-                throw new ArgumentException("stride < minimumStride", nameof(stride));
+            ThrowHelper.ThrowArgumentExceptionIfFalse(stride >= minimumStride, nameof(stride), ErrorCode.InvalidArgumentStride);
         }
 
         // Compute the layout of the destination buffer.
         int bytesPerPlane = FrameInfo.Width * FrameInfo.Height * BitToByteCount(FrameInfo.BitsPerSample);
         int planeCount = _reader.InterleaveMode == InterleaveMode.None ? FrameInfo.ComponentCount : 1;
         int minimumDestinationSize = (bytesPerPlane * planeCount) - (stride - minimumStride);
 
+        ThrowHelper.ThrowArgumentExceptionIfFalse(destination.Length >= minimumDestinationSize, nameof(destination), ErrorCode.InvalidArgumentSize);
+
         if (destination.Length < minimumDestinationSize)
             throw new ArgumentException("destination buffer too small", nameof(destination));
 

src/JpegLSEncoder.cs

@@ -42,28 +42,31 @@ public JpegLSEncoder()
     /// <param name="height">The height of the image to encode.</param>
     /// <param name="bitsPerSample">The bits per sample of the image to encode.</param>
     /// <param name="componentCount">The component count of the image to encode.</param>
-    /// <param name="allocateDestination">Flag to control if destination buffer should be allocated or not.</param>
-    /// <param name="extraBytes">Number of extra destination bytes. Comments and tables are not included in the estimate.</param>
+    /// <param name="interleaveMode">The interleave mode of the image to encode (default None).</param>
+    /// <param name="allocateDestination">Flag to control if destination buffer should be allocated or not (default true).</param>
+    /// <param name="extraBytes">Number of extra destination bytes. Comments and tables are not included in the standard estimate (default 0).</param>
     /// <exception cref="ArgumentOutOfRangeException">Thrown when one of the arguments is invalid.</exception>
     /// <exception cref="OutOfMemoryException">Thrown when memory allocation for the destination buffer fails.</exception>
-    public JpegLSEncoder(int width, int height, int bitsPerSample, int componentCount, bool allocateDestination = true, int extraBytes = 0)
-        : this(new FrameInfo(width, height, bitsPerSample, componentCount), allocateDestination, extraBytes)
+    public JpegLSEncoder(int width, int height, int bitsPerSample, int componentCount, InterleaveMode interleaveMode = InterleaveMode.None, bool allocateDestination = true, int extraBytes = 0)
+        : this(new FrameInfo(width, height, bitsPerSample, componentCount), interleaveMode, allocateDestination, extraBytes)
     {
     }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="JpegLSEncoder"/> class.
     /// </summary>
     /// <param name="frameInfo">The frameInfo of the image to encode.</param>
-    /// <param name="allocateDestination">Flag to control if destination buffer should be allocated or not.</param>
-    /// <param name="extraBytes">Number of extra destination bytes. Comments and tables are not included in the estimate.</param>
+    /// <param name="interleaveMode">The interleave mode of the image to encode (default None).</param>
+    /// <param name="allocateDestination">Flag to control if destination buffer should be allocated or not (default true).</param>
+    /// <param name="extraBytes">Number of extra destination bytes. Comments and tables are not included in the standard estimate (default 0).</param>
     /// <exception cref="ArgumentOutOfRangeException">Thrown when one of the arguments is invalid.</exception>
     /// <exception cref="OutOfMemoryException">Thrown when memory allocation for the destination buffer fails.</exception>
-    public JpegLSEncoder(FrameInfo frameInfo, bool allocateDestination = true, int extraBytes = 0)
+    public JpegLSEncoder(FrameInfo frameInfo, InterleaveMode interleaveMode = InterleaveMode.None, bool allocateDestination = true, int extraBytes = 0)
     {
         ArgumentOutOfRangeException.ThrowIfNegative(extraBytes);
 
         FrameInfo = frameInfo;
+        InterleaveMode = interleaveMode;
 
         if (allocateDestination)
         {
@@ -489,7 +492,7 @@ public void CreateAbbreviatedFormat()
     /// </summary>
     /// <param name="source">Source pixel data that needs to be encoded.</param>
     /// <param name="frameInfo">Frame info object that describes the pixel data.</param>
-    /// <param name="interleaveMode">Defines how the the pixel data should be encoded.</param>
+    /// <param name="interleaveMode">Defines how the pixel data should be encoded.</param>
     /// <param name="encodingOptions">Defines several options how to encode the pixel data.</param>
     /// <param name="stride">The stride to use; byte count to the next pixel row. Pass 0 (AutoCalculateStride) for the default.</param>
     public static Memory<byte> Encode(

src/ThrowHelper.cs

@@ -144,7 +144,7 @@ private static string GetErrorMessage(ErrorCode errorCode)
             ErrorCode.InvalidArgumentNearLossless => "The near lossless argument is outside the range [0, min(255, MAXVAL/2)]",
             ErrorCode.InvalidArgumentPresetCodingParameters => "The argument for the JPEG-LS preset coding parameters is not valid",
             ErrorCode.InvalidArgumentColorTransformation => "The argument for the color component is not (None, Hp1, Hp2, Hp3) or invalid in combination with component count",
-            ErrorCode.InvalidArgumentSize => "The passed size is outside the valid range",
+            ErrorCode.InvalidArgumentSize => "The passed size of a buffer is outside the valid range",
             ErrorCode.InvalidArgumentStride => "The stride argument does not match with the frame info and buffer size",
             ErrorCode.InvalidArgumentEncodingOptions => "The encoding options argument has an invalid value",
             _ => string.Empty

src/nuget-release-notes.txt

@@ -1,2 +1,2 @@
-1.1.0-alpha.1
- - Initial release
+0.8.0
+ - Initial release.

test/JpegLSDecoderTest.cs

@@ -444,7 +444,7 @@ static void EventHandler(object? sender, CommentEventArgs e)
     [Fact]
     public void ApplicationDataHandlerReceivesApplicationDataBytes()
     {
-        JpegLSEncoder encoder = new(1, 1, 8, 1, true, 100);
+        JpegLSEncoder encoder = new(1, 1, 8, 1, InterleaveMode.None, true, 100);
 
         var applicationData1 = new byte[] { 1, 2, 3, 4 };
         encoder.WriteApplicationData(12, applicationData1);