MaximumConventionalMemory Property

Summary

Maximum size of continuous conventional memory in bytes to use when creating a RasterImage object.

Syntax

Objective-C

C++/CLI

Java

Python

public long MaximumConventionalMemory { get; set; }

@property (nonatomic, assign) long MaximumConventionalMemory

public long getMaximumConventionalMemory(); 
public void setMaximumConventionalMemory( 
   long longValue 
);

public: 
property bool MaximumConventionalMemory { 
   bool get(); 
   void set(bool); 
}

MaximumConventionalMemory # get and set (GlobalMemoryThresholds)

Property Value

Maximum size of continuous conventional memory in bytes to use when creating a RasterImage object. The default value is 0. (Uses as much physical memory as needed).

Remarks

The appropriate setting for MaximumConventionalMemory depends on the system hardware configuration and the number of cores and application types being used. Change this setting if out-of-memory errors occur when running your application.

If a RasterImage object created directly or loaded using RasterCodecs is very large and is created using conventional memory, then a large amount of physical memory is used to hold this image in memory and is not available for other purposes such as OCRing, barcode reading or various other image processing. This is more noticeable in multi-threaded applications where loading several large images in conventional memory can cause out-of-memory errors, even when performing operations that normally would succeed.

Use MaximumConventionalMemory to set the maximum size of the image in memory allowed. Then, creating or loading a new RasterImage will automatically switch to use the disk memory feature of RasterImage (See RasterMemoryFlags.DiskMemory and RasterImage.IsDiskMemory).

The MaximumConventionalMemory value is in bytes but can also be one of the following special values:

Value	Meaning
0	No Maximum. The toolkit will try to use as much conventional memory as needed to create the image. This is the default behavior.
>0	Amount in bytes. If the memory requested is larger, the system will switch to disk or memory mapped files with a small window.
-1	This is a special value designed for multi-threaded operations using multiple RasterImage objects in a document-based application (OCR or document converters). The specific number of bytes depends on the processor(s) being used. See notes below.
-2	This is a special value designed for generic multi-threaded operations using multiple RasterImage objects. The specific number of bytes depends on the processor(s) being used. See notes below.

All other values are currently invalid and will throw an exception.

Special value -1

This is a special value designed for multi-threaded operations using multiple RasterImage objects in a document-based application (OCR or document converters). The specific number of bytes depends on the processor(s) being used.

For x86 processors, the value is 42,187,000 (42 MB).
For x64 processors, the value is calculated dynamically (1.7 GB for each 8 cores, not exceeding the physical memory size).

These values allow a typical document processing application (such as OCR) to process 8 documents (sizes 8.5 by 11 inches at 300 DPI and 32-bits per pixel) to be loaded and processed in conventional memory at the same time. Anything significantly larger than that gets switched to use disk memory mode.

Different factors affect the performance of a particular setting and must be weighed. These include the following factors:

The speed of the machine's hard drive — increases the penalty for using disk memory rather than conventional memory.
Load time — using disk memory consumes more time loading than using conventional memory.
OCR Recognition and other memory heavy image processing — using disk memory improves the performance of these operations because conventional memory is freed for image processing

The LEADTOOLS OCR and document toolkits set the value of MaximumConventionalMemory to -1 to free up as much conventional memory as possible for other operations such as auto-zoning and recognition. This memory size can hold a typical document page (8.5 by 11 inches at 32-bits per pixel) in conventional memory.

Special value of -2

This is a special value designed for generic multi-threaded operations using multiple RasterImage objects. The specific number of bytes depends on the processor(s) being used.

For x86 processors, the value is 1,536,000,000 (1.5 GB)
For x64 processors, the value is calculated dynamically to be the maximum of 1.5 GB and 3/4 of the amount of physical RAM in the system.

Example

using Leadtools; 
using Leadtools.Codecs; 
 
 
public static void MaximumConventionalMemoryTest() 
{ 
	Console.WriteLine("maximumConventionalMemoryTest"); 
	string imageFileName = @"C:\LEADTOOLS22\Resources\Images\Leadtools.pdf"; 
 
	long size = 0; 
 
	using (var rasterCodecs = new RasterCodecs()) 
	{ 
		using (var rasterImage = rasterCodecs.Load(imageFileName, 1)) 
		{ 
			Console.WriteLine("loaded, size:{0} Conventional:{1} Disk:{2}", 
			   rasterImage.DataSize, rasterImage.IsConventionalMemory, rasterImage.IsDiskMemory); 
			Debug.Assert(rasterImage.IsConventionalMemory); 
			Debug.Assert(!rasterImage.IsDiskMemory); 
 
			size = rasterImage.DataSize; 
		} 
 
		// Set maximum conventional size to half of the bitmap's and re-check. Should be disk 
		GlobalMemoryThresholds thresholds = RasterDefaults.GetGlobalMemoryThresholds(); 
		Console.WriteLine("Original GlobalMemoryThresholds.MaximumConventionalMemory = {0}", thresholds.MaximumConventionalMemory); 
		thresholds.MaximumConventionalMemory = size / 2; 
		RasterDefaults.SetGlobalMemoryThresholds(thresholds); 
		thresholds = RasterDefaults.GetGlobalMemoryThresholds(); 
		Console.WriteLine("New      GlobalMemoryThresholds.MaximumConventionalMemory = {0}", thresholds.MaximumConventionalMemory); 
 
		using (var rasterImage = rasterCodecs.Load(imageFileName, 1)) 
		{ 
			Console.WriteLine("loaded, size:{0} Conventional:{1} Disk:{2}", 
				  rasterImage.DataSize, rasterImage.IsConventionalMemory, rasterImage.IsDiskMemory); 
			Debug.Assert(!rasterImage.IsConventionalMemory); 
			Debug.Assert(rasterImage.IsDiskMemory); 
		} 
 
		// Now set to -1 and try to create a 20 by 20 at 32-BPP inch bitmap, should be disk 
		// Reset 
		RasterDefaults.SetGlobalMemoryThresholds(GlobalMemoryThresholds.Default); 
		thresholds = RasterDefaults.GetGlobalMemoryThresholds(); 
		Console.WriteLine("Original GlobalMemoryThresholds.MaximumConventionalMemory = {0}", thresholds.MaximumConventionalMemory); 
		thresholds.MaximumConventionalMemory = -1; 
		RasterDefaults.SetGlobalMemoryThresholds(thresholds); 
		thresholds = RasterDefaults.GetGlobalMemoryThresholds(); 
		Console.WriteLine("New      GlobalMemoryThresholds.MaximumConventionalMemory = {0}", thresholds.MaximumConventionalMemory); 
 
		using (var rasterImage = new RasterImage( 
		   RasterMemoryFlags.Conventional, 
		   20 * 300, 
		   20 * 300, 
		   32, 
		   RasterByteOrder.Bgr, 
		   RasterViewPerspective.TopLeft, 
		   null, 
		   null, 
		   0)) 
		{ 
			Console.WriteLine("created, size:{0} Conventional:{1} Disk:{2}", 
				  rasterImage.DataSize, rasterImage.IsConventionalMemory, rasterImage.IsDiskMemory); 
			Debug.Assert(!rasterImage.IsConventionalMemory); 
			Debug.Assert(rasterImage.IsDiskMemory); 
		} 
 
		// finally create 8.5 by 11 at 300 DPI, should be conv 
		using (var rasterImage = new RasterImage( 
		   RasterMemoryFlags.Conventional, 
		   (int)(8.5 * 300), 
		   11 * 300, 
		   32, 
		   RasterByteOrder.Bgr, 
		   RasterViewPerspective.TopLeft, 
		   null, 
		   null, 
		   0)) 
		{ 
			Console.WriteLine("created, size:{0} Conventional:{1} Disk:{2}", 
					 rasterImage.DataSize, rasterImage.IsConventionalMemory, rasterImage.IsDiskMemory); 
			Debug.Assert(rasterImage.IsConventionalMemory); 
			Debug.Assert(!rasterImage.IsDiskMemory); 
		} 
	} 
 
	// Reset 
	RasterDefaults.SetGlobalMemoryThresholds(GlobalMemoryThresholds.Default); 
}

Requirements

Target Platforms

Reference

Leadtools Namespace

Download our FREE evaluation

Help Version 22.0.2023.5.16

Leadtools Assembly

Introduction

Getting Started

Namespaces

Leadtools Namespace

Leadtools.ImageProcessing Namespace

Assemblies