.\" pragma ident "@(#)KcsUpdateProfile.3	1.3  04/21/95"
.TH KcsUpdateProfile 3 "21 April 1995" "" "KCMS Library"
.SH NAME
KcsUpdateProfile \-  Update a profile with characterization or
calibration data
.SH SYNOPSIS
.ft B
.nf
#include <kcms/kcs.h>
#include <kcms/kcstypes.h>
.sp
KcsStatusId KcsUpdateProfile(
		KcsProfileId		profile,
		KcsCharacterizationData	*charact, 
		KcsCalibrationData	*calib, 
		void			*CMMSpecificData)
.fi
.ft R
.SH MT-LEVEL
MT-Unsafe
.SH DESCRIPTION
Use 
.B KcsUpdateProfile()
to change the profile data in the 
loaded profile according to the supplied color patches.
.PP
The data which must be supplied to this call depends on the type 
of device that the profile represents. The two device types 
supported by the default CMM are scanners, and monitors. 
Printer profiles are not currently supported. This API will also be 
used for printers, when implemented by the default or 
alternative CMMs. The data required for this call depends on 
whether the profile is to be calibrated or characterized.
.PP
Calibration refers to bringing the profile to a known state which 
is equivalent for all color-managed devices with the same color 
response, after characterization.
.PP
Characterization refers to changing the profile data so that the 
profile will allow the device to be color-managed to produce the 
same color response, in spite of device to device variations. 
Characterization requires colorimetric measurements. How these 
measurements are used to update a profile is described below 
and in the examples.
.SH ARGUMENTS
.TP
.SB profile
The identifier of the profile to be updated.
.TP
.SB charact
A set of color sample measurements where sample is a color 
patch on a test target. 
.sp
For a scanner, this is a target that is scanned. In this case, each 
sample measurement consists of an input which is the CIE XYZ 
value of the patch, as measured. The sample output is the RGB 
value that the scanner produced when scanning the patch. In 
addition, each color sample contains fields for the sample weight, 
standard deviation, and sample type. The weight is a hint 
indicating the importance of the sample color. The default should 
be to set to 1.0. The standard deviation is used to indicate the 
statistics of a set of measurements of the sample color which 
have been reduced to a single sample. The sample type is used to 
indicate that a color sample represents either black, white, other, 
neutral, or chromatic color. For best results, the sample type field 
should be correctly set for each color sample. For example, the 
sample type KcsFluorescent can be used to tag special color 
samples with this property. The sample type is a hint passed by 
the KCMS framework to the CMM.
.sp
Note that CIE XYZ values are to be scaled in the range 0.0 to 
100.0 and that RGB values are to be scaled in range 0.0 to 1.0. For 
additional details, see this document, Chapter 5, Data Structures, 
KcsCharacterizationData. 
.sp
Monitors do not use the charact argument. Pointer *charact 
should be set to NULL when 
.B KcsUpdateProfile()
is called for a monitor profile. For a monitor, characterization 
data consists of the profile attributes 
icSigRedColorantTag,
icSigGreenColorantTag,
icSigBlueColorantTag, and 
icSigMediaWhitePointTag. These attributes must be set and 
valid prior to calling 
.B KcsUpdateProfile(). 
Use KcsSetAttribute to set these attributes.
.TP
.SB calib
The linearization tables needed to calibrate the profile. These 
tables are required to calibrate all device types. They are also 
required when calling 
.B KcsUpdateProfile() 
to characterize a scanner or monitor. Both the input and output spaces are 
KcsSpaceRGB for a scanner and monitor. The RGB samples are 
scaled in the range of 0.0 to 1.0. 
.TP
.SB CMMSpecificData
A pointer to any additional data needed by a specific CMM to 
update the profile. Refer to the CMM documentation for any 
specific data required. For use with the default CMM, set this 
argument to NULL.
.SH RETURN VALUES
Upon successful completion KCS_SUCCESS is returned. Otherwise
one of the following errors will be returned.
.SH ERRORS
.nf
KCS_MEM_ALLOC_ERROR
KCS_CC_UPDATE_NEEDS_MORE_DATA
KCS_CC_UPDATE_INVALIDE_DATA
.fi
.SH SEE ALSO
.BR KcsLoadProfile (3)
.BR KcsCreateProfile (3)
.BR KcsSaveProfile (3)
.BR KcsUpdateProfile (3)
.br
.BR "KCMS Application Developers Guide"