/usr/share/psychtoolbox-3/PsychCal/IccProfile.m

function icc=IccProfile(command,file)
% icc=IccProfile(command,file,icc)
%
% IccProfile.mex will read any ICC or ColorSync profile. The
% International Color Consortium (ICC) published a standard file
% format for saving color calibration data for imaging devices. This
% includes digital cameras, scanners, printers, and monitors. Users
% of the Psychophysics Toolbox will be primarily interested in the
% use of an ICC Profile to characterize their CRT monitor or LCD
% display. The idea is that the file contains all the necessary
% information to transform the specification of a color in a standard
% perceptual space (e.g. CIE X,Y,Z) into the numbers necessary to
% display that color.
% web http://www.color.org/profiles.html ;
%
% USAGE:
%
% icc=IccProfile('Read',file) % Gets data into Matlab.
% folder=IccProfile('Folder') % ColorSync Profiles folder
% file=IccProfile('Filename',screenNumber,newfile) % Get/set screen's profile.
% IccProfile('ShortDump',file,[tag]) % For exploring.
% IccProfile('Dump',file,[tag]) % ""
% IccProfile('LongDump',file,[tag]) % ""
%
% "file" is a filename, a partial or complete path, for an ICC
% Profile file. The default folder is the ColorSync Profiles
% folder (in the System Folder).
% "icc" is a Matlab struct.
% "folder" path string gives location of ColorSync Profiles folder.
% "tag" is a four-character string identifying a chunk of
% information in the icc profile, e.g. 'rTRC' for the red
% Tone Reproduction Curve (i.e. gamma curve for red phosphor)
% or 'gXYZ' for the the X,Y,Z color coordinates of the green
% phosphor.
% 'Read' returns a Matlab struct with one field for each tag in the
% profile. The field will still be present, but empty, if the
% tag is of an unknown type, or if an error was encountered in
% reading the tag. (Use 'Dump' to diagnose.) 'Read' recognizes
% most of the tag types relevant to monitor calibration.
% 'Folder' returns the path (a string) for the ColorSync Profiles folder.
% Use DIR(IccProfile('Folder')) to get a list of files there.
% 'Filename' get and/or set the filename of the profile associated with your
% screen. Or use the Monitors control panel (go to color) to choose.
% Note that setting the file has the side effect of loading
% the video card's gamma table from the 'vcgt', if present in
% your profile.
% 'Dump' describes every tag in the profile. Or just one tag.
% 'ShortDump' describes every tag in the profile, with less detail.
% 'LongDump' describes every tag in the profile, with more detail.
%
% EXAMPLE:
%
% file=iccprofile('filename',0)
% icc=iccprofile('read',file)
%
% This will read all the information in the profile associated with
% screen 0 (the main screen) and provide it to you as a handy Matlab struct
% "icc" that you can use in your software. For explanation of the contents,
% consult the official ICC documentation, plus Apple's documentation of
% their custom tags: 'vcgt' and 'mmod'.
% web http://www.color.org/profiles.html ;
% web http://developer.apple.com/techpubs/macos8/MultimediaGraphics/ColorSyncManager/ManagingColorWithColorSync/ColorSync.7b.html
%
% EXPLANATION OF TAG TYPE:
%
% Most of the information in a profile is stored as chunks of data,
% called elements. Each element has a unique 4-character tag name and
% a 4-character tag type. IccProfile accepts every tag name, and
% installs a corresponding field in your icc struct, with the same
% name (e.g. 'desc'). However, IccProfile will be able to transfer the
% content of the profile element to your struct only if IccProfile
% recognizes the type. At present, IccProfile can read the following
% tag types:
%
% NAME TYPE TAGS THAT USE IT.
% Profile description 'desc' 'desc'
% Tone reproduction curve 'curv' 'rTRC','gTRC','bTRC','kTRC'
% X,Y,Z of a color 'XYZ ' 'rXYZ','gXYX','bXYZ','wtpt','bkpt','lumi'
% Text string 'text' 'cprt'
% Date and time 'dtim' 'calt'
% Viewing conditions 'view' 'view'
% Measurement type 'meas' 'meas'
% Data (unformatted) 'data'
% Unsigned 8-bit int array 'ui08'
% Unsigned 16-bit int array 'ui16'
% Unsigned 32-bit int array 'ui32'
% Unsigned 64-bit int array 'ui64'
% Unsigned 32-bit fixed array 'uf32'
% Signed 32-bit fixed array 'sf32'
% Video card gamma 'vcgt' 'vcgt'
% Make and model 'mmod' 'mmod'
%
% TAG
% 'desc' profile description, a human readable text string
% 'rTRC' red tone reproduction curve
% 'gTRC' green tone reproduction curve
% 'bTRC' blue tone reproduction curve
% 'kTRC' gray tone reproduction curve
% 'rXYZ' red phosphor color
% 'gXYZ' green phosphor color
% 'bXYZ' blue phosphor color
% 'wtpt' white point
% 'bkpt' black point
% 'lumi' luminance in cd/m^2
% 'cprt' copyright
% 'calt' calibration date and time
% 'view' viewing conditions
% 'meas' measurement type
% 'vcgt' custom Apple tag for video card gamma table
% 'mmod' custom Apple tag for make and model of the device
%
% NOTE: IccProfile may report errors in an apparently good profile.
% This is because icclib enforces the ICC standard more strictly than
% ColorSync does, so it picks up errors that were previously missed.
% (On 7/31/00 we reported to Apple two such errors, affecting most of their
% ColorSync Profiles, and added a work-around to IccProfile.)
% You can try running Apple's "Profile First Aid", which detects and
% fixs some common profile errors, though it too is less strict than
% icclib. "Profile First Aid" 3.0.1 is installed in the Apple
% Extras:ColorSync Extras folder when you install ColorSync 3.0.1
% web http://asu.info.apple.com/swupdates.nsf/artnum/n11674 ;
%
% CALIBRATION:
%
% You can buy a calibration package consisting of a program (e.g.
% ColorBlind ProveIt! or Monaco EZColor) and a simple colorimeter to
% easily create an ICC profile for your monitor. Using IccProfile.mex,
% it should be easy to use that calibration data to do your color
% corrections, but we haven't actually tried that yet. Here are a few
% calibrators that seems to be good, from what we've read. We've
% included links to the manufacturer (if available) and to Jon Cone's
% inkjetmall web site because he knows a lot about digital
% printing and has good advice about choosing among these products.
%
% ColorBlind ProveIt! software $50
% Does not include colorimeter. Can be used alone, using perceptual
% matching, or with the Sequel Chroma 4 colorimeter, below.
% web http://www.color.com/Products/proveit.html ;
% web http://www.inkjetmall.com/store/prove-it.html ;
%
% Sequel Chroma 4 CRT & LCD monitor colorimeter $249
% Requires software, which is not included. Compatible with ColorBlind
% and Monaco.
% web http://www.inkjetmall.com/store/measuring-devices.html#monitors ;
%
% Monaco EZColor software $299
% MonacoSENSOR colorimeter $249 (or both together for $499)
% web http://www.monacosys.com/monacoezcolor.html ;
%
% The ColorBlind+Sequel package, for $299, is cheaper than the $499
% Monaco package, and the ColorBlind software seems to be at least as
% highly regarded as Monaco's by Jon Cone and others using it to
% calibrate their monitors for critical digital color printing.
%
% Denis Pelli
%
% ACKNOWLEDGEMENT: IccProfile.mex is largely a Matlab interface to
% the excellent free icclib created in C by Graeme Gill, for which we
% are very grateful.
% web http://web.access.net.au/argyll/color.html ;

% HISTORY
% 7/28/00 dgp Wrote it, using Graeme Gill's icclib.c.
% 7/29/00 dgp Recommend ColorBlind ProveIt!
% 7/30/00 dgp The default folder is now the ColorSync Profiles folder.
% 8/1/00 dgp Make compatible with ColorSync Profiles by relaxing checking.
% 8/1/00 dgp Read 'vcgt' and 'data' types.
% 8/2/00 dgp Drop all mention of writing, since we're dropping that feature.
% 8/3/00 dgp Add 'Filename' function.

psychtoolbox-3-common 3.0.9+svn2579.dfsg1-1 / usr / share / psychtoolbox-3 / PsychCal / IccProfile.m