Introduction

Color Conversion SDK provides functions for converting between color-spaces using different methods and options; the SDK supports the following conversions:

Source Color Space | Can be converted to | Conversion method | Recommended
RGB | Any other color space. | Built-in, ICC profiles, or emulation tables, depending on the destination color space. |
BGR | Any other color space. | Built-in, ICC profiles, or emulation tables, depending on the destination color conversion. |
YUV | Any other color space. | 1. Built in. |
CMYK | Any other color space. | 1.Emulation Tables (one way CMYK => RGB) 2.ICC Profiles. 3.Built in. | The best conversion is through the ICC Profiles (USE_ICC), this is because of the nature of the CMYK conversion, which is machine-dependant. You can use profiles that vary in the degree of black color (ink) generation.
HSV | Any other color space. | 1. Built in. |
HLS | Any other color space. | 1. Built in. |
YIQ | Any other color space. | 1. Built in. |
CMY | Any other color space. | 1.Built in. 2.ICC Profiles |
LAB | Any other color space. | 1. Emulation Tables (one way CMYK => RGB). 2. ICC Profiles. 3.Built in. | For two-way conversion, RGB to LAB and vice versa, the best solution is with emulation tables and Built in conversions, because the colors are preserved better. However for one way you can use ICC profiles.
XYZ | Any other color space. | 1. Built in. |
YCCK | Any other color space. | 1. Built in. |
Y41P | Any other color space. | 1. Built in. |
UYVY | Any other color space. | 1. Built in. |
YUY2 | Any other color space. | 1. Built in. |
YVU9 | Any other color space. | 1. Built in. |
YCC | Any other color space. | 1. Built in. |

The SDK uses the following methods for conversion between color conversions:

ICC color conversion profiles

Emulation Tables

LEAD’s Built-in conversion

Each of the conversion methods listed above can be customized; for example, conversion between RGB to CMY with ICC color conversion profiles can be done with either the built-in profiles or with user-supplied profiles as shown in the table above.

Please note that if you have purchased an eval version of a LEADTOOLS toolkit, this help file contains the same information as the help file included in the standard release toolkit. Consequently, references to the .DLL and .LIB files contain an N designation. The .DLL and .LIB files included with the evaluation toolkit contain an E designation. Therefore, any references in the help file to xx14N.DLL or xx_N.LIB files refer to the corresponding xx14E.DLL or xx_E.LIB files. For example, if the help file re


Example Programs

The Demo can load TIFF images in RGB, CIELab and CMYK formats and converts between them, the conversion can be customized using the CMYK and CIELab dialogs, which can let you specify the conversion method and the properties of that conversion.

Note:

You can run the example programs on your system by clicking the appropriate buttons in online help. If you try to run an example program that is not on your system, an error message will appear.

CSDEM32

CSDEM32 is the Color Conversion example program. It uses pull-down menus to demonstrate most of the LEADTOOLS Color Conversion features in one application.


Version History

Current version: | 14
Last update: | May 18, 2005

Changes from Version 13 to Version 14

Version 13


Changes from Version 13 to Version 14

Version 14 of the LEADTOOLS Color Conversion API has changed from Version 13 as follows:

LEADTOOLS Color Conversion API now supports UNICODE.

Changed Structures:

CONVERSION_PARAMS takes 2 new members.

Changed Functions:

L_ClrConvertToBitmap takes 1 new parameter.

L_ClrConvertDirectToBitmap takes 1 new parameter.


Version 13

Version 13 is the first version of LEADTOOLS Color Conversion API.

The rest of this topic lists the new functions in this toolkit.

L_ClrConvert

L_ClrConvertDirect

L_ClrConvertDirectToBitmap

L_ClrConvertToBitmap

L_ClrDlg

L_ClrFree

L_ClrInit

L_ClrIsValid

L_ClrSetConversionParams


Copyright notice

Copyright Notices

©Copyright LEAD Technologies, Inc. 1991-2005. ALL RIGHTS RESERVED

Portions of the PCDLIB32.DLL, PCDLIB.DLL, LFFPX7.DLL, LFKODAK.DLL, EKFPIXJPEG140.DLL, PDC_SDK.DLL, PROFIRE.DLL, DC120V154_32.DLL, LFDCR14N.DLL, DCSPROBACK.DLL, DCSPRO3SLR.DLL, LFDCS14N.DLL, and LFKDC14N.DLL files contain material that is ©Copyright Eastman Kodak Company, 1996-2001. This software is based in part on the work of the Independent JPEG Group.

Portions of the LFCRW14N.DLL, LTCMP14.DLL, CDSDK.reg, CDSDK.dll, CDRAPCLS.dll, czs_ui.dll, deimg.dll, deImg010.dll, deImg110.dll, deImg153.dll, deimg301.dll, deimg401.dll, deImg404.dll, deimg602.dll, Deimg603.dll, DeImgd60.dll, pscAdimg.dll, pscCllct.dll, pscCStUI.dll, pscDcd.dll, pscDevUI.dll, pscDvlp.dll, Pscl2STI.dll, pscll.dll, pscParse.dll, pscSetup.dll, psdkdll.dll, psdkReg.dll, psParse.dll. file contain material that is © Canon, Inc. 2002

Portions of the LFFPX7.DLL and LFKODAK.DLL files contain material that is ©Copyright Hewlett Packard, 1996.

Portions of the OCR/ICR/OMR Features and the help file for the OCR/ICR/OMR Features are ©Copyright Scansoft, Inc. 1995-2003. ALL RIGHTS RESERVED

Portions of the Barcode Modules contain material that is ©Copyright Axtel Inc., 1999.

Portions of the LEADTOOLS PDF Plug in and the LEADTOOLS Vector Imaging Pro are ©Copyright 1996, 2000 Artifex Software Inc. All rights reserved.

File filters for decoding MrSID ® and DjVu ® formats are provided under a license from Lizardtech, Inc.

The "FlashPix" format uses Microsoft's OLE structured storage.

Portions of the DICOM help files in Medical Imaging product line are reprinted with permission from the National Electrical Manufacturers Association ©Copyright 1998 by the National Electrical Manufacturers Association. All rights including translation into other languages, reserved under the Universal Copyright Convention, the Berne Convention or the Protection of Literacy and Artistic Works, and the International and Pan American Copyright Conventions.

Portions of LEADTOOLS Data Security Add On contain software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/), including cryptographic software written by Eric Young (eay@cryptsoft.com) and by Tim Hudson (tjh@cryptsoft.com). Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved. Copyright Tim Hudson 1995-1998 (tjh@cryptsoft.com) All rights reserved.

Portions of LEADTOOLS Data Security Add On contain software based on the MD5 Message Digest Algorithm developed by RSA Data Security, Inc.. Copyright (c) 1991-92 RSA Data Security, Inc. All Rights Reserved.

Portions hereof licensed under US patent 5,327,254 and foreign counterparts.

Trademarks

LEAD® and LEADTOOLS® are registered trademarks of LEAD Technologies, Inc.
Microsoft, Windows, Windows NT, Visual Basic, Visual FoxPro, and Microsoft Access are either trademarks or registered trademarks of the Microsoft Corporation.
OS/2® is a registered trademark of International Business Machines Corporation.

TextBridge®OCR is a registered trademark of Scansoft, Inc.

ISIS® is a registered trademark of Pixel Translations, Inc.

ScanAhead™ is a trademark of Pixel Translations, Inc.

FlashPix™ is a trademark of Eastman Kodak Company.

All other brand or product names used in this online help are trademarks of their respective holders.

Address and Contact Information

LEAD Technologies, Inc.
Suite 400
1201 Greenwood Cliff
Charlotte, NC 28204

(704) 332-5532
FAX: (704) 372-8161
E-mail: support@leadtools.com
Technical support: (704) 372-9681 or support@leadtools.com
Home page: http://www.leadtools.com


Programming with LEADTOOLS Color Space Functions

Programming with LEADTOOLS Color Conversion Functions

Once LEADTOOLS Color Conversion is installed to the system, the user is ready to begin programming. LEADTOOLS provides functions for converting between color-spaces using different methods and options. The toolkit supports conversions among RGB, BGR, YUV, CMYK, HSV, HLS, YIQ, CMY, LAB, YCCK, Y41P, UYVY, YUY2, YVU9, and YCC color spaces.

LEADTOOLS Color Conversion provides two methods to accomplish conversion:

Direct Conversion.

Indirect Conversion.

Direct Conversion

This process doesn't require any initialization code. L_ClrConvertDirect can be called to convert directly between two color spaces. This function uses built-in equations and options and is the same as using the second methods with USE_BUILTIN.

L_ClrConvertDirectToBitmap can also be used to convert directly, however this function will return a LEAD BITMAPHANDLE representation of the destination buffer. This function is valid for conversions from any color space to RGB or BGR.

Indirect Conversion

To begin using the available indirect conversion feature in the LEADTOOLS Color Conversion toolkit, the user should declare an instance of CONVERSION_PARAMS structure; then fill it depending on the conversion process options. The user may optionally utilize emulation tables. For more information, refer to Emulation Tables.

Next, the user should initialize a color conversion handle. For more information refer to Initializing a Color Conversion Handle.

After the user has established a Color Conversion handle, he or she is ready to convert image data from a specific one-color conversion model to another. For more information, refer to Conversion Process.

When the handle to the Color Conversion is no longer needed, it should be freed. For more information, refer to Freeing the Color Conversion Handle.

The user can also initiate a conversion visually with L_ClrDlg, which brings up a color space option dialog. Based on the option set in that dialog, a color handle will be returned and/or the option specified in the dialog packed in CONVERSION_PARAMS instance.


Initializing a Color Conversion Handle

To begin using the LEADTOOLS Color Conversion toolkit, the user must initialize a color conversion handle. This is done by calling the L_ClrInit function. Each call to the L_ClrInit function will create a color conversion handle of type HANDLE. This handle is passed to many of the LEADTOOLS Color Conversion API functions, so this function must be called before calling many functions in case of indirect conversion.

Another way to initialize a color conversion handle is by calling L_ClrDlg, which brings up a color space option dialog. Based on the option set in that dialog, a color handle will be returned and/or the option specified in the dialog packed in CONVERSION_PARAMS instance.

To check the validity of the created color conversion handle call the L_ClrIsValid function.


Conversion Process

After the user has established a color conversion handle and set the conversion process options, he or she can start converting with the L_ClrConvert function.

L_ClrConvert can be called many times for the same color conversion handle, with the possibility of adjusting the conversion options using the L_ClrSetConversionParams function.

To align the input and output buffers, refer to Alignment parameters

For information on YUV Conversion, refer to Generic YUV Conversion.


Alignment parameters

Conversion functions, L_ClrConvert, and L_ClrConvertDirect, take two alignment parameters, one for the input buffer, and the other one for the output buffer. Non-zero values for these parameters indicate that the input and output buffer's scanlines (rows of pixels) are padded with extra non-image bytes so that the total number of bytes in each scanline is a multiple of nInAlign (input buffer) or nOutAlign (output buffer).

For example, consider having a 3 column x 1 row CMY image buffer (9 bytes total) to be converted to RGB:

If the input buffer is not aligned and you need the output buffer to be aligned by 4 bytes (a memory need), call L_ClrConvert or L_ClrConvertDirect with:

nInAlign = 0
nOutAlign = 4

If the above 3 column x 1 row CMY input buffer is 4-bytes aligned (12 bytes total), and the output buffer is not to be aligned call L_ClrConvert or L_ClrConvertDirect with:

nInAlign = 4
nOutAlign = 0

If the above 3 column x 1 row CMY input buffer is 4-bytes aligned (12 bytes total), and the output buffer needs to be 4-bytes aligned, call L_ClrConvert or L_ClrConvertDirect with:

nInAlign = 4
nOutAlign = 4

Any other combination may be used for any supported color conversions. In any case the user should allocate enough memory for the actual pixels and the additional alignment bytes if any.


Freeing the Color Conversion Handle

When the Color conversion handle is no longer needed, the user must free the handle by calling the L_ClrFree function. At this point the Color Conversion handle becomes invalid. Before starting another conversion process, the user must establish a new Color Conversion handle by calling the L_ClrInit function.


Files To Be Included With Your Application

The installation procedure creates a directory tree for the LEADTOOLS files, and adds the demonstration programs and online help to your desktop. You specify the root directory during installation. The following subdirectory for the Color Conversion API Features is created:

REDIST\

Redistributable Color Conversion files.

Note: | You may not copy or redistribute any of the following files without obtaining the proper license. In some cases, the license is included with your initial purchase of LEADTOOLS. In other cases, you must obtain a license from a third party or enter into a royalty agreement with LEAD to obtain the proper license. For these special licensing situations, see the notes below accompanying the specific file.
Note: | You may not distribute the header files with your application, and you may not provide software development capabilities in your application.

The following table summarizes the files you must include on your distribution diskettes to support the LEADTOOLS functions. Most files in the table are optional. 32-bit DLLs are listed. These files are referred to as "Redistributables" in the License Agreement.

Please note that LTKRN is required for ALL API applications. For more information on LTKRN and other files for the Main API, refer to Files To Be Included With Your Application .

Redistributable Name: | Explanation: | If you are using a standard release without Unicode, the files to use are: | If you are using a standard release with Unicode, the files to use are: | If you are using an evaluation release without Unicode, the files to use are: | If you are using an evaluation release with Unicode, the files to use are:
LTCLR | LEADTOOLS Color Conversion. The Header File is LTCLR.H. Also requires LTKRN. | DLL: LTCLR14N.DLL Library: LTCLR_N.LIB. | DLL: LTCLR14NU.DLL Library: LTCLR_NU.LIB. | DLL: LTCLR14E.DLL Library: LTCLR_E.LIB. | DLL: LTCLR14EU.DLL Library: LTCLR_EU.LIB.

The following files are provided for customizing emulation tables:

Source

Convert to

src_cmyk_image.tif

RGB image (i.e. dst_cmyk2rgb_image.tif)

src_rgb_image.tif

Lab image ( i.e. dst_rgb2lab_image.tif)

src_lab_image.tif

RGB image (i.e. dst_lab2rgb_image.tif)

If custom emulation tables are to be used, you can convert the above files using your own or any third party application to the needed color space. A set of images already converted and ready for use (dst_cmyk2rgb_image.tif, dst_rgb2lab_image.tif, and dst_lab2rgb_image.tif), is provided. However, using the provided set of converted images will produce the same results as the built-in emulation tables.


Installation Directory

The installation procedure creates a directory tree for the LEADTOOLS files, and adds the demonstration programs and online help to your desktop. You specify the root directory during installation.

The following is a list of the subdirectories in the root directory:

ACROBAT | LEADTOOLS manuals in the PDF format, which you can view and print using Adobe Acrobat. These files are optional and are available when installing from the CD-ROM.
BIN | Executable files for the demonstration programs.
HELP | Online help files.
IMAGES | Sample images and databases containing images.
EXAMPLES\DLL | One subdirectory for each example API program.
EXAMPLES\OCX | One subdirectory for each example ActiveX program.
EXAMPLES\COM | One subdirectory for each example COM program.
EXAMPLES\CLASSLIB | One subdirectory for each example Class Library program.
EXAMPLES\RES | Resource files for the example programs.
INCLUDE | Header files, BAS files, and the ActiveX's MFC interface files for versions of Visual C++ earlier than 4.0.
INCLUDE\CLASSLIB | Header files for the Class Library
LIB | Library files.
REDIST | Redistributable files. These are copies of the LEADTOOLS files and other files that you may need to distribute with your application. For exact information about required files, refer to Files To Be Included With Your Application.


Technical Support

As a registered user, free technical support is available. You must register your software to receive any technical support. Technical support is available 9 a.m. through 6 p.m. Eastern Standard Time. If you are calling by phone, please be at your computer. You can also contact us through the following methods:

Phone: | (704) 372-9681
E-mail: | support@leadtools.com
FAX: | (704) 372-8161
Home page: | http://www.leadtools.com
FTP: | ftp.leadtools.com

You can also contact LEAD by mail at:

LEAD Technologies, Inc.
Atten: Technical Support
Suite 400
1201 Greenwood Cliff
Charlotte, NC 28204

Before calling technical support, please look in the online documentation and the example programs for an answer to your question.


Color Conversion API Function Groups

Color Conversion API Functions:

L_ClrConvert

L_ClrConvertDirect

L_ClrConvertDirectToBitmap

L_ClrConvertToBitmap

L_ClrDlg

L_ClrFree

L_ClrInit

L_ClrIsValid

L_ClrSetConversionParams


Data Types

Basic Data Types and Keywords

LEADTOOLS Basic Data Types

Keywords Used in Declarations

COLOR CONVERSION Structures

WHITEPOINT

CMYK_PARAMS

YUV_PARAMS

LAB_PARAMS

CONVERSION_PARAMS

Structures Used with Input and Output Functions

WINDOWS Structures


LEADTOOLS Basic Data Types

LEADTOOLS has defined the following basic data types for portability:

Data Type | Definition and Usage
L_BITFIELD | Defined as L_UINT; used as a bit field.
L_BOOL | Defined as L_UINT; used as a Boolean value.
L_CHAR | Defined as char; used as a signed 8-bit integer.
L_DOUBLE | Defined as double; used as a double precision floating point number.
L_FLOAT | Defined as float; used as a floating point number.
L_INT | Defined as int; used as a signed integer, 16-bits or larger.
L_INT16 | Defined as short; used as a signed 16-bit integer.
L_INT32 | Defined as long; used as a signed 32-bit integer.
L_UCHAR | Defined as unsigned char; used as an unsigned 8-bit integer.
L_UINT | Defined as unsigned; used as an unsigned integer, 16-bits or larger.
L_UINT16 | Defined as unsigned short; used as an unsigned 16-bit integer.
L_UINT32 | Defined as unsigned long; used as an unsigned 32-bit integer.
L_VOID | Defined as void; used as a void.
L_COMP | Defined as L_UINT; used as a handle to a computer
L_MEDIA | Defined as L_VOID L_FAR *; used as a void pointer
L_TYPE | Defined as L_UINT.
L_FLAGS | Defined as L_UINT.
L_TCHAR | Defined as either char or TCHAR. If FOR_UNICODE is defined, then L_TCHAR will be defined as TCHAR.


Keywords Used in Declarations

LEADTOOLS uses the following keywords in declarations of functions, structures, and datatypes:

Keyword | Definition and Usage
L_FAR | Defined as nothing; used as a placeholder.
L_HUGE | Defined as nothing; used as a placeholder.
L_EXPORT | Defined as nothing; used as a placeholder.
L_PASCAL | Defined as nothing; used as a placeholder.
EXT_FUNCTION | Defined as WINAPI; used as an attribute for all toolkit functions.
pEXT_FUNCTION | Defined as EXT_FUNCTION L_FAR *; used as an attribute when defining pointers to toolkit functions.
EXT_CALLBACK | Defined as _cdecl L_FAR; used as an attribute for all toolkit callback functions.
pEXT_CALLBACK | Defined as EXT_CALLBACK L_FAR *; used as an attribute when defining pointers to toolkit callback functions.


CMYK_PARAMS

typedef struct _CMYK_PARAMS
{
L_UINT uStructSize;
L_INT nGcr_level; /* value between 0.0 and 1.0 */
L_INT nMask;
} CMYK_PARAMS, *LPCMYK_PARAMS;

The CMYK_PARAMS structure provides information about CMYK conversion properties.

Parameter | Description
uStructSize | Size of this structure.
nGcr_level | GCR (Gray Component Replacement) value. Possible values are between 0 and 1000.
nMask | Masking value, currently there is only one used value:
 | Value | Meaning
 | CMYK_GCR | Change the nGcr_level.

Comments

LPCMYK_PARAMS is a pointer to a CMYK_PARAMS structure. Where the function parameter type is LPCMYK_PARAMS, you can declare a CMYK_PARAMS variable, update the structure's fields, and pass the variable's address. Declaring a LPCMYK_PARAMS variable is necessary only if your program requires a pointer.

CMYK_PARAMS is used with the CONVERSION_PARAMS structure.

The mask value will be used only when updating the CMYK conversion using L_ClrSetConversionParams function.

The higher the GCR, the more the gray components are replaced with blackness.


CONVERSION_PARAMS

typedef struct _CONVERSION_PARAMS
{
L_UINT uStructSize ;
L_INT nActiveMethod;
LPWHITEPOINT pWpoint;
L_TCHAR sInputProfile[MAX_PATH];
pMEMICCPROFILE pMemInputProfile;
L_TCHAR sOutputProfile[MAX_PATH];
pMEMICCPROFILE pMemOutputProfile;
L_TCHAR sDstInputTable[MAX_PATH];
LPCMYK_PARAMS pCmykParams;
LPYUV_PARAMS pYuvParams;
LPLAB_PARAMS pLabParams;
L_INT nMethod;
L_INT nQuantization; /* Reserved, must be 8*/

} CONVERSION_PARAMS, *LPCONVERSION_PARAMS;

Parameter | Description
uStructSize | Size of this structure.
nActiveMethod | Active conversion method. Possible values should be one and only one of the following:
 | Value | Meaning
 | USE_BUILTIN | [1] For equations.
 | USE_ICC | [2] For profiles.
 | USE_CUSTOM_ICC | [4] For custom profiles.
 | USE_ET | [8] For emulation tables.
 | USE_CUSTOM_ET | [16] For custom emulation tables
 | USE_AUTO | [32] For best conversion.
 | Since the nMethod member may contain more than one conversion method, this member is used to determine which method to use in the conversion process.
pWpoint | Pointer to a WHITEPOINT structure that describes the white point.
sInputProfile | Character string that contains the input profile name, used with USE_CUSTOM_ICC active conversion method (nAvtiveMethod membet).
pMemInputProfile | Pointer to a MEMICCPROFILE structure that contains information about the input memory profile to be used as the input profile.
sOutputProfile | Character string that contains the output profile name, used with USE_CUSTOM_ICC active conversion method (nAvtiveMethod membet).
pMemOutputProfile | Pointer to a MEMICCPROFILE structure that contains information about the input memory profile to be used as the output profile.
sDstInputTable | Character string that contains the destination image name for emulation, used with USE_CUSTOM_ICC active conversion method (nAvtiveMethod membet).
pCmykParams | Pointer to a CMYK_PARAMS structure that describes the CMYK conversion properties. If this parameter is NULL, default values are assumed.
pYuvParams | Pointer to a YUV PARAMS structure that describes the YUV conversion properties. If this parameter is NULL, default values are assumed.
pLabParams | Pointer to a LAB PARAMS structure that describes the CIELab conversion properties. If this parameter is NULL, default values are assumed.
nMethod | Conversion method. When the conversion method is used with the L_ClrInit function. Possible values are:
 | Value | Meaning
 | USE_BUILTIN | [1] For equations (default).
 | USE_ICC | [2] For profiles.
 | USE_CUSTOM_ICC | [4] For custom profiles.
 | USE_ET | [8] For emulation tables. This option is valid for CMYK to RGB, RGB to CIELab, and CIELab to RGB conversions only.
 | USE_CUSTOM_ET | [16] For custom emulation tables. This option is valid for CMYK to RGB, RGB to CIELab, and CIELab to RGB conversions only.
 | USE_AUTO | [32] For best conversion
 | USE_ALL | [63] For all of the above

The nMethod can be used to initialize the SDK with more than one conversion method. Therefore, the nActiveMethod member should be set with the conversion method to be used.

The L_ClrSetConversionParams can be used to switch between these conversions by specifying CHANGE_ACTIVE_METHOD for this member.

When the conversion method is used with the L_ClrSetConversionParams function, the possible values are:

Value

Meaning

CHANGE_ACTIVE_METHOD

[1] Change the active method.

CHANGE_CUSTOM_PRO_FILES

[2] Change profiles.

CHANGE_WHITE_POINT

[4] Change white point.

CHANGE_ET

[8] Change emulation tables.

CHANGE_CMYK

[16] Change CMYK parameters.

CHANGE_YUV

[32] Change YUV parameters.

CHANGE_ALL

[63] Change all of the above.

nQuantization

Quantization level, must be 8.

Comments

In the case the conversion is from CMYK to RGB or RGB to/from CIELab, and nActiveMethod member is set to USE_CUSTOM_ET, the user should specify the full path to the images in the sDstInputTable member. The following table shows the image dimensions to be used in the emulation tables that are passed to the sDstInputTable member.

Conversion | Image Dimensions
CMYK to RGB | 289x289 RGB TIF image
RGB to CIELab | 190x190 CIELab TIF image
CIELab to RGB | 190x190 RGB TIFF image

There are cmyk_src_image.tif, rgb_src_image.tif, and lab_src_image.tif images distributed with the library. They can be used and converted, using any tool, to their RGB, CIELab, and RGB equivalents respectively.

When using the custom ICC engine (USE_CUSTOM_ICC set in the nMethod member), there are two ways to specify the source and/or destination profiles:

Profiles from disk files: sInputProfile and sOutputProfile are used.

Profiles resident in memory: pMemInputProfiel and pMemOutputProfile are used.

Any combination of the input and output profiles is allowed. For example, a file source profile can be used with a memory destination profile.

If all four options for source and destination profiles are set (sInputProfile, sOutputProfile, pMemInputProfile and pMemOutputProfile), the memory profiles get the highest priority. Therefore, if you set both sInputProfile and pMemInputProfile, only the source specified in pMemInputProfile will be used. In addition, is only a source profile is provided, either file or memory, without a destination profile, the ICC engine will a default destination profile.


LAB_PARAMS

typedef struct
{
L_UINT uStructSize;
L_INT nMask;
L_INT L_offset;
L_INT L_range;
L_INT a_offset;
L_INT a_range;
L_INT b_offset;
L_INT b_range;
} LAB_PARAMS, *LPLAB_PARAMS;

The LAB_PARAMS structure provides information about CIELab conversion properties.

Parameter | Description
uStructSize | Size of this structure.
nMask | Masking value:
 | Value | Meaning
 | LAB_L_OFFSET | Change L_offset value
 | LAB_L_RANGE | Change L_range value
 | LAB_a_OFFSET | Change a_offset value
 | LAB_a_RANGE | Change a_range value
 | LAB_b_OFFSET | Change b_offset value
 | LAB_b_RANGE | Change b_range value
L_offset | L component offset
L_range | L componnt range
a_offset | a component offset
a_range | a Component range
b_offset | b Component offset
b_range | b Component range

Comments

The gamut capacity is expressed as an offset and range, with the exception of the minimum and maximum values. For example, in the T.42 CIELab, the communication conversion can be expressed as:

L_offset = 0;
L_range = 100
a_offset = 128
a_range = 170
b_offset = 96
b_range = 200

You may refer to www.itu.int.com for more information on the CIELab color conversion.

LAB_PARAMS is used with the CONVERSION_PARAM structure.

The mask value will be used only when updating the CMYK conversion using L_ClrSetConversionParams function.


WHITEPOINT

typedef struc _WHITEPOINT
{
L_INT nWhitePoint;
L_DOUBLE xWhite;
L_DOUBLE yWhite;
} WHITEPOINT, L_FAR* LPWHITEPOINT;

The WHITEPOINT structure specifies the spectrum of the white color.

Parameter | Description
nWhitePoint | Common white points. Possible values:
 | Value | Meaning
 | CIELAB_D50 | D50 white point.
 | CIELAB_D55 | D55 white point.
 | CIELAB_D65 | D65 white point.
 | CIELAB_D75 | D75 white point.
 | CIELAB_D93 | D93 white point.
 | CIELAB_CUSTOM | Use the values of xWhite and yWhite members.
 | CIELAB_DEFAULT | Dfault (D55) white point.
xWhite | X value between 0.0 and 1.0.
yWhite | y value between 0.0 and 1.0.

Comments

LPWHITEPOINT is a pointer to a WHITEPOINT structure. Where the function parameter type is LPWHITEPOINT, you can declare a WHITEPOINT variable, update the structure's fields, and pass the variable's address. Declaring a LPWHITEPOINT variable is necessary only if your program requires a pointer.

WHITEPOINT is used with the CONVERSION_PARAMS structure.

Any of the predefined white points can be used, or custom x and y values can be used in an xyY system with CIELAB_CUSTOM, Y is always 1.0.


WINDOWS Structures

HANDLE

Handle is a standard Windows structure. For further information concerning HANDLE, please refer to the Microsoft SDK documentation or your compiler's documentation.


YUV_PARAMS

typedef struct
{
L_UINT uStructSize;
L_INT nMask;
L_INT nUh;
L_INT nUv;
L_INT nVh;
L_INT nVv;
L_INT *pOffsets;
L_INT nMacroPixel;
L_INT nRange;
L_BOOL bPlanar;
} YUV_PARAMS, *LPYUV_PARAMS;

The YUV_PARAMS structure provides information about YUV conversion properties. It is used to describe some YUV format to be converted to another color conversion. For more information see Generic YUV Conversion.

Parameter | Description
uStructSize | Size of this structure
nMask | Masking value. This can be any combination of the following values:
 | Value | Meaning
 | YUV_UH | Change the nUh value
 | YUV_UV | Change the nUv value
 | YUV_VH | Change the nVh value
 | YUV_VV | Change the nvV value
 | YUV_OFFSETS | Change the pOffsets value
 | YUV_MACROPIXEL | Change the nMacroPixel value
 | YUV_RANGE | Change the nRange value
nUh | Integer that represents the horizontal subsampling period of U
nUv | Integer that represents the vertical subsampling period of U.
nVh | Integer that represents the horizontal subsampling period of V.
nVv | Integer that represents the vertical subsampling period of V.

pOffsets | Pointer to integer array that represents offsets of the byte ordering for the proposed YUV format. When bPlanar is TRUE, the only useful data is pOffsets[0] which will indicate what is the arrangement of the YUV buffer. Possible values are:
 | Value | Meaning
 | PLANAR_YUV | Planes order, Y, U, V
 | PLANAR_YVU | Planes order, Y, V, U
 | PLANAR_UYV | Planes order, U, Y, V
 | PLANAR_UVY | Planes order, U, V, Y
 | PLANAR_VYU | Planes order, V, Y, U
 | PLANAR_VUY | Planes order, V, U, Y
nMacroPixel | Macropixel size, which is the number of pixels in the unit pixels group.
nRange | Integer represents the range of values in the input buffer; full range, or 16-240 (YUVRANGE_FULL, and YUVRANGE_16_240).
bPlanar | Value that indicates whether the buffer consists of the Y plane, V plane and U plane. Possible values are:
 | Value | Meaning
 | TRUE | The buffer consists of the Y, U, and V planes.
 | FALSE | The buffer does not consist of the Y, U, and V planes.

Comments

LPYUV_PARAMS is a pointer to a YUV_PARAMS structure. Where the function parameter type is LPYUV_PARAMS, you can declare a YUV_PARAMS variable, update the structure's fields, and pass the variable's address. Declaring a LPYUV_PARAMS variable is necessary only if your program requires a pointer.

YUV_PARAMS is used with the CONVERSION_PARAMS structure.


Return Codes

For a list of all possible return codes for LEADTOOLS Color Conversion API functions, refer to LEADTOOLS API Return Codes in the Main API help file.


Built-in Conversion

The Color Conversion API provides built-in conversion. To do a built-in conversion, follow the steps below:

1.

Define the following global variables:

HANDLE ClrHandle;
CONVERSION_PARAMS params;
WHITEPOINT WPoint;
L_UCHAR *pRGBData;
L_UCHAR *pLABData;
L_INT nWidth;
L_INT nHeight;
L_INT nInAlign;
L_INT nOutAlign;

2.

Set the conversion options by filling a CONVERSION_PARAMS structure:

ZeroMemory(&params, sizeof(CONVERSION_PARAMS));

params.pWpoint = &WPoint;
params.uStructSize = sizeof(CONVERSION_PARAMS);
params.pWpoint->nWhitePoint = CIELAB_D50;
params.nQuantization = 8;
params.nMethod = USE_BUILTIN;
params.nActiveMethod = USE_BUILTIN;
params.pWpoint->xWhite = 0.0;
params.pWpoint->yWhite = 0.0;

3.

Initialize the color conversion handle with L_ClrInit():

L_ClrInit(&ClrHandle, CCS_RGB, CCS_LAB, &params);

4.

Convert from RGB to CIELab:

L_ClrConvert(ClrHandle, pRGBData, pLABData, nWidth, nHeight, nInAlign, nOutAlign);

5.

At the end, free the color conversion handle:

L_ClrFree(ClrHandle);


Color Conversion to an Image

The Color Conversion API provides direct color conversion to an image. To do a conversion, follow the steps below:

1.

Define the following global variables:

BITMAPHANDLE LeadBitmap;
L_UCHAR *pLABData;

2.

To convert 320x240 24 bit CIELab data to a LEAD bitmap with RGB24, do the following:

L_ClrConvertDirectToBitmap(CCS_LAB, CCS_RGB, pLABData, &LeadBitmap, sizeof(BITMAPHANDLE), 320, 240, 0, 0);

// You can use the Lead bitmap as you want

3.

At the end, free the bitmap handle:

L_FreeBitmap (&LeadBitmap);


Conversion Given an ICM Profile

1.

Define the following global variables:

HANDLE ClrHandle;
CONVERSION_PARAMS params;
BYTE RGBColor[3];
BYTE ColorSpace[4];

2.

Set the conversion options by filling a CONVERSION_PARAMS structure:

memset(&params, 0, sizeof(CONVERSION_PARAMS));

params.uStructSize = sizeof(CONVERSION_PARAMS);
params.nMethod = USE_CUSTOM_ICC;
params.nActiveMethod = USE_CUSTOM_ICC;
params.pWpoint = (LPWHITEPOINT)malloc(sizeof(WHITEPOINT));
params.pWpoint->nWhitePoint = CIELAB_D50;

params.pMemInputProfile = NULL;
params.pMemOutputProfile = NULL;

lstrcpy(params.sInputProfile, TEXT("C:\\MyCMYKProfile.ICM"));
lstrcpy(params.sOutputProfile, TEXT("C:\\MyRGBProfile.ICM"));

3.

Initialize the color conversion handle with L_ClrInit():

L_ClrInit(&ClrHandle, CCS_CMYK, CCS_RGB, &params);

4.

Now, do the conversion:

ColorSpace[0] = 100;
ColorSpace[1] = 100;
ColorSpace[2] = 100;
ColorSpace[3] = 100;

L_ClrConvert(ClrHandle, ColorSpace, RGBColor, 1, 1, 0, 0);

5.

At the end, free the color conversion handle:

L_ClrFree(ClrHandle);


Dialog Based Initialization

The Color Conversion API provides a color space dialog that can be used to initialize a conversion. To do a dialog based initialization follow the steps below:

1.

Define the following global variables:

HANDLE ClrHandle;
L_UCHAR *pRGBData;
L_UCHAR *pLABData;
L_INT nWidth;
L_INT nHeight;
L_INT nInAlign;
L_INT nOutAlign;

2.

Display the color space dialog box to initialize as follows:

L_ClrDlg(DLG_LAB, NULL, &ClrHandle, NULL);

3.

Convert from RGB to CIELab as follows:

L_ClrConvert(ClrHandle, pRGBData, pLABData, nWidth, nHeight, nInAlign, nOutAlign);

4.

At the end, free the color conversion handle:

L_ClrFree(ClrHandle);


Emulation Tables

The LEAD Color Conversion toolkit provides emulation tables as one of its conversion methods. This method however is provided only for the following conversions:

CMYK to RGB.

CIELab to RGB

and RGB to CIELab

The Emulation tables' method supports both built-in and custom options. For built-in emulation tables, use the USE_ET option. The custom emulation tables' option, USE_CUSTOM_ET, provides custom conversion using user-supplied images, converted from the source images distributed with the library, by any tool, as follows:

Conversion | Source | Convert to
CMYK to RGB | src_cmyk_image.tif | RGB image (i.e. dst_cmyk2rgb_image.tif)
RGB to Lab | src_rgb_image.tif | Lab image (i.e. dst_rgb2lab_image.tif)
Lab to RGB | src_lab_image.tif | RGB image (i.e. dst_lab2rgb_image.tif)

A set of images, already converted and ready for use (dst_cmyk2rgb_image.tif, dst_rgb2lab_image.tif, and dst_lab2rgb_image.tif), is provided. However, using the provided set of converted images will produce the same results as the built-in emulation tables.

The code below shows how a conversion can be done using the built-in tables:

L_VOID Tables_Convert_CMYKToRGB(L_UCHAR *pInput, L_UCHAR *pOutput, L_INT nWidth)
{
HANDLE ClrHandle /*Color Handle*/;
CONVERSION_PARAMS params /*Conversion options*/;

/* Zero initialize, this step is important*/
ZeroMemory (&params, sizeof (CONVERSION_PARAMS));

/*Conversion with options.
The conversion will be done with the options specified in the
params variable
*/

/* Set the params size */
params.uStructSize = sizeof (CONVERSION_PARAMS);

/* We want to use built-in emulation tables */
params.nMethod = USE_ET;

/* set the active conversion method */
params.nActiveMethod = USE_ET;

/* initialize the color conversion */
L_ClrInit (&ClrHandle, /*pointer to color handle to be returned*/
CCS_CMYK, /*input color space*/
CCS_RGB, /*output color space*/
&params /*pointer to the initialization options*/
);

/* Convert the image buffer */
L_ClrConvert (ClrHandle, /* conversion handle*/
pInput, /* input buffer*/
pOutput, /* output buffer*/
nWidth, /*pixel's width*/
nHeight, /*pixel's height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/

/* free the conversion */
L_ClrFree (ClrHandle);
}

The code below shows how a conversion can be done using user-defined tables:

L_VOID Tables_Convert_CMYKToRGB(L_UCHAR *pInput, L_UCHAR *pOutput, L_INT nWidth)
{
HANDLE ClrHandle /*Color Handle*/;
CONVERSION_PARAMS params /*Conversion options*/;

ZeroMemory(&params, sizeof(CONVERSION_PARAMS));

/*Conversion with options.
The conversion will be done with the options specified in the
params variable
*/

/* set the params size */
params.uStructSize = sizeof(CONVERSION_PARAMS);

/* we want to use custom emulation tables */
params.nMethod = USE_CUSTOM_ET;

/* set the active conversion method */
params.nActiveMethod = USE_CUSTOM_ET;

/* set the emulation tables */
lstrcpy(params.sDstInputTable, TEXT("C:\\RGBImage.tif"));

/* initialize the color conversion */
L_ClrInit (&ClrHandle, /*pointer to color handle to be returned*/
CCS_CMYK, /*input color space*/
CCS_RGB, /*output color space*/
&params /*pointer to the initialization options*/
);

/* convert the image buffer */

L_ClrConvert (ClrHandle, /* conversion handle */
pInput, /* input buffer */
pOutput, /* output buffer */
nWidth, /*pixel's width*/
nHeight, /*pixel's height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/

/* free the conversion */
L_ClrFree (ClrHandle);
}


Generic YUV Conversion

Generic YUV conversion provides the ability to convert any YUV format to any supported color space, using the YUV_PARAMS structure and adhering to the restrictions listed below. After defining the YUV format, you can proceed with the conversion normally, just like any other conversion. Use L_ClrConvert to perform the conversion and call L_ClrFree to free the conversion handle. Currently the conversion from any color space to Generic YUV is not supported.

Generic YUV conversion currently has the following restrictions:

1. | No sub-sampling of Y is supported
2. | The number of Y elements must be a multiple of both U, and V.
3. | With non-planar formats, vertical sub-sampling of Y, U, and V is not supported.
4. | No alignment supported in planar format; line width must not contain additional bytes.
5. | The horizontal sub-sampling periods of U, and V must be multiples of each other, and the vertical sub-sampling periods of U, and V must be multiples of each other.

Examples:

1.

Converting Y41P to RGB using Generic YUV Conversion:

L_VOID GenericY41PToRGB(L_UCHAR *pIn, L_UCHAR *pOut, L_INT nWidth, L_INT nHeight)
{
/*Declare a handle*/
HANDLE hClrHandle;

/*Declare a CONVERSION_PARAMS structure*/
CONVERSION_PARAMS cpParams;
/*Declare a YUV_PARAMS structure*/
YUV_PARAMS yuvParams;

/*Byte ordering of the format; for Y41P:
U0 Y0 V0 Y1 U4 Y2 V4 Y3 Y4 Y5 Y6 Y7
0 1 2 3 4 5 6 7 8 9 10 11
Put the Y component order first, then the U and V last as follows:
Y positions: 1,3,5,7,8,9,10,11
U positions: 0,4
V positions: 2,6 */

L_INT pOff[] = {1,3,5,7,8,9,10,11,0,4,2,6};

ZeroMemory (&cpParams, sizeof (CONVERSION_PARAMS));
/*Determine the size of the structure*/
yuvParams.uStructSize = sizeof(YUV_PARAMS);
/*Determine the horizontal sub-sampling of U */
yuvParams.nUh = 4;
/*Determine the vertical sub-sampling of U */
yuvParams.nUv = 1;
/*Determine the horizontal sub-sampling of V */
yuvParams.nVh = 4;
/*Determine the vertical sub-sampling of V */
yuvParams.nVv = 1;
/*Set the byte ordering*/
yuvParams.pOffsets = pOff;
/*The YUV values range*/
yuvParams.nRange = YUVRANGE_FULL;
/*This represents the macro pixels(smallest group of pixels allowed), which indicates how many actual pixels are in the macro pixel. This value is important only in non – planar format*/
yuvParams.nMacroPixel = 8;
/*This is a Boolean value that represents the type of the YUV format (Planar = TRUE, or non – Planar = FALSE.)*/
yuvParams.bPlanar =FALSE;

/*Fill the pYuvParams value with the address of the YUV_PARAMS structure*/
cpParams.pYuvParams = &yuvParams;
/*Determine the size of CONVERSION_PARAMS*/
cpParams.uStructSize = sizeof (CONVERSION_PARAMS);
/*Determine the type of conversion to be used in the conversion, for YUVGeneric, only use USE_BUILTIN*/
cpParams.nMethod = USE_BUILTIN;
/*Determine the type of conversion to be activated. For YUVGeneric,
only USE_BUILTIN*/
cpParams.nActiveMethod = USE_BUILTIN;

/*Initialize the conversion*/
L_ClrInit(&hClrHandle, CCS_YUV, CCS_RGB, &cpParams);

/*Convert the buffers pIn to pOut*/
L_ClrConvert(hClrHandle, pIn, pOut, nWidth, nHeight, 0, 0);

/*Free the handles*/
L_ClrFree(hClrHandle);
}

2.

Converting YVU9 (Planar) to RGB using Generic YUV Conversion:

L_VOID GenericYVU9ToRGB(L_UCHAR *pIn, L_UCHAR *pOut, L_INT nWidth, L_INT nHeight)
{
/*Declare a handle*/
HANDLE hClrHandle;

/*Declare a CONVERSION_PARAMS structure*/
CONVERSION_PARAMS cpParams;

/*Declare a YUV_PARAMS structure*/
YUV_PARAMS yuvParams;

/*This array of integers specifies the byte order of the yuv format. For planar formats it takes only a single value that represents the plane sequence in the buffer:
YUV, YVU, UYV, UVY, VYU, or VUY.*/
L_INT pOff[] = {PLANAR_YVU}; /*PLANAR_YVU means the Y plane comes first in the buffer, then the V plane, and the U plane is last*/

ZeroMemory (&cpParams, sizeof (CONVERSION_PARAMS));

/*Determine the size of the structure*/
yuvParams.uStructSize = sizeof(YUV_PARAMS);

/*Determine the horizontal sub-sampling of U*/
yuvParams.nUh = 4;

/*Determine the vertical sub-sampling of U*/
yuvParams.nUv = 4;

/*Determine the horizontal sub-sampling of V*/
yuvParams.nVh = 4;

/*Determine the vertical sub-sampling of V*/
yuvParams.nVv = 4;

/*This is a pointer to an integer. Pass the byte order array.*/
yuvParams.pOffsets = pOff;

/*The range value determines the YUV range values. */
yuvParams.nRange = YUVRANGE_FULL;

/*This represents the macro pixels(smallest group of pixels allowed) , which indicates how many actual pixels are in the macro pixel. This value is important only in non – planar format*/
yuvParams.nMacroPixel = 16;

/*This is a Boolean value that represents the type of the YUV format (Planar, or non – Planar.)*/
yuvParams.bPlanar = TRUE;

/*Pass the YUV_PARAMS structure address to the pYuvParams member of the CONVERSION_PARAMS structure.*/
cpParams.pYuvParams = &yuvParams;

/*Determine the size of the CONVERSION_PARAMS structure.*/
cpParams.uStructSize = sizeof (CONVERSION_PARAMS);

/*Determine the type of conversion to be used. For YUVGeneric, use only USE_BUILTIN*/
cpParams.nMethod = USE_BUILTIN;

/*Determine the type of conversion to be activated. For YUVGeneric, use only USE_BUILTIN.*/
cpParams.nActiveMethod = USE_BUILTIN;

/*Initialize the conversion*/
L_ClrInit(&hClrHandle, CCS_YUV, CCS_RGB, &cpParams);

/*Convert the buffers pIn to pOut*/
L_ClrConvert(hClrHandle, pIn, pOut, nWidth, nHeight, 0, 0);

/*Free the handles*/
L_ClrFree(hClrHandle);
}


Built-in Conversion (Delphi 4.0)

The Color Conversion API provides built-in conversion. To do a built-in conversion, follow the steps below:

1. | At the beginning of the Unit1 file, add LTDLLUNT, LTDLLTYP, and LTDLLDEF to the uses section.
2. | Use the following code to perform the built-in conversion:

function TForm1.Builtin_RGBToLAB({in}pSrcRGB, {out}pDstLAB: Pointer; {in}nWidth, {in}nHeight: Integer) : {ret}Integer;
var
ClrHandle : THandle; (* color handle *)
params : CONVERSION_PARAMS; (* conversion params *)
WPoint : WHITEPOINT ; (* white point definition *)
ret : Integer; (* return value *)
begin
(*
******************************************************************
* Simple conversion from RGB to CIELab using built-in conversion *
* Parameters : *
* pSrcRGB : 24 bit RGB data, this is the input image data *
* pDstLAB : 24 bit CIELab data, this is the output image data *
* nWidth : Width of the image *
* nHeight : Height of the image *
* Returns SUCCESS when successful or error code else *
******************************************************************
*)

(* initialize the conversion structure *)
ZeroMemory(Pointer(@params), SizeOf(CONVERSION_PARAMS));

(* set the whitepoint *)
params.pWpoint := @WPoint;

(* set up default conversion data *)
params.uStructSize := sizeof(CONVERSION_PARAMS);
params.pWpoint.nWhitePoint := CIELAB_D50;
params.nQuantization := 8;
params.nMethod := USE_BUILTIN;
params.nActiveMethod := USE_BUILTIN;
params.pWpoint.xWhite := 0.0;
params.pWpoint.yWhite := 0.0;

(* initialize the conversion engine *)
ret := L_ClrInit(@ClrHandle,
CCS_RGB,
CCS_LAB,
@params);

(* do we have a valid handle *)
if ret <> SUCCESS then
Result := ret
else
begin
(* do the conversion from RGB to CIELab *)
ret := L_ClrConvert (ClrHandle,
pSrcRGB,
pDstLAB,
nWidth,
nHeight,
0,
0);

if ret <> SUCCESS then
begin
(* free before leaving *)
L_ClrFree (ClrHandle);
Result := ret;
end
else
begin
(* do not forget to free every thing *)
ret := L_ClrFree (ClrHandle);
Result := ret;
end;
end;

end;


Color Conversion to an Image (Delphi 4.0)

The Color Conversion API provides color conversion to an image. To do a conversion, follow the steps below:

1. | At the beginning of the Unit1 file, add LTDLLUNT, LTDLLTYP, and LTDLLDEF to the uses section.
2. | Use the following code to direct color conversion to an image:

function TForm1.LABToLEADBitmap({in}pSrcLAB: Pointer; {out}var pBitmap: BITMAPHANDLE; {in}nWidth, {in}nHeight: Integer) : {ret}Integer;
var
ret : Integer; (* return value *)
begin
(*
******************************************************************
* Simple conversion from CIELab to RGB24 LEAD bitmap *
* Parameters : *
* pSrcLAB : 24 bit CIELab data, this is the input image data *
* pBitmap : Handle to the resulting LEAD bitmap *
* nWidth : Width of the image *
* nHeight : Height of the image *
* Returns SUCCESS when successful or an error code otherwise *
******************************************************************
*)
ret := L_ClrConvertDirectToBitmap(CCS_LAB,
CCS_RGB,
pSrcLAB,
@pBitmap,
SizeOf(BITMAPHANDLE),
nWidth,
nHeight,
0,
0);

Result := ret;
end;


Conversion Given an ICM Profiles (Delphi 4.0)

Conversion Given an ICM Profile (Delphi 4.0)

1.

Define the following global variables:

ClrHandle : THandle;
params : CONVERSION_PARAMS;
RGBColor : array[0..2] of UCHAR;
ColorSpace : array[0..3] of UCHAR;

2.

Set the conversion options by filling a CONVERSION_PARAMS structure:

ZeroMemory(Pointer(@params), SizeOf(CONVERSION_PARAMS));

params.uStructSize := SizeOf(CONVERSION_PARAMS);
params.nMethod := USE_CUSTOM_ICC;
params.nActiveMethod := USE_CUSTOM_ICC;
New(params.pWpoint);
params.pWpoint.nWhitePoint := CIELAB_D50;

StrCopy (params.sInputProfile, ‘C:\MyCMYKProfile.ICM’);
StrCopy (params.sOutputProfile, ‘C:\MyRGBProfile.ICM’);

params.pMemInputProfile := nil;
params.pMemOutputProfile := nil;

3.

Initialize the color conversion handle with L_ClrInit():

L_ClrInit(@ClrHandle, CCS_CMYK, CCS_RGB, @params);

4.

Now, do the conversion:

ColorSpace[0] := 100;
ColorSpace[1] := 100;
ColorSpace[2] := 100;
ColorSpace[3] := 100;

L_ClrConvert(ClrHandle, Pointer(ColorSpace), Pointer(RGBColor), 1, 1, 0, 0);

5.

At the end, free the color conversion handle:

L_ClrFree(ClrHandle);


Dialog Based Initialization (Delphi 4.0)

The Color Conversion API provides a color space dialog that can be used to initialize a conversion. To do a dialog based initialization follow the steps below:

1. | At the beginning of the Unit1 file, add LTDLLUNT, LTDLLTYP, and LTDLLDEF to the uses section.
2. | Use the following code to implement using the color space dialog for initializing:

function TForm1.ColorDlg_RGBToLAB({in}pSrcRGB, {out}pDstLAB: Pointer; {in}nWidth, {out}nHeight: Integer) : {ret}Integer;
var
ClrHandle : THandle; (* color handle *)
ret: Integer; (* return value *)
begin
(*
******************************************************************
* Simple conversion from RGB to CIELab using the LEAD color dialog *
* Parameters : *
* pSrcRGB : 24 bit RGB data, this is the input image data *
* pDstLAB : 24 bit CIELab data, this is the output image data *
* nWidth : Width of the image *
* nHeight : Height of the image *
* Returns SUCCESS when successful or an error code otherwise *
******************************************************************
*)

(*
* when the dialog appears choose RGB to LAB conversion from
* the Miscellaneous options
*)
ret := L_ClrDlg(DLG_LAB, (* CIELAb color dialog *)
Handle, (* Handle to parent window *)
@ClrHandle, (* I need a color handle *)
nil (* no need for a CONVERSION_PARAMS data *)
);

(* do we have a valid handle *)
if ret <> SUCCESS then
Result := ret
else
begin
(* do the conversion from RGB to CIELab *)
ret := L_ClrConvert (ClrHandle,
pSrcRGB,
pDstLAB,
nWidth,
nHeight,
0,
0);

if ret <> SUCCESS then
begin
(* free before leaving *)
L_ClrFree (ClrHandle);
Result := ret;
end
else
begin
(* do not forget to free every thing *)
ret := L_ClrFree (ClrHandle);
Result := ret;
end;
end;

end;


Emulation Tables (Delphi 4.0)

Note:

At the beginning of the Unit1 file, add LTDLLUNT, LTDLLTYP, and LTDLLDEF to the uses section.

The LEAD Color Conversion toolkit provides emulation tables as one of its conversion methods. This method however is provided only for the following conversions:

CMYK to RGB.

CIELab to RGB

and RGB to CIELab

The Emulation tables' method supports both built-in and custom options. For built-in emulation tables, use the USE_ET option. The custom emulation tables' option, USE_CUSTOM_ET, provides custom conversion using user-supplied images converted from the source images distributed with the library by any tool, as follows:

Conversion | Source | Convert to
CMYK to RGB | src_cmyk_image.tif | RGB image (i.e. dst_cmyk2rgb_image.tif)
RGB to Lab | src_rgb_image.tif | Lab image ( i.e. dst_rgb2lab_image.tif)
Lab to RGB | src_lab_image.tif | RGB image (i.e. dst_lab2rgb_image.tif)

A set of images, already converted and ready for use (dst_cmyk2rgb_image.tif, dst_rgb2lab_image.tif, and dst_lab2rgb_image.tif), is provided. However, using the provided set of converted images will produce the same results as the built-in emulation tables.

The code below shows how a conversion can be done using the built-in tables:

procedure Tables_Convert_CMYKToRGB({in}pInput: Pointer; {out}pOutput: Pointer; {in}nWidth: Integer; {in}nHeight: Integer);
var
ClrHandle : THandle (*Color Handle*);
params : CONVERSION_PARAMS (*Conversion options*);
begin

(* Zero initialize, this step is important*)
ZeroMemory (@params, SizeOf (CONVERSION_PARAMS));

(*
* Conversion with options.
* The conversion will be done with the options specified in the
* params variable.
*)

(* Set the params size *)
params.uStructSize := SizeOf (CONVERSION_PARAMS);

(* We want to use built-in emulation tables *)
params.nMethod := USE_ET;

(* set the active conversion method *)
params.nActiveMethod := USE_ET;

(* initialize the color conversion *)
L_ClrInitL_ClrInit (@ClrHandle, (* pointer to color handle to be returned*)
CCS_CMYK, (* input color space *)
CCS_RGB, (* output color space *)
@params (* pointer to the initialization options *)
);

(* Convert the image buffer *)
L_ClrConvert (ClrHandle, (* conversion handle *)
pInput, (* input buffer *)
pOutput, (* output buffer *)
nWidth, (* pixels width *)
nHeight, (* pixels height *)
0, (* 0 bytes align *)
0); (* 0 bytes align *)

(* free the conversion *)
L_ClrFree (ClrHandle);
end;

The code below shows how a conversion can be done using user-defined tables:

procedure Tables_Convert_CMYKToRGB({in}pInput: Pointer; {out}pOutput: Pointer; {in}nWidth: Integer; {in}nHeight: Integer);
var
ClrHandle : THandle (*Color Handle*);
params : CONVERSION_PARAMS (*Conversion options*);
begin

(* Zero initialize, this step is important*)
ZeroMemory (@params, SizeOf (CONVERSION_PARAMS));

(*
* Conversion with options.
* The conversion will be done with the options specified in the
* params variable.
*)

(* Set the params size *)
params.uStructSize := SizeOf (CONVERSION_PARAMS);

(* We want to use built-in emulation tables *)
params.nMethod := USE_CUSTOM_ET;

(* set the active conversion method *)
params.nActiveMethod := USE_CUSTOM_ET;

(* set the emulation tables *)
StrCopy(params.sInputProfile, 'C:\RGBImage.tif');

(* initialize the color conversion *)
L_ClrInit (@ClrHandle, (* pointer to color handle to be returned*)
CCS_CMYK, (* input color space *)
CCS_RGB, (* output color space *)
@params (* pointer to the initialization options *)
);

(* Convert the image buffer *)
L_ClrConvert (ClrHandle, (* conversion handle *)
pInput, (* input buffer *)
pOutput, (* output buffer *)
nWidth, (* pixels width *)
nHeight, (* pixels height *)
0, (* 0 bytes align *)
0); (* 0 bytes align *)

(* free the conversion *)
L_ClrFree (ClrHandle);
end;


Generic YUV conversion (Delphi 4.0)

Note:

At the beginning of the Unit1 file, add LTDLLUNT, LTDLLTYP, and LTDLLDEF to the uses section.

Generic YUV conversion provides the ability to convert any YUV format to any supported color space, using the YUV_PARAMS structure and adhering to the restrictions listed below. After defining the YUV format, you can proceed with the conversion normally, just like any other conversion. Use L_ClrConvert to perform the conversion and call L_ClrFree to free the conversion handle. Currently the conversion from any color space to Generic YUV is not supported.

Generic YUV conversion currently has the following restrictions:

1. | No sub-sampling of Y is supported
2. | The number of Y elements must be a multiple of both U, and V.
3. | With non-planar formats, vertical sub-sampling of Y, U, and V is not supported.
4. | No alignment supported in planar format; line width must not contain additional bytes.
5. | The horizontal sub-sampling periods of U, and V must be multiples of each other, and the vertical sub-sampling periods of U, and V must be multiples of each other.

Examples:

1.

Converting Y41P to RGB using Generic YUV Conversion:

procedure GenericY41PToRGB({in}pIn: Pointer; {out}pOut: Pointer; {in}nWidth: Integer; {in}nHeight: Integer);
var
hClrHandle : THandle (* Color Handle *);
cpParams : CONVERSION_PARAMS (* Conversion options *);
yuvParams : YUV_PARAMS (* Declare YUV Params structure *);
pOff: array[0..11] of Integer (* Byte ordering of the YUV format *);
begin

(*
* Byte ordering of the format; for Y41P:
* U0 Y0 V0 Y1 U4 Y2 V4 Y3 Y4 Y5 Y6 Y7
* 0 1 2 3 4 5 6 7 8 9 10 11
* Put the Y component order first then the U and V last as follows:
* Y positions: 1,3,5,7,8,9,10,11
* U positions: 0,4
* V positions: 2,6
*)

pOff[0] := 1;
pOff[1] := 3;
pOff[2] := 5;
pOff[3] := 7;
pOff[4] := 8;
pOff[5] := 9;
pOff[6] := 10;
pOff[7] := 11;
pOff[8] := 0;
pOff[9] := 4;
pOff[10] := 2;
pOff[11] := 6;

ZeroMemory (@cpParams, sizeof (CONVERSION_PARAMS));
(* Determine the size of the structure *)
yuvParams.uStructSize := sizeof(YUV_PARAMS);
(* Determine the horizontal sub-sampling of U *)
yuvParams.nUh := 4;
(* Determine the vertical sub-sampling of U *)
yuvParams.nUv := 1;
(* Determine the horizontal sub-sampling of V *)
yuvParams.nVh := 4;
(* Determine the vertical sub-sampling of V */
yuvParams.nVv = 1;
(* Set the byte ordering *)
yuvParams.pOffsets := @pOff;
(* The YUV values range *)
yuvParams.nRange := YUVRANGE_FULL;
(*
* This represents the macro pixels(smallest group of pixels allowed) , which indicates
* how many actual pixels are in the macro pixel, this value is important only in non –
* planar format
*)

yuvParams.nMacroPixel := 8;
(*
* This is a Boolean value that represents the type of the YUV format (Planar = TRUE,
* or non – Planar = FALSE.)
*)
yuvParams.bPlanar := 0; (* Flase *)

(* Fill the pYuvParams value with the address of the YUV_PARAMS structure *)
cpParams.pYuvParams := @yuvParams;
(* Determine the size of CONVERSION_PARAMS *)
cpParams.uStructSize := SizeOf (CONVERSION_PARAMS);
(*
* Determine the type of conversion to be used in the conversion, for YUVGeneric, only use
* USE_BUILTIN
*)
cpParams.nMethod := USE_BUILTIN;
(*
* Determine the type of conversion to be activated. For YUVGeneric,
* only USE_BUILTIN
*)
cpParams.nActiveMethod := USE_BUILTIN;

(* Initialize the conversion *)
L_ClrInit(@hClrHandle, CCS_YUV, CCS_RGB, @cpParams);

(* Convert the buffers pIn to pOut *)
L_ClrConvert (hClrHandle, pIn, pOut, nWidth, nHeight, 0, 0);

(* Free the handles *)
L_ClrFree (hClrHandle);
end;

2.

Converting YVU9 (Planar) to RGB using Generic YUV Conversion:

procedure GenericYVU9ToRGB({in}pIn: Pointer; {out}pOut: Pointer; {in}nWidth: Integer; {in}nHeight: Integer);
var
hClrHandle : THandle (* Color Handle *);
cpParams : CONVERSION_PARAMS (* Conversion options *);
yuvParams : YUV_PARAMS (* Declare YUV Params structure *);
pOff: array[0..0] of Integer (* Byte ordering of the YUV format *);
begin

(*
* This array of integers specifies the byte order of the yuv format. For planar
* formats it takes only a single value that represents planes sequence in the buffer:
* YUV, YVU, UYV, UVY, VYU, or VUY.
*)
pOff[0] := PLANAR_YVU; (*
* PLANAR_YVU means the Y plane comes first in
* the buffer, then the V plane, and the U plane is last
*)

ZeroMemory (@cpParams, SizeOf (CONVERSION_PARAMS));

(* Determine the size of the structure *)
yuvParams.uStructSize := SizeOf(YUV_PARAMS);

(* Determine the horizontal sub-sampling of U *)
yuvParams.nUh := 4;

(* Determine the vertical sub-sampling of U *)
yuvParams.nUv := 4;

(* Determine the horizontal sub-sampling of V *)
yuvParams.nVh := 4;

(* Determine the vertical sub-sampling of V *)
yuvParams.nVv := 4;

(* This is a pointer to an integer. Pass the byte ordering array *)
yuvParams.pOffsets := @pOff;

(* The range value determines the YUV range values *)
yuvParams.nRange := YUVRANGE_FULL;

(*
* This represents the macro pixels(smallest group of pixels allowed) , which indicates
* how many actual pixels are in the macro pixel. This value is important only in non – p
* planar format
*)
yuvParams.nMacroPixel := 16;

(*
* This is a Boolean value that represents the type of the YUV format (Planar, or non
* - Planar.)
*)
yuvParams.bPlanar := 1; (* True *)

(*
* Pass the YUV_PARAMS structure address to the pYuvParams member of the
* CONVERSION_PARAMS structure
*)
cpParams.pYuvParams := @yuvParams;

(* Determine the size of the CONVERSION_PARAMS structure*)
cpParams.uStructSize := SizeOf (CONVERSION_PARAMS);

(*
* Determine the type of conversion to be used. For YUVGeneric, use
* only USE_BUILTIN
*)
cpParams.nMethod := USE_BUILTIN;

(*
* Determine the type of conversion to be activated. For
* YUVGeneric, use only USE_BUILTIN
*)
cpParams.nActiveMethod := USE_BUILTIN;

(* Initialize the conversion *)
L_ClrInit(@hClrHandle, CCS_YUV, CCS_RGB, @cpParams);

(* Convert the buffers pIn to pOut *)
L_ClrConvert (hClrHandle, pIn, pOut, nWidth, nHeight, 0, 0);

(* Free the handles *)
L_ClrFree (hClrHandle);
end;

;


Built-in Conversion (Visual Basic)

The Color Conversion API provides built-in conversion. To do a built-in conversion, follow the steps below:

1.

Define the following global variables:

Dim RGBData(100) As Byte
Dim LABData(100) As Byte
Dim nWidth As Integer
Dim nHeight As Integer
Dim nInAlign As Integer
Dim nOutAlign As Integer
Dim ClrHandle As Long 'color handle
Dim cnvParam As CONVERSION_PARAMS 'conversion params
Dim wtPoint As WHITEPOINT 'white point definition

2.

Set the conversion options by filling a CONVERSION_PARAMS structure:

'set the whitepoint
wtPoint.nWhitePoint = CIELAB_D50
wtPoint.xWhite = 0
wtPoint.yWhite = 0

'initialize the conversion structure
cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 8
cnvParam.nMethod = USE_BUILTIN
cnvParam.nActiveMethod = USE_BUILTIN
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = 0
cnvParam.sDstInputTable(0) = 0
cnvParam.sInputProfile(0) = 0
cnvParam.sOutputProfile(0) = 0
cnvParam.pWpoint = VarPtr(wtPoint)

3.

Initialize the color conversion handle with L_ClrInit ():

L_ClrInit ClrHandle, CCS_RGB, CCS_LAB, cnvParam

4.

Convert from RGB to CIELab:

L_ClrConvert ClrHandle, RGBData(0), LABData(0), nWidth, nHeight, nInAlign, nOutAlign

5.

At the end, free the color conversion handle:

L_ClrFree ClrHandle


Color Conversion to an Image (Visual Basic)

The color conversion API provides direct color conversion to an image. To do a conversion, follow the steps below:

1.

Define the following global variables:

Dim LABData(100) As Byte
Dim LBitmap As LEADBitmapHandle
Dim nWidth As Integer
Dim nHeight As Integer
Dim nInAlign As Integer
Dim nOutAlign As Integer

2.

To convert 320x240 24 bit CIELab data to a LEAD bitmap with RGB24 do the following:

L_ClrConvertDirectToBitmap CCS_LAB, CCS_BGR, LABData(0), LBitmap, Len(Lbitmap), nWidth, nHeight, nInAlign, nOutAlign

' You can use the Lead bitmap as you want


Conversion Given an ICM Profile (Visual Basic)

1.

Define the following global variables:

Dim ClrHandle As Long
Dim cnvParam As CONVERSION_PARAMS
Dim wtPoint As WHITEPOINT 'this needs to be defined in VB, because its member in CONVERSION_PARAMS can't be accessed since it is a pointer and not a structure
Dim RGBColor(3) As Byte
Dim ColorSpace(4) As Byte

2.

Set the conversion options by filling a CONVERSION_PARAMS structure:

wtPoint.nWhitePoint = CIELAB_D50
wtPoint.xWhite = 0
wtPoint.yWhite = 0
cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 8
cnvParam.nMethod = USE_CUSTOM_ICC
cnvParam.nActiveMethod = USE_CUSTOM_ICC
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = 0
cnvParam.sDstInputTable(0) = 0
cnvParam.pWpoint = VarPtr(wtPoint)

cnvParam.pMemInputProfile = 0
cnvParam.pMemOutputProfile = 0

Dim str1 As String
str1 = "C:\\MyRGBProfile.ICM"
Dim i As Integer
For i = 0 To Len(str1) – 1
cnvParam.sInputProfile(i) = Asc(Right(str1, Len(str1) - i))
Next i

str1 = "C:\\MyRGBProfile.ICM"
For i = 0 To Len(str1) – 1
cnvParam.sOutputProfile(i) = Asc(Right(str1, Len(str1) - i))
Next i

3.

Initialize the color conversion handle with L_ClrInit ():

L_ClrInit ClrHandle, CCS_CMYK, CCS_RGB, cnvParam

4.

Now, do the conversion:

ColorSpace(0) = 100
ColorSpace(1) = 100
ColorSpace(2) = 100
ColorSpace(3) = 100
L_ClrConvert ClrHandle, ColorSpace(0), RGBColor(0), 1, 1, 0, 0

5.

At the end, free the color conversion handle:

L_ClrFree ClrHandle


Dialog Based Initialization (Visual Basic)

The Color Conversion API provides a color space dialog that can be used to initialize a conversion. To do a dialog based initialization follow the steps below:

1.

Define the following global variables:

Dim RGBData(100) As Byte
Dim LABData(100) As Byte
Dim nWidth As Integer
Dim nHeight As Integer
Dim nInAlign As Integer
Dim nOutAlign As Integer
Dim ClrHandle As Long 'color handle
Dim cnvParam As CONVERSION_PARAMS

2.

Display the color space dialog box to initialize as follows:

L_ClrDlg DLG_LAB, Form1.hWnd, ClrHandle, cnvParam

3.

Convert from RGB to CIELab as follows:

L_ClrConvert ClrHandle, RGBData(0), LABData(0), nWidth, nHeight, nInAlign, nOutAlign

4.

At the end, free the color conversion handle:

L_ClrFree ClrHandle


Emulation Tables (Visual Basic)

The LEAD Color Conversion toolkit provides emulation tables as one of its conversion methods. This method however is provided only for the following conversions:

CMYK to RGB.

CIELab to RGB

and RGB to CIELab

The Emulation tables' method supports both built-in and custom options. For built-in emulation tables, use the USE_ET option. The custom emulation tables' option, USE_CUSTOM_ET, provides custom conversion using user-supplied images, converted from the source images distributed with the library by any tool, as follows:

Conversion | Source | Convert to
CMYK to RGB | src_cmyk_image.tif | RGB image (i.e. dst_cmyk2rgb_image.tif)
RGB to Lab | src_rgb_image.tif | Lab image ( i.e. dst_rgb2lab_image.tif)
Lab to RGB | src_lab_image.tif | RGB image (i.e. dst_lab2rgb_image.tif)

A set of images, already converted and ready for use (dst_cmyk2rgb_image.tif, dst_rgb2lab_image.tif, and dst_lab2rgb_image.tif), is provided. However, using the provided set of converted images will produce the same results as the built-in emulation tables.

The code below shows how a conversion can be done using the built-in tables:

Function Tables_Convert_CMYKToRGB(RGBData() As Byte, LABData() As Byte, nWidth As Integer, nHeight As Integer, nInAlign As Integer, nOutAlign As Integer) As Integer
'This function converts an RGB24 image to LAB using built-in emulation tables.
'-RGBData: pointer to the input RGB data.
'-LABData: pointer to the output LAB beffer
'-nWidth: width of the passed image.
'-nHeight: height of the passed image.
'-nInAlign: input buffer alignment.
'-nOutAlign: output buffer alignment.

Dim ClrHandle As Long 'color handle
Dim cnvParam As CONVERSION_PARAMS 'conversion params
Dim ret As Integer 'return value

'initialize the conversion structure
cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 8
cnvParam.nMethod = USE_ET
cnvParam.nActiveMethod = USE_ET
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = 0
cnvParam.sDstInputTable(0) = 0
cnvParam.sInputProfile(0) = 0
cnvParam.sOutputProfile(0) = 0

'initialize the conversion engine
ret = L_ClrInit (ClrHandle, CCS_RGB, CCS_LAB, cnvParam)

'do we have a valid handle
If (ret = SUCCESS) Then
'do the conversion from RGB to CIELab
ret = L_ClrConvert (ClrHandle, RGBData(0), LABData(0), nWidth, nHeight, nInAlign, nOutAlign)
If (ret <> SUCCESS) Then
MsgBox "Failed to convert from RGB to LAB"
Tables_Convert_CMYKToRGB = ret
End If

'do not forget to free every thing
L_ClrFree (ClrHandle)
Else
MsgBox "Failed to initialize LTCLR"
Tables_Convert_CMYKToRGB = ret
End If

End Function

The code below shows how a conversion can be done using user-defined tables:

Function Tables_Convert_CMYKToRGB(RGBData() As Byte, LABData() As Byte, nWidth As Integer, nHeight As Integer, nInAlign As Integer, nOutAlign As Integer, strDst As String) As Integer
'This function converts an RGB24 image to LAB using built-in emulation tables.
'-RGBData: pointer to the input RGB data.
'-LABData: pointer to the output LAB beffer
'-nWidth: width of the passed image.
'-nHeight: height of the passed image.
'-nInAlign: input buffer alignment.
'-nOutAlign: output buffer alignment.
'-strDst: destination custom table.

Dim ClrHandle As Long 'color handle
Dim cnvParam As CONVERSION_PARAMS 'conversion params
Dim ret As Integer 'return value
Dim i As Integer

'initialize the conversion structure
cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 8
cnvParam.nMethod = USE_CUSTOM_ET
cnvParam.nActiveMethod = USE_CUSTOM_ET
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = 0
cnvParam.sDstInputTable(0) = 0
cnvParam.sInputProfile(0) = 0
cnvParam.sOutputProfile(0) = 0

For i = 0 To Len(strDst) – 1
cnvParam.sDstInputTable(i) = Asc(Right(strDst, Len(strDst) - i))
Next i

'initialize the conversion engine
ret = L_ClrInit (ClrHandle, CCS_RGB, CCS_LAB, cnvParam)

'do we have a valid handle
If (ret = SUCCESS) Then
'do the conversion from RGB to CIELab
ret = L_ClrConvert (ClrHandle, RGBData(0), LABData(0), nWidth, nHeight, nInAlign, nOutAlign)
If (ret <> SUCCESS) Then
MsgBox "Failed to convert from RGB to LAB"
Tables_Convert_CMYKToRGB = ret
End If

'do not forget to free every thing
L_ClrFree (ClrHandle)
Else
MsgBox "Failed to initialize LTCLR"
Tables_Convert_CMYKToRGB = ret
End If

End Function


Generic YUV conversion (Visual Basic)

Generic YUV conversion provides the ability to convert any YUV format to any supported color space, using the YUV_PARAMS structure and adhering to the restrictions listed below. After defining the YUV format, you can proceed with the conversion normally, just like any other conversion. Use L_ClrConvert to perform the conversion and call L_ClrFree to free the conversion handle. Currently the conversion from any color space to Generic YUV is not supported.

Generic YUV conversion currently has the following restrictions:

1. | No sub-sampling of Y is supported
2. | The number of Y elements must be a multiple of both U, and V.
3. | With non-planar formats, vertical sub-sampling of Y, U, and V is not supported.
4. | No alignment supported in planar format; line width must not contain additional bytes.
5. | The horizontal subsampling periods of U, and V must be multiples of each other, and the vertical subsampling periods of U, and V must be multiples of each other.

Examples:

1.

Converting Y41P to RGB using Generic YUV Conversion:

Function GenericY41PToRGB(YUVData() As Byte, RGBData() As Byte, nWidth As Integer, nHeight As Integer) As Integer
Dim ret As Integer
Dim ClrHandle As Long
Dim cnvParam As CONVERSION_PARAMS
Dim pOff(12) As Long

pOff(0) = 1
pOff(1) = 3
pOff(2) = 5
pOff(3) = 7
pOff(4) = 8
pOff(5) = 9
pOff(6) = 10
pOff(7) = 11
pOff(8) = 0
pOff(9) = 4
pOff(10) = 2
pOff(11) = 6
'(1,3,5,7,8,9,10,11,0,4,2,6)

Dim YUVParamas As LPYUV_PARAMS
With YUVParamas
.uStructSize = Len(YUVParamas)
.nMask = 0
.nUh = 4
.nUv = 1
.nVh = 4
.nVv = 1
.pOffsets = VarPtr(pOff(0))
.nMacroPixel = 8
.nRange = YUVRANGE_FULL
.bPlanar = 0
End With

cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 0
cnvParam.nMethod = USE_BUILTIN
cnvParam.nActiveMethod = USE_BUILTIN
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = VarPtr(YUVParamas)
cnvParam.sInputProfile(0) = 0
cnvParam.sOutputProfile(0) = 0

ret = L_ClrInit (ClrHandle, CCS_YUV, CCS_RGB, cnvParam)
ret = L_ClrConvert (ClrHandle, YUVData(0), RGBData(0), nWidth, nHeight, 0, 0)
ret = L_ClrFree (ClrHandle)

GenericY41PToRGB = ret

End Function

2.

Converting YVU9 (Planar) to RGB using Generic YUV Conversion:

Function GenericYVU9ToRGB(YUVData() As Byte, RGBData() As Byte, nWidth As Integer, nHeight As Integer) As Integer
Dim ret As Integer
Dim ClrHandle As Long
Dim cnvParam As CONVERSION_PARAMS
Dim pOff(0) As Long

pOff(0) = PLANAR_YVU

Dim YUVParamas As LPYUV_PARAMS
With YUVParamas
.uStructSize = Len(YUVParamas)
.nMask = 0
.nUh = 4
.nUv = 1
.nVh = 4
.nVv = 1
.pOffsets = VarPtr(pOff(0))
.nMacroPixel = 8
.nRange = YUVRANGE_FULL
.bPlanar = 1
End With

cnvParam.uStructSize = Len(cnvParam)
cnvParam.nQuantization = 0
cnvParam.nMethod = USE_BUILTIN
cnvParam.nActiveMethod = USE_BUILTIN
cnvParam.pCmykParams = 0
cnvParam.pLabParams = 0
cnvParam.pYuvParams = VarPtr(YUVParamas)
cnvParam.sInputProfile(0) = 0
cnvParam.sOutputProfile(0) = 0

ret = L_ClrInit (ClrHandle, CCS_YUV, CCS_RGB, cnvParam)
ret = L_ClrConvert (ClrHandle, YUVData(0), RGBData(0), nWidth, nHeight, 0, 0)
ret = L_ClrFree (ClrHandle)

GenericYVU9ToRGB = ret

End Function


L_ClrConvert

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrConvert(ClrHandle, pSrc, pDst, nWidth, nHeight, nInAlign, nOutAlign)

HANDLE ClrHandle; | /* handle to the color conversion */
L_CHAR * pSrc; | /* pointer to the input buffer */
L_CHAR * pDst; | /* pointer to the output buffer */
L_INT nWidth; | /* width of pixels to be processed */
L_INT nHeight; | /* height of pixels to be processed */
L_INT nInAlign; | /* each scanline in the input buffer is multiple of nInAlign bytes */
L_INT nOutAlign; | /* each scan line in the output buffer is multiple of nOutAlign bytes */

Converts image data in a buffer from one color conversion model to another.

Parameter | Description
ClrHandle | Handle to an existing color conversion. This handle is obtained by calling the L_ClrInit function.
pSrc | Pointer to the buffer holding the input data.
pDst | Pointer to the buffer that will hold the converted data.
nWidth | Width of pixels to be processed.
nHeigh | Height of pixels to be processed.
nInAlign | Each scanline in the input buffer is a multiple of nInAlign bytes.
nOutAlign | Each scan line in the output buffer is a multiple of nOutAlign bytes.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

Conversion is done by setting the active method value specified in the CONVERSION_PARAMS structure when calling L_ClrInit. To change the active method, use L_ClrSetConversionParams. Only methods supported by the initialized converter should be specified.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrInit
Topics: | Conversion Process
 | COLOR Function Groups

Example

For an example, refer to L_ClrInit.


L_ClrConvertDirect

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrConvertDirect(nSrcFormat, nDstFormat, pSrcBuf, pDstBuf, nWidth, nHeight, nInAlign, nOutAlign)

L_INT nSrcFormat; | /* format of the input data */
L_INT nDstFormat; | /* format of the output data */
L_CHAR * pSrcBuf; | /* pointer to the input buffer */
L_CHAR * pDstBuf; | /* pointer to the output buffer */
L_INT nWidth; | /* width of pixels to be processed */
L_INT nHeight; | /* height of pixels to be processed */
L_INT nInAlign; | /* each scanline in the input buffer is a multiple of nInAlign bytes */
L_INT nOutAlign; | /* each scan line in the output buffer is a multiple of nOutAlign bytes */

Converts image data in a buffer from one color conversion model to another directly using built in algorithms.

Parameter | Description
nSrcFormat | Format of the source data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color conversion is RGB.
 | CCS_YUV | [0x01] Color conversion is YUV.
 | CCS_CMYK | [0x02] Color conversion is CMYK.
 | CCS_HSV | [0x03] Color conversion is HSV.
 | CCS_HLS | [0x04] Color conversion is HLS.
 | CCS_YIQ | [0x05] Color conversion is YIQ.
 | CCS_CMY | [0x06] Color conversion is CMY.
 | CCS_LAB | [0x07] Color conversion is CIELAB.
 | CCS_XYZ | [0x08] Color conversion is CIEXYZ.
 | CCS_YCCK | [0x0B] Color conversion is YCCK.
 | CCS_BGR | [0x0C] Color conversion is BGR.
 | CCS_UYVY | [0x0E] Color conversion is UYVY.
 | CCS_YUY2 | [0x09] Color conversion is YUY2.
 | CCS_YVU9 | [0x0A] Color conversion is YVU9.
 | CCS_YCC | [0x0F] Color conversion is YCC.
nDstFormat | Format of the output data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color conversion is RGB.
 | CCS_YUV | [0x01] Color conversion is YUV.
 | CCS_CMYK | [0x02] Color conversion is CMYK.
 | CCS_HSV | [0x03] Color conversion is HSV.
 | CCS_HLS | [0x04] Color conversion is HLS.
 | CCS_YIQ | [0x05] Color conversion is YIQ.
 | CCS_CMY | [0x06] Color conversion is CMY.
 | CCS_LAB | [0x07] Color conversion is CIELAB.
 | CCS_XYZ | [0x08] Color conversion is CIEXYZ.
 | CCS_BGR | [0x0C] Color conversion is BGR.
 | CCS_UYVY | [0x0E] Color conversion is UYVY.
 | CCS_YUY2 | [0x09] Color conversion is YUY2.
 | CCS_YVU9 | [0x0A] Color conversion is YVU9.
 | CCS_YCC | [0x0F] Color conversion is YCC.
pSrcBuf | Pointer to the buffer holding the input data.
pDstBuf | Pointer to the buffer that will hold the converted data.
nWidth | Width of pixels to be processed.
nHeigh | Height of pixels to be processed.
nInAlign | Each scanline in the input buffer is a multiple of nInAlign bytes.
nOutAlign | Each scan line in the output buffer is a multiple of nOutAlign bytes.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

Converting from any color space to YCCK color space is currently not supported.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrConvert
Topics: | Programming with LEADTOOLS Color Conversion Functions
 | COLOR Function Groups

Example

L_INT Fast_Convert_CMYKToRGB(L_UCHAR *pInput, L_UCHAR *pOutput, L_INT nWidth, L_INT nHeight)
{
/* direct conversion using built in options */
return L_ClrConvertDirect(CCS_CMYK, /* input color conversion */
CCS_RGB, /*output color conversion */
pInput, /*input buffer*/
pOutput, /*output buffer*/
nWidth, /*pixels width*/
nHeight, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/
}


L_ClrConvertDirectToBitmap

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrConvertDirectToBitmap(nSrcFormat, nDstFormat, pSrcBuf, pBitmap, uStructSize, nWidth, nHeight, nInAlign, nOutAlign)

L_INT nSrcFormat; | /* format of the input data */
L_INT nDstFormat; | /* format of the output data */
L_CHAR * pSrcBuf; | /* pointer to the input buffer */
BITMAPHANDLE * pBitmap; | /* pointer to the output LEAD bitmap */
L_UINT uStructSize; | /* size in bytes, of pBitmap */
L_INT nWidth; | /* width of pixels to be processed */
L_INT nHeight; | /* height of pixels to be processed */
L_INT nInAlign; | /* each scanline in the input buffer is a multiple of nInAlign bytes */
L_INT nOutAlign; | /* each scan line in the output buffer is a multiple of nOutAlign bytes */

Converts image data in a buffer from one color conversion model to RGB\BGR directly using built in algorithms, and sets the output as a LEAD bitmap.

Parameter | Description
nSrcFormat | Format of the source data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color conversion is RGB.
 | CCS_YUV | [0x01] Color conversion is YUV.
 | CCS_CMYK | [0x02] Color conversion is CMYK.
 | CCS_HSV | [0x03] Color conversion is HSV.
 | CCS_HLS | [0x04] Color conversion is HLS.
 | CCS_YIQ | [0x05] Color conversion is YIQ.
 | CCS_CMY | [0x06] Color conversion is CMY.
 | CCS_LAB | [0x07] Color conversion is CIELAB.
 | CCS_XYZ | [0x08] Color conversion is CIEXYZ.
 | CCS_YCCK | [0x0B] Color conversion is YCCK.
 | CCS_BGR | [0x0C] Color conversion is BGR.
 | CCS_UYVY | [0x0E] Color conversion is UYVY.
 | CCS_YUY2 | [0x09] Color conversion is YUY2.
 | CCS_YVU9 | [0x0A] Color conversion is YVU9.
 | CCS_YCC | [0x0F] Color conversion is YCC.
 | CCS_IHS | [0x10] Color conversion is IHS.

nDstFormat | Format of the output data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color conversion is RGB.
 | CCS_BGR | [0x0C] Color conversion is BGR.
pSrcBuf | Pointer to the buffer holding the input data.
pBitmap | Pointer to the LEAD bitmap that will hold the converted data.
uStructSize | Size in bytes, of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).
nWidth | Width of pixels to be processed.
nHeigh | Height of pixels to be processed.
nInAlign | Each scanline in the input buffer is a multiple of nInAlign bytes.
nOutAlign | Each scanline in the output buffer is a multiple of nOutAlign bytes.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

This function works only for conversion to BGR or RGB color space formats.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrConvert
Topics: | Programming with LEADTOOLS Color Conversion Functions
 | COLOR Function Groups

Example

L_INT Fast_Convert_CMYKToRGB(L_UCHAR *pInput, BITMAPHANDLE *pBitmap, L_INT nWidth, L_INT nHeight)
{
/* direct conversion using built in options */
return L_ClrConvertDirectToBitmap(CCS_CMYK, /* input color conversion */
CCS_RGB, /*output color conversion */
pInput, /*input buffer*/
pBitmap, /*output bitmap*/
sizeof(BITMAPHANDLE),
nWidth /*pixels width*/
nHeight, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/
}


L_ClrConvertToBitmap

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrConvertToBitmap(ClrHandle, pSrc, pBitmap, uStructSize, nWidth, nHeight, nInAlign, nOutAlign)

HANDLE ClrHandle; | /* handle to the color conversion */
L_CHAR * pSrc; | /* pointer to the input buffer */
BITMAPHANDLE * pBitmap; | /* pointer to the output LEAD bitmap */
L_UINT uStructSize; | /* size, in bytes of pBitmap */
L_INT nWidth; | /* width of pixels to be processed */
L_INT nHeight; | /* height of pixels to be processed */
L_INT nInAlign; | /* each scanline in the input buffer is a multiple of nInAlign bytes */
L_INT nOutAlign; | /* each scan line in the output buffer is a multiple of nOutAlign bytes */

Converts image data in a buffer from one color conversion model to RGB\BGR, and sets it as a LEAD bitmap.

Parameter | Description
ClrHandle | Handle to an existing color conversion. This handle is obtained by calling the L_ClrInit function.
pSrc | Pointer to the buffer holding the input data.
pBitmap | Pointer to the buffer that will hold the converted data bitmap.
uStructSize | Size in bytes, of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).
nWidth | Width of pixels to be processed.
nHeigh | Height of pixels to be processed.
nInAlign | Each scanline in the input buffer is a multiple of nInAlign bytes.
nOutAlign | Each scanline in the output buffer is a multiple of nOutAlign bytes.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

Conversion is done by setting the active method value specified in the CONVERSION_PARAMS structure when calling L_ClrInit. To change the active method, use L_ClrSetConversionParams. Only methods supported by the initialized converter should be specified.

The conversion is done if it was initialized with BGR or RGB Color Spaces as the destination.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrInit
Topics: | Conversion Process
 | COLOR Function Groups


L_ClrDlg

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrDlg(nDlg, hWnd, pClrHandle, pPramas)

L_INT nDlg; | /* dialog constant */
HANDLE hWnd; | /* handle to the parent window */
HANDLE * pClrHandle; | /* pointer to the output color handle */
LPCONVERSION_PARAMS pParams; | /* pointer to the output conversion params */

Displays a color space dialog box to initialize, and creates a color handle and CONVERSION_PARAMS data.

Parameter | Description
nDlg | The color space dialog to display. Possible values are:
 | Value | Meaning
 | DLG_CMYK | CMYK dialog.
 | DLG_LAB | LAB dialog.
hWnd | Handle to parent window.
pClrHandle | Pointer to color handle to be set by the dialog. Pass NULL if it is not needed.
pParams | Pointer to a CONVERSION_PARAMS structure to be set by the dialog. Pass NULL if it is not needed.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

This is another way of initializing the toolkit without using L_ClrInit. You can use it to retrieve a Color handle and/or a CONVERSION_PARAMS structure, for use later in initialization or modification by L_ClrSetConversionParams.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrInit
Topics: | Conversion Process
 | COLOR Function Groups


L_ClrFree

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrFree(ClrHandle)

HANDLE ClrHandle;

/* handle to the color conversion */

Frees the converter, releases any used resources, and invalidates the conversion handle.

Parameter | Description
ClrHandle | Handle to an existing color conversion. This handle is obtained by calling the L_ClrInit function.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

A color conversion handle is initialized by calling the L_ClrInit function.

For each call to L_ClrInit there must be a call to L_ClrFree. This function should be the last function to be called in the toolkit. It will clean up and free memory allocated during the color conversion session for the specified handle.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrInit
Topics: | Freeing the Color Conversion Handle
 | COLOR Function Groups

Example

For an example, refer to L_ClrInit.


L_ClrInit

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrInit(pClrHandle, nSrcFormat, nDstFormat, pParams)

HANDLE pClrHandle; | /* pointer to a color conversion handle */
L_INT nSrcFormat; | /* format of the input data */
L_INT nDstFormat; | /* format of the output data */
LPCONVERSION_PARAMS pParams; | /* pointer to a structure */

Initializes the color conversion engine.

Parameter | Description
pClrHandle | Pointer to a color conversion handle. This handle is needed in the conversion process and for setting the process options.
nSrcFormat | Format of the source data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color space is RGB.
 | CCS_YUV | [0x01] Color space is YUV.
 | CCS_CMYK | [0x02] Color space is CMYK.
 | CCS_HSV | [0x03] Color space is HSV.
 | CCS_HLS | [0x04] Color space is HLS.
 | CCS_YIQ | [0x05] Color space is YIQ.
 | CCS_CMY | [0x06] Color space is CMY.
 | CCS_LAB | [0x07] Color space is CIELAB.
 | CCS_XYZ | [0x08] Color space is CIEXYZ.
 | CCS_YCCK | [0x0B] Color space is YCCK.
 | CCS_YCCK | [0x0B] Color space is YCCK.
 | CCS_BGR | [0x0C] Color space is BGR.
 | CCS_UYVY | [0x0E] Color space is UYVY.
 | CCS_YUY2 | [0x09] Color space is YUY2.
 | CCS_YVU9 | [0x0A] Color space is YVU9.
 | CCS_YCC | [0x0F] Color space is YCC.
nDstFormat | Format of the output data. Possible values are:
 | Value | Meaning
 | CCS_RGB | [0x00] Color space is RGB.
 | CCS_YUV | [0x01] Color space is YUV.
 | CCS_CMYK | [0x02] Color space is CMYK.
 | CCS_HSV | [0x03] Color space is HSV.
 | CCS_HLS | [0x04] Color space is HLS.
 | CCS_YIQ | [0x05] Color space is YIQ.
 | CCS_CMY | [0x06] Color space is CMY.
 | CCS_LAB | [0x07] Color space is CIELAB.
 | CCS_XYZ | [0x08] Color space is CIEXYZ.
 | CCS_BGR | [0x0C] Color space is BGR.
 | CCS_UYVY | [0x0E] Color space is UYVY.
 | CCS_YUY2 | [0x09] Color space is YUY2.
 | CCS_YVU9 | [0x0A] Color space is YVU9.
 | CCS_YCC | [0x0F] Color space is YCC.
pParams | Pointer to a CONVERSION_PARAMS structure that contains the conversion properties used in the initialization.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

L_ClrInit must be called before calling any other LEADTOOLS Color Space toolkit functions in case of indirect conversion.

When the handle to the color conversion is no longer needed, it should be freed by calling L_ClrFree. For every call to L_ClrInit there must be a call to L_ClrFree.

If pParams is NULL, the default built in conversion is assumed, and any subsequent calls to L_ClrSetConversionParams will only affect CMYK conversion parameters.

When you choose the conversion method, be sure not to combine the Profiles option (USE_ICC) with the Custom Profiles option (USE_CUSTOM_ICC), or the Emulation Tables method (USE_ET) with the custom Emulation Tables method (USE_CUSTOM_ET).

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrConvert, L_ClrFree
Topics: | Initializing a Color Conversion Handle
 | COLOR Function Groups

Example

L_VOID ConvertCMYKToRGB(L_UCHAR * pInput, L_UCHAR *pOutput, L_INT nWidth, L_INT nHeight)
{
HANDLE ClrHandle /*Color Handle*/;

/*
Simple conversion without any options(NULL).
The conversion will be done with built-in options as the default option
*/

/* initialize the color conversion */
L_ClrInit(&ClrHandle,
CCS_CMYK,
CCS_RGB,
NULL);

/* convert the image buffer */
L_ClrConvert(ClrHandle, /* conversion handle */
pInput, /* input buffer */
pInput, /* output buffer */
nWidth, /*pixels width*/
nHeight, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/

/* free the conversion */
L_ClrFree(ClrHandle);
}


L_ClrIsValid

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrIsValid(ClrHandle)

HANDLE ClrHandle;

/* handle to the color conversion */

Determines whether the color conversion is valid to the conversion process.

Parameter | Description
ClrHandle | Handle to an existing color conversion. This handle is obtained by calling the L_ClrInit function.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

This function is useful for checking the validity of some conversion handle when using multiple converters.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrConvert
Topics: | Conversion Process
 | COLOR Function Groups

Example:

L_INT DoConvert(HANDLE ClrHandle, L_UCHAR *pInput, L_UCHAR *pOutput, L_INT nWidth, L_INT nHeight)
{
L_INT error_code; /* return error code*/

/* Check first the handle*/
error_code = L_ClrIsValid(ClrHandle);

if(error_code != SUCCESS)
return error_code;

/* Convert the image buffer */
return L_ClrConvert(ClrHandle, /*conversion handle*/
pInput, /*input buffer*/
pOutput,/*output buffer*/
nWidth, /*pixels width*/
nHeight, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/
}


L_ClrSetConversionParams

#include "ltkrn.h"
#include "ltclr.h"

L_INT EXT_FUNCTION L_ClrSetConversionParams(ClrHandle, pParams)

HANDLE ClrHandle; | /* handle to the color conversion */
LPCONVERSION_PARAMS pParams; | /* pointer to a structure */

Sets new conversion parameters.

Parameter | Description
ClrHandle | Handle to an existing color conversion. This handle is obtained by calling the L_ClrInit function.
pParams | Pointer to a CONVERSION_PARAMS structure, this structure will describe the conversion properties.

Returns

SUCCESS | The function was successful.
< 1 | An error occurred. Refer to Return Codes.

Comments

If pParams is NULL, this function will fail. A valid color conversion handle is needed. To check the handle validity, use L_ClrIsValid.

Required DLLs and Libraries

LTCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

See Also

Functions: | L_ClrConvert, L_ClrFree, L_ClrInit
Topics: | Conversion Process
 | COLOR Function Groups

Example

L_VOID ConvertCMYKToRGB(L_UCHAR *pInput, L_UCHAR *pOutput, L_INT nWidth)
{
HANDLE ClrHandle /*Color Handle*/;
CONVERSION_PARAMS params /*conversion options*/;
L_UCHAR *input_buffer /* input buffer */,
*output_buffer; /* output buffer */
L_INT height , width/* the number of pixels to convert */;

/*
Conversion with options.
The conversion will be done with the options specified in the params variable
*/

/* set the params size */
params.uStructSize = sizeof(CONVERSION_PARAMS);

/* we want to use the built in ICC conversion method and built in conversion */
params.nMethod = USE_BUILTIN | USE_ICC /* use built in conversion and LEAD ICC Engine*/;

/* set the active conversion method */
params.nActiveMethod = USE_BUILTIN;

/* allocate a D50 white point option */
params.pWpoint = (LPWHITEPOINT)malloc(sizeof(WHITEPOINT));
params.pWpoint->nWhitePoint = CIELAB_D50; /* D50 white point */

/* allocate a cmyk option */
params.pCmykParams = (LPCMYK_PARAMS)malloc(sizeof(CMYK_PARAMS));
params.pCmykParams->uStructSize = sizeof(CMYK_PARAMS);
params.pCmykParams->nMask = CMYK_GCR;
params.pCmykParams->nGcr_level = 175; /* 17.5 % GCR value */

/* initialize the color conversion */
L_ClrInit(&ClrHandle,
CCS_CMYK,
CCS_RGB,
NULL);
/* convert the image buffer */
L_ClrConvert(ClrHandle, /* conversion handle */
input_buffer, /* input buffer */
output_buffer, /* output buffer */
width, /*pixels width*/
height, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/

/* change the active method for conversion */
params.nMethod = CHANGE_ACTIVE_METHOD;
/* switch to ICC conversion method */
params.nActiveMethod = USE_ICC;

/* update the conversion state */
L_ClrSetConversionParams(ClrHandle, &params);

/* convert the image buffer */
L_ClrConvert(ClrHandle, /* conversion handle */
input_buffer, /* input buffer */
output_buffer, /* output buffer */
width, /*pixels width*/
height, /*pixels height*/
0, /* 0 bytes align*/
0); /*0 bytes align*/

/* free the conversion */
L_ClrFree (ClrHandle);

/* save the image */
/*...*/

free(params.pWpoint);
free(params.pCmykParams);
}


LEADTOOLS Reference Manuals

LEADTOOLS provides reference manuals that contain the same information as the online help. You can print them from PDF files. Please note that due to the large size of the PDF files that contain the LEADTOOLS manuals, these files are no longer included in the setup. Instead, these PDF files can be downloaded from our website at http://support.leadtools.com/SupportPortal/DesktopDefault.aspx?tabindex=3&tabid=27.

To print the PDF files, you must use the Adobe Acrobat Reader 3.0 or higher. You can download a copy of the Acrobat Reader from the Adobe web site (http://www.adobe.com). Note that different versions of the Acrobat Reader are available for different operating systems, but they all can read the same PDF files.


Topic Selection

LEAD Technologies, Inc.
Suite 400
1201 Greenwood Cliff
Charlotte, NC 28204

Sales@Leadtools.com
www.leadtools.com

(704) 332-5532
FAX: (704) 372-8161
Tech Support: (704) 372-9681

LEADTOOLS is ideal for developers involved in still frame, multimedia, document, medical, and vector imaging projects, including Internet/Intranet applications. Independent of the specific application requirement – scanning, file format support/conversion, compression, image processing, annotation, database support, multimedia, etc. – LEADTOOLS provides the most comprehensive, robust, flexible, and powerful imaging solution available.

Click this button to start the Licensing help file to review the License Agreements governing your use of the software.

Click this button to start the Products help file to review the full line of LEADTOOLS Products.

Click this button to start the Imaging help file to review the full line of LEADTOOLS Image Categories.


.topic 0x1f6
 Conversions
 When using the toolkit to convert a large image, you will obtain better performance if you convert a large number of pixels with each function call. In the following examples, a single call to L_ColorConvertDirect processes (1) the entire image or (2) an entire scanline:
 Use:
 (1)
(CCS_CMYK, CCS_RGB, pIn, pOut, 640, 480, 0, 0);
 or
 (2)
 for (int k=0; k<480; k++)
 L_ClrConvertDirect(CCS_CMYK, CCS_RGB, pIn, pOut, 640, 1, 0, 0);

 but not recommended to use:
 for (int k=0; k<480; k++)
 for (int k=0; k<640; k++)
 L_ClrConvertDirect(CCS_CMYK, CCS_RGB, pIn, pOut, 1, 1, 0, 0);

.topic 0x1f7
 Can be converted to:
 In some cases, to achieve better quality, it is recommended to divide the conversion into two steps. For example, if the conversion from CMYK to Lab is needed, convert from CMYK to RGB then from RGB to Lab. This lets you use other methods for the conversion like the ICC profiles or the emulation tables, which give better results. In addition to this, each color space can be converted to itself. This is sometimes needed for aligning or copying a buffer.
 There is also the USE_AUTO method, which guarantees the best conversion algorithm.
 Conversions from one color space to the same is supported with the built-in and custom icc options. The built-in conversion will perform a copy, while the custom icc depends on the input profiles. For example, a conversion from CIELab with D50 white point to CIELab with D65 white point can be done with D50-CIELab as input profile and D65-CIELab as output profile.

.topic 0x1f8
 YUV
 In addition to YUV support and the other commonly used YUV formats (YUY2, UYVY, Y41P, and YVU9), the toolkit supports generic YUV to RGB conversion, which enables the user to define other YUV formats or even his own YUV format using the YUV_PARAMS structure, then use  to do the conversion. For more information, see .


Canbeconvertedto

In some cases, to achieve better quality, it is recommended to divide the conversion into two steps. For example, if the conversion from CMYK to Lab is needed, convert from CMYK to RGB then from RGB to Lab. This lets you use other methods for the conversion like the ICC profiles or the emulation tables, which give better results. In addition to this, each color space can be converted to itself. This is sometimes needed for aligning or copying a buffer.

There is also the USE_AUTO method, which guarantees the best conversion algorithm.

Conversions from one color space to the same is supported with the built-in and custom icc options. The built-in conversion will perform a copy, while the custom icc depends on the input profiles. For example, a conversion from CIELab with D50 white point to CIELab with D65 white point can be done with D50-CIELab as input profile and D65-CIELab as output profile.


Conversions

When using the toolkit to convert a large image, you will obtain better performance if you convert a large number of pixels with each function call. In the following examples, a single call to L_ColorConvertDirect processes (1) the entire image or (2) an entire scanline:

Use:

(1)

L_ClrConvertDirect(CCS_CMYK, CCS_RGB, pIn, pOut, 640, 480, 0, 0);

or

(2)

for (int k=0; k<480; k++)

L_ClrConvertDirect(CCS_CMYK, CCS_RGB, pIn, pOut, 640, 1, 0, 0);

but not recommended to use:

for (int k=0; k<480; k++)

for (int k=0; k<640; k++)

L_ClrConvertDirect(CCS_CMYK, CCS_RGB, pIn, pOut, 1, 1, 0, 0);


YUV

In addition to YUV support and the other commonly used YUV formats (YUY2, UYVY, Y41P, and YVU9), the toolkit supports generic YUV to RGB conversion, which enables the user to define other YUV formats or even his own YUV format using the YUV_PARAMS structure, then use L_ClrConvert to do the conversion. For more information, see Generic YUV Conversion.