👁 Image
CoreJ2K 2.3.0.81

▄█████ ▄▄▄ ▄▄▄▄ ▄▄▄▄▄ ██ ████▄ ██ ▄█▀ 
██ ██▀██ ██▄█▄ ██▄▄ ██ ▄██▀ ████ 
▀█████ ▀███▀ ██ ██ ██▄▄▄ ████▀ ███▄▄ ██ ▀█▄ 
A Managed and Portable JPEG2000 Codec for .NET Platforms

👁 NuGet
👁 Downloads
👁 License

👁 Release Build
👁 CodeQL Security Analysis
👁 Fuzzing

🚀 Quick Start

dotnet add package CoreJ2K
dotnet add package CoreJ2K.Skia

Simple API

using CoreJ2K;
using SkiaSharp;

// Decode – legacy path (returns InterleavedImage, useful for sample-level access)
using var image = J2kImage.FromStream(File.OpenRead("image.jp2"));
var bitmap = image.As<SKBitmap>();

// Decode – fast path (8-bit images, skips the intermediate int[] buffer: ~4× less memory)
var bitmap2 = J2kImage.DecodeToImage<SKBitmap>(File.OpenRead("image.jp2"));

// Encode with modern API (recommended)
byte[] data = CompleteConfigurationPresets.Web
 .WithCopyright("© 2025")
 .Encode(imageSource);

// Or use traditional API
byte[] j2kData = J2kImage.ToBytes(bitmap);

📖 Full Documentation • 💻 More Examples • 🎯 Modern API Guide • 📦 All Packages

📑 Table of Contents

• About
  • What is CoreJ2K?
  • Key Features
  • Why Choose CoreJ2K?
• Getting Started
  • Installation
  • Quick Examples
  • Platform Support
• Documentation
  • Encoding Guide
  • Advanced Parameters
  • Usage Notes
• Standards & Compliance
  • JPEG 2000 Part 1 (100%)
  • JPEG 2000 Part 2 (~50%)
  • Library Comparison
  • Full Specification Details
• Support
• Contributing
• **License

About

What is CoreJ2K?

CoreJ2K is a pure C# implementation of the JPEG 2000 image compression standard for .NET. Modern fork of CSJ2K (C# port of jj2000), designed for .NET Standard and modern .NET platforms. Provides both encoding and decoding with 100% ISO/IEC 15444-1 Part 1 compliance.

Key Features

Why Choose CoreJ2K?

Comparison: CoreJ2K is the only open-source .NET library with full JPEG 2000 Part 1 compliance and complete pointer marker read/write support.

↑ Back to top

Getting Started

Installation

Core Library

dotnet add package CoreJ2K

With Image Integration

# SkiaSharp (recommended - cross-platform)
dotnet add package CoreJ2K.Skia

# ImageSharp (modern .NET)
dotnet add package CoreJ2K.ImageSharp

# System.Drawing (Windows)
dotnet add package CoreJ2K.Windows

# Pfim (DDS/TGA)
dotnet add package CoreJ2K.Pfim

Quick Examples

Basic Decoding

using CoreJ2K;
using SkiaSharp;

// From file
var image = J2kImage.FromStream(File.OpenRead("image.jp2"));
var bitmap = image.As<SKBitmap>();

// From bytes
byte[] data = File.ReadAllBytes("image.j2k");
var image2 = J2kImage.FromBytes(data);

// Save as PNG
using var output = File.OpenWrite("output.png");
bitmap.Encode(output, SKEncodedImageFormat.Png, 90);

Fast Decode (8-bit, ~4× less peak memory)

For the common 8-bit decode-and-display path, DecodeToImage<T> writes pixels directly into the backend image, skipping the intermediate int[] buffer that InterleavedImage would normally allocate. Use this whenever you don't need sample-level access after decoding.

using CoreJ2K;
using SkiaSharp;

// From stream – fast path (8-bit components: ~1 B/sample peak vs ~5 B/sample legacy)
SKBitmap bitmap = J2kImage.DecodeToImage<SKBitmap>(File.OpenRead("image.jp2"));

// From byte array
SKBitmap bitmap2 = J2kImage.DecodeToImage<SKBitmap>(File.ReadAllBytes("image.j2k"));

// From file path
SKBitmap bitmap3 = J2kImage.DecodeFileToImage<SKBitmap>("image.jp2");

When to use the legacy FromStream path instead:

• You need to inspect or modify individual samples (GetSample, SetComponent, Crop, …).
• Any component has bit depth > 8 (the fast path falls back automatically, but you may also call FromStream directly).

Fast Random Tile Access (with TLM markers)

// For large tiled images with TLM markers
var image = J2kImage.FromStream(File.OpenRead("large_tiled.jp2"));

// Check if fast tile access is available
if (decoder.SupportsFastTileAccess())
{
 Console.WriteLine("✓ TLM markers present - instant tile access!");
 
 // Jump directly to tile 500 (out of 1000) - O(1) operation!
 bool usedFast = decoder.SeekToTile(500); // Instant!
 
 // Or access by coordinates
 decoder.SetTile(x, y); // Also uses TLM fast path internally
}
else
{
 Console.WriteLine("⚠ No TLM - sequential access only");

 // Falls back to O(n) sequential parsing
 decoder.SetTile(x, y); // Must parse all previous tiles
}

// Performance improvements with TLM:
// - Access tile 100 (of 1000): 1000x faster
// - GIS map server: ~30s → ~0.03s
// - Medical imaging: ~30s → ~0.05s

Creating images with TLM markers:

// Enable TLM markers for fast random access
var config = new CompleteEncoderConfigurationBuilder()
 .ForGeospatial() // Or any preset
 .WithTiles(t => t.SetSize(512, 512))
 .WithPointerMarkers(p => p.UseTLM(true)) // Enable TLM!
 .Build();

byte[] data = J2kImage.ToBytes(bitmap, config);
// Decoder can now seek to any tile instantly!

Basic Encoding

// Default (high quality)
byte[] j2k = J2kImage.ToBytes(bitmap);

// Lossless
var lossless = new ParameterList { ["lossless"] = "on", ["file_format"] = "on" };
byte[] data = J2kImage.ToBytes(bitmap, lossless);

// Lossy with target bitrate
var lossy = new ParameterList { ["rate"] = "0.5", ["file_format"] = "on" };
byte[] compressed = J2kImage.ToBytes(bitmap, lossy);

Platform Support

↑ Back to top

Documentation

Modern Configuration API

CoreJ2K 1.3.0+ includes a comprehensive, fluent configuration API that makes JPEG 2000 encoding easier and more intuitive than ever.

Quick Start with Presets

using CoreJ2K.Configuration;

// One-liner encoding with preset
byte[] webImage = CompleteConfigurationPresets.Web
 .WithCopyright("© 2025")
 .Encode(imageSource);

// Medical imaging (lossless)
byte[] medical = CompleteConfigurationPresets.Medical
 .WithMetadata(m => m
 .WithComment("Patient: Anonymous")
 .WithComment("Study: CT Scan"))
 .Encode(dicomImage);

// High-quality photography
byte[] photo = CompleteConfigurationPresets.Photography
 .WithCopyright("© 2025 Photographer")
 .WithComment("Sunset over mountains")
 .Encode(photograph);

Quality Presets

// Lossless (perfect reconstruction)
var config = new CompleteEncoderConfigurationBuilder()
 .ForLossless()
 .Build();

// High quality (90% quality)
var config = new CompleteEncoderConfigurationBuilder()
 .ForHighQuality()
 .Build();

// Balanced (75% quality)
var config = new CompleteEncoderConfigurationBuilder()
 .ForBalanced()
 .Build();

// High compression
var config = new CompleteEncoderConfigurationBuilder()
 .ForHighCompression()
 .Build();

Use Case Presets

// Medical imaging - lossless with appropriate settings
.ForMedical()

// Archival storage - very high quality + error resilience
.ForArchival()

// Web delivery - progressive + balanced quality
.ForWeb()

// Thumbnail generation - fast + small
.ForThumbnail()

// Geospatial/GIS - spatial browsing + tiled
.ForGeospatial()

// Streaming - quality progressive
.ForStreaming()

Fine-Grained Control

var config = new CompleteEncoderConfigurationBuilder()
 .WithQuality(0.85)
 .WithQuantization(q => q
 .UseExpounded()
 .WithBaseStepSize(0.008f)
 .WithGuardBits(2))
 .WithWavelet(w => w
 .UseIrreversible_9_7()
 .WithDecompositionLevels(6))
 .WithProgression(p => p.UseLRCP())
 .WithTiles(t => t.SetSize(512, 512))
 .WithMetadata(m => m
 .WithComment("Custom configuration")
 .WithCopyright("© 2025")
 .WithXml(customMetadata))
 .Build();

byte[] data = J2kImage.ToBytes(image, config);

📚 Complete Guides:

• - Unified API with presets
• - Encoding parameters
• - Quality/size trade-offs
• - Transform settings
• - Data organization
• - Comments, copyright, XML
• - DCO, NLT, MCT (JPX codestream extensions)
• - XML metadata representation (ISO/IEC 15444-14)

Traditional API (Encoding Guide)

Lossless

var p = new ParameterList();
p["lossless"] = "on";
p["file_format"] = "on";
byte[] data = J2kImage.ToBytes(bitmap, p);

Lossy with Quality

var p = new ParameterList();
p["rate"] = "0.5"; // 0.5 bits/pixel
p["file_format"] = "on"; // JP2 wrapper
p["tiles"] = "1024 1024"; // Tile size
p["Wlev"] = "5"; // Decomposition levels
byte[] data = J2kImage.ToBytes(bitmap, p);

Progressive Quality Layers

var p = new ParameterList();
p["rate"] = "0.2";
p["Alayers"] = "0.015 +20 2.0 +10"; // Multiple layers
p["Aptype"] = "res"; // Resolution progression
byte[] data = J2kImage.ToBytes(bitmap, p);

Advanced Parameters

Common encoder parameters (case-sensitive):

Note: Parameter names match internal encoder conventions (no leading dashes).

Usage Notes

• InterleavedImage: Cross-platform image wrapper. Use As<T>() to convert to platform types (e.g., SKBitmap). Carries a full int[] sample buffer — use DecodeToImage<T> instead when you only need the final bitmap.
• DecodeToImage<T>: Memory-efficient decode that skips InterleavedImage entirely for 8-bit images (~4× less peak memory). Falls back to FromStream + As<T> automatically for >8-bit components.
• ParameterList: Optional encoding parameters. Use indexer to set: params["key"] = "value"
• Image Sources: Accepts SKBitmap, Bitmap, Image, or codec-specific formats (PGM/PPM/PGX streams)
• Thread Safety: Decoding and encoding operations are thread-safe

Fast Random Tile Access (TLM Markers)

NEW in CoreJ2K: Support for TLM (Tile-part Lengths) markers enables O(1) random tile access instead of O(n) sequential parsing. This provides 100-1000x performance improvements for:

• GIS/Map Servers: Sub-second tile delivery (~30s → ~0.03s)
• Medical Imaging: Interactive whole-slide image viewing (~30s → ~0.05s)
• Satellite Imagery: Efficient ROI extraction
• Parallel Processing: Multi-threaded tile decoding

Encoding with TLM

// Create tiled image with TLM markers
var config = new CompleteEncoderConfigurationBuilder()
 .WithTiles(t => t.SetSize(512, 512))
 .WithPointerMarkers(p => p.UseTLM(true)) // Enable TLM
 .Build();

byte[] data = J2kImage.ToBytes(image, config);

Decoding with Fast Access

var decoder = CreateDecoder(stream);

// Check TLM availability
if (decoder.SupportsFastTileAccess())
{
 // O(1) fast path - instant seeking
 decoder.SeekToTile(500); // Jump directly to tile 500
}
else
{
 // O(n) sequential fallback
 decoder.SetTile(x, y); // Parse all previous tiles
}

Performance Impact:

↑ Back to top

Standards & Compliance

Part 1: Core Coding System

CoreJ2K achieves 100% JPEG 2000 Part 1 (ISO/IEC 15444-1) compliance:

Compliance Scores:

• Baseline Profile: ✅ 100%
• Profile 0: ✅ 100%
• Profile 1: ✅ 100%
• Extended Features: ✅ 100%
• Part 14 JPXML: ✅ 100%

Part 2: Extensions

CoreJ2K implements the most commonly used JPEG 2000 Part 2 (ISO/IEC 15444-2) features end-to-end (encode and decode):

Coverage: ~50% — all production-relevant per-sample and multi-component transforms are implemented. Remaining gaps are the wavelet-shape and custom-kernel features (ATK, DFS/ADS).

API note: Pass Part 2 parameters to J2kImage.ToBytes:

// DCO: per-component DC offset
var dco = new DCOMarkerSegment { Offsets = new[] { 10, -3, 20 } };

// NLT: gamma non-linearity
var nlt = new NLTMarkerSegment { Type = NLTType.Gamma, GammaExponent = 2.2 };

// Encode with Part 2 extensions (Rsiz + CAP written automatically)
byte[] data = J2kImage.ToBytes(src, metadata, pl, nltSegments: new[] { nlt }, dcoSegment: dco);

Library Comparison

Quick comparison with major JPEG 2000 libraries:

CoreJ2K Unique Advantages:

• Only open-source .NET library with full Part 1 compliance
• Only open-source library with complete pointer marker read/write
• Memory-safe managed code (no buffer overflows)
• Zero licensing costs

📊 View detailed comparison tables →

JPEG 2000 Specification Compliance

CoreJ2K supports multiple parts of ISO/IEC 15444:

Part 1 covers 99% of real-world JPEG 2000 usage including:

• ✅ Medical imaging (DICOM)
• ✅ Digital cinema (DCP)
• ✅ Geospatial/satellite imagery
• ✅ Digital archives and libraries
• ✅ High-quality image storage

📖 View complete specification details →

↑ Back to top

Support

Resources

• 📚 Documentation: This README and inline code docs
• 💬 Discussions: GitHub Discussions
• 🐛 Bug Reports: GitHub Issues
• 📦 Packages: NuGet Gallery

External Links

• JPEG 2000 Implementation Guide
• ISO/IEC 15444-1 Standard
• SkiaSharp GitHub
• ImageSharp GitHub
• OpenJPEG GitHub

Support the Project

If CoreJ2K helps your project:

• ⭐ Star the repository on GitHub
• 📢 Share with others
• 💰 Donate via cryptocurrency:
  • 👁 ZEC
    
  • 👁 BTC
    

↑ Back to top

Contributing

Contributions welcome! Ways to help:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features in Discussions
• 📝 Improve docs with pull requests
• 🧪 Add tests for better coverage
• 🔧 Fix issues and submit PRs

↑ Back to top

License

BSD 3-Clause License

Copyright (c) 1999-2000 JJ2000 Partners
Copyright (c) 2007-2012 Jason S. Clary
Copyright (c) 2013-2016 Anders Gustafsson, Cureos AB
Copyright (c) 2024-2026 Sjofn LLC

Free to use in commercial and open-source projects. No licensing fees.

→ Full license text

<div align="center">

Made with ❤️ for the .NET community

👁 GitHub stars
👁 GitHub issues
👁 Commit Activity

↑ Back to top

</div>

Appendix: Detailed Comparison Tables

<details> <summary><b>Click to expand full library comparison</b></summary>

Standards Compliance and Features

Technical Characteristics

Performance and Quality

Developer Experience

Use Case Suitability