Inspect and Load X Colour Profiles with xcmsdb

xcmsdb reads and writes the X colour data attached to your screen, covering queries, loading a characterisation file and safe removal. The examples are for xcmsdb 1.0.6, installed here by x11-xserver-utils 7.7+10build2. Allow about 15 minutes if you already have an X display and a device-characterisation file supplied by your display setup.

This is an X11 task, not a colour-profile conversion tool. xcmsdb writes properties on the root window. It does not install an ICC file, change a monitor's firmware, or configure a display server. You need access to the target X display, normally through the correct DISPLAY and X authority credentials. None of the examples needs sudo; using elevated privileges does not grant access to another user's X session.

1. Confirm the installed command

Start with the version and option summary. These checks do not contact an X server or change its properties:

$ command -v xcmsdb
/usr/bin/xcmsdb
$ xcmsdb -version
xcmsdb 1.0.6
$ xcmsdb -help
usage:  xcmsdb [-options ...] [filename]

The local help also lists the display, format, query, remove and version options. The installed package version matters here because command-line help is a better description of the binary you will actually run than a guide written for a different distribution.

Checkpoint: If command -v finds nothing, stop and install or repair the package through your normal system administration process. Do not create a replacement script called xcmsdb.

2. Select the display without changing it

Set DISPLAY to the X screen whose root-window properties you need to inspect. Use the value already associated with the desktop session when possible:

$ printf 'display: %s\n' "${DISPLAY:-<unset>}"
$ export DISPLAY=':0'

Replace :0 with the real display value. A display name can include a host and screen, such as host.example:0.0. The program reads DISPLAY to choose the display and screen; do not assume that a terminal opened over SSH points at the local desktop.

Test access with a read-only query:

$ xcmsdb -query
<device characterisation data for the selected screen, if present>

The exact report depends on the properties on that screen. With no accessible X server, the command exits non-zero and reports an error such as xcmsdb: Can't open display ''. That is a display or authorisation problem, not evidence that the profile is absent. Check DISPLAY and the session's X authority before trying other options.

3. Understand what a query is reading

A successful query reads device colour-characterisation data from the screen's root window and formats it for people. The standard data is split across two properties:

Xlib can also use function sets with their own, non-standard profile properties. xcmsdb does not know those formats, so an empty or partial standard report does not prove that every colour-management mechanism on the display is empty.

For a second, low-level view, use xprop against the same display:

$ xprop -root | grep -E 'XDCCC_LINEAR_RGB_(MATRICES|CORRECTION)'

xprop may print one or both properties, or nothing if they are not present. Keep the two commands pointed at the same display. Looking at a different desktop is an easy way to misdiagnose a correct configuration.

4. Load a supplied characterisation file

Loading is the state-changing operation. Obtain the input file from the display vendor, calibration process or administrator responsible for the X setup. Do not invent a file from a generic ICC profile: the input is ASCII data that xcmsdb transforms into X properties, and the manpage does not define a universal example file.

Once you have verified the file and selected the display, load it by supplying its path:

$ PROFILE_FILE='/path/to/verified-device-characterisation.txt'
$ test -r "$PROFILE_FILE"
$ xcmsdb "$PROFILE_FILE"
$ xcmsdb -query

With no -query or -remove, the program reads the named file. If you omit the filename, it reads standard input, so this equivalent form is useful for a controlled pipeline:

$ xcmsdb < "$PROFILE_FILE"

Do not redirect an accidental diagnostic stream into the profile input. Keep the file path quoted, and check the query result after loading. A successful process exit means the operation completed for the selected display; it does not validate the colour science or prove that every X client will use the data.

5. Choose the correction-property precision

The correction property can store entries at 32, 16 or 8 bits per entry. The default is 32 bits. More bits allow more precision for encoded floating-point values, but the option does not improve an inaccurate source file.

$ xcmsdb -format 16 "$PROFILE_FILE"
$ xcmsdb -query

Use -format 32, -format 16 or -format 8, with the format chosen before the filename. If you have no compatibility requirement for a consumer that expects lower precision, leave the default in place. Record the choice alongside the source file so a later operator can reproduce the result.

6. Remove the data only when you mean to

Warning: -remove deletes the standard XDCCC properties from the selected screen's root window. It can affect colour conversions for X clients that use Xcms. There is no undo option in xcmsdb.

Before removal, save a readable report and the original input file if you have one:

$ xcmsdb -query > "$HOME/xcmsdb-before-remove.txt"
$ cp --preserve=mode,timestamps "$PROFILE_FILE" "$HOME/xcmsdb-profile-backup.txt"
$ xcmsdb -remove
$ xcmsdb -query

The final query should show the resulting state for that display. To recover, load the preserved, verified characterisation file again with the same format choice. If the original data was not backed up, ask the calibration or desktop administrator for the authoritative source instead of reconstructing values by hand.

7. Diagnose the common traps

Done means