Cyotek Development Bloghttps://devblog.cyotek.com/tag/aco/atom.xml2014-01-28T18:25:09ZWriting Photoshop Color Swatch (aco) files using C#urn:uuid:185a2dfb-dc4d-479e-b09c-1289092e44142014-01-28T18:25:09Z2014-01-28T18:25:09Z<p>The <a href="/post/reading-photoshop-color-swatch-aco-files-using-csharp">previous article</a> in this mini-series described how to
read files in Abode's Colour File format as used by applications
such as Photoshop and other drawing programs.</p>
<p>In this second article, I'll describe how to write such files.</p>
<div class="article-gallery">
<a href="https://images.cyotek.com/image/devblog/savephotoshopcolorswatch1.png" class="gallery" title="RGB - " ><img src="https://images.cyotek.com/image/thumbnail/devblog/savephotoshopcolorswatch1.png" alt="RGB" decoding="async" loading="lazy" /></a><a href="https://images.cyotek.com/image/devblog/savephotoshopcolorswatch2.png" class="gallery" title="HSL - " ><img src="https://images.cyotek.com/image/thumbnail/devblog/savephotoshopcolorswatch2.png" alt="HSL" decoding="async" loading="lazy" /></a><a href="https://images.cyotek.com/image/devblog/savephotoshopcolorswatch3.png" class="gallery" title="Grayscale - " ><img src="https://images.cyotek.com/image/thumbnail/devblog/savephotoshopcolorswatch3.png" alt="Grayscale" decoding="async" loading="lazy" /></a></div>
<h2 id="getting-started">Getting started</h2>
<p>I'm not going to go over the structure again, so if you haven't
already done so, please read the previous article <a href="/post/reading-photoshop-color-swatch-aco-files-using-csharp">Reading
Photoshop Color Swatch (aco) files using C#</a> for full details
on the file structure and how to read it.</p>
<h2 id="writing-big-endian-values">Writing big-endian values</h2>
<p>All the data in an <code>aco</code> file is stored in <a href="http://en.wikipedia.org/wiki/Endianness" rel="external nofollow noopener">big-endian</a>
format and therefore needs to be reversed on Windows systems
before writing it back into the file.</p>
<p>We can use the following two methods to write a <code>short</code> or a
<code>int</code> respectively into a stream as a series of bytes. Of
course, if you just want functions to convert these into bytes
you could use similar code, just remove the bit-shift.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">private</span> <span class="keyword">void</span> WriteInt<span class="number">16</span><span class="symbol">(</span>Stream stream<span class="symbol">,</span> <span class="keyword">short</span> value<span class="symbol">)</span>
<span class="symbol">{</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span>value <span class="symbol">&gt;&gt;</span> <span class="number">8</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span>value <span class="symbol">&gt;&gt;</span> <span class="number">0</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>

<span class="keyword">private</span> <span class="keyword">void</span> WriteInt<span class="number">32</span><span class="symbol">(</span>Stream stream<span class="symbol">,</span> <span class="keyword">int</span> value<span class="symbol">)</span>
<span class="symbol">{</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span><span class="symbol">(</span>value <span class="symbol">&amp;</span> <span class="number">0xFF000000</span><span class="symbol">)</span> <span class="symbol">&gt;&gt;</span> <span class="number">24</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span><span class="symbol">(</span>value <span class="symbol">&amp;</span> <span class="number">0x00FF0000</span><span class="symbol">)</span> <span class="symbol">&gt;&gt;</span> <span class="number">16</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span><span class="symbol">(</span>value <span class="symbol">&amp;</span> <span class="number">0x0000FF00</span><span class="symbol">)</span> <span class="symbol">&gt;&gt;</span> <span class="number">8</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 stream<span class="symbol">.</span>WriteByte<span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span><span class="symbol">(</span><span class="symbol">(</span>value <span class="symbol">&amp;</span> <span class="number">0x000000FF</span><span class="symbol">)</span> <span class="symbol">&gt;&gt;</span> <span class="number">0</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<p>As with the equivalent read functions, the <code>&gt;&gt; 0</code> shift is
unnecessary but it does clarify the code.</p>
<p>We also need to store colour swatch names, so again we'll make
use of the <code>Encoding.BigEndianUnicode</code> property to convert a
string into a series of bytes to write out.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">private</span> <span class="keyword">void</span> WriteString<span class="symbol">(</span>Stream stream<span class="symbol">,</span> <span class="keyword">string</span> value<span class="symbol">)</span>
<span class="symbol">{</span>
 stream<span class="symbol">.</span>Write<span class="symbol">(</span>Encoding<span class="symbol">.</span>BigEndianUnicode<span class="symbol">.</span>GetBytes<span class="symbol">(</span>value<span class="symbol">)</span><span class="symbol">,</span> <span class="number">0</span><span class="symbol">,</span> value<span class="symbol">.</span>Length <span class="symbol">*</span> <span class="number">2</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<h2 id="writing-the-file">Writing the file</h2>
<p>When writing the file, I'm going to follow the specification's
suggestion of writing a version 1 palette (for backwards
compatibility), followed by a version 2 palette (for
applications that support swatch names).</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">using</span> <span class="symbol">(</span>Stream stream <span class="symbol">=</span> File<span class="symbol">.</span>Create<span class="symbol">(</span>fileName<span class="symbol">)</span><span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">this</span><span class="symbol">.</span>WritePalette<span class="symbol">(</span>stream<span class="symbol">,</span> palette<span class="symbol">,</span> FileVersion<span class="symbol">.</span>Version<span class="number">1</span><span class="symbol">,</span> ColorSpace<span class="symbol">.</span>Rgb<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WritePalette<span class="symbol">(</span>stream<span class="symbol">,</span> palette<span class="symbol">,</span> FileVersion<span class="symbol">.</span>Version<span class="number">2</span><span class="symbol">,</span> ColorSpace<span class="symbol">.</span>Rgb<span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<p>The core save routine follows. First, we write the version of
format and then the number of colours in the palette.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">private</span> <span class="keyword">void</span> WritePalette<span class="symbol">(</span>Stream stream<span class="symbol">,</span> ICollection<span class="symbol">&lt;</span>Color<span class="symbol">&gt;</span> palette<span class="symbol">,</span> FileVersion version<span class="symbol">,</span> ColorSpace colorSpace<span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">int</span> swatchIndex<span class="symbol">;</span>

 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span>version<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span>palette<span class="symbol">.</span>Count<span class="symbol">)</span><span class="symbol">;</span>

 swatchIndex <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
</pre>
</figure>
<p>With that done, we loop through each colour, calculate the four
values that comprise the colour data and then write that.</p>
<p>If it's a version 2 file, we also write the swatch name. As
these basic examples are just using the <code>Color</code> class, there's
no real flexibility in names, so we cheat - if it's a &quot;named&quot;
colour, then we use the <code>Color.Name</code> property. Otherwise, we
generate a <code>Swatch &lt;index&gt;</code> name.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
 <span class="keyword">foreach</span> <span class="symbol">(</span>Color color <span class="keyword">in</span> palette<span class="symbol">)</span>
 <span class="symbol">{</span>
 <span class="keyword">short</span> value<span class="number">1</span><span class="symbol">;</span>
 <span class="keyword">short</span> value<span class="number">2</span><span class="symbol">;</span>
 <span class="keyword">short</span> value<span class="number">3</span><span class="symbol">;</span>
 <span class="keyword">short</span> value<span class="number">4</span><span class="symbol">;</span>

 swatchIndex<span class="symbol">++</span><span class="symbol">;</span>

 <span class="keyword">switch</span> <span class="symbol">(</span>colorSpace<span class="symbol">)</span>
 <span class="symbol">{</span>
 <span class="comment">// Calculate color space values here!</span>
 <span class="keyword">default</span><span class="symbol">:</span>
 <span class="keyword">throw</span> <span class="keyword">new</span> InvalidOperationException<span class="symbol">(</span><span class="string">&quot;Color space not supported.&quot;</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>

 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span>colorSpace<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> value<span class="number">1</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> value<span class="number">2</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> value<span class="number">3</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">,</span> value<span class="number">4</span><span class="symbol">)</span><span class="symbol">;</span>

 <span class="keyword">if</span> <span class="symbol">(</span>version <span class="symbol">==</span> FileVersion<span class="symbol">.</span>Version<span class="number">2</span><span class="symbol">)</span>
 <span class="symbol">{</span>
 <span class="keyword">string</span> name<span class="symbol">;</span>

 name <span class="symbol">=</span> color<span class="symbol">.</span>IsNamedColor <span class="symbol">?</span> color<span class="symbol">.</span>Name <span class="symbol">:</span> <span class="keyword">string</span><span class="symbol">.</span>Format<span class="symbol">(</span><span class="string">&quot;Swatch {0}&quot;</span><span class="symbol">,</span> swatchIndex<span class="symbol">)</span><span class="symbol">;</span>

 <span class="keyword">this</span><span class="symbol">.</span>WriteInt<span class="number">32</span><span class="symbol">(</span>stream<span class="symbol">,</span> name<span class="symbol">.</span>Length<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">this</span><span class="symbol">.</span>WriteString<span class="symbol">(</span>stream<span class="symbol">,</span> name<span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>
 <span class="symbol">}</span>
<span class="symbol">}</span>
</pre>
</figure>
<h2 id="converting-colour-spaces">Converting colour spaces</h2>
<p>As previously mentioned, the <a href="http://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1055819" rel="external nofollow noopener">specification</a> states that each
colour is comprised of four values. Even if a particular colour
space doesn't use all four (for example <code>Grayscale</code> just uses
one, you still need to write the other values, typically as
zero's.</p>
<p>Although it's a slight duplication, I'll include the description
table for colour spaces to allow easy reference of the value
types.</p>
<table>
<thead>
<tr>
<th style="text-align: right;">Id</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: right;">0</td>
<td>RGB. The first three values in the colour data are red, green, and blue. They are full unsigned 16-bit values as in Apple's RGBColordata structure. Pure red = 65535, 0, 0.</td>
</tr>
<tr>
<td style="text-align: right;">1</td>
<td>HSB. The first three values in the colour data are hue, saturation, and brightness. They are full unsigned 16-bit values as in Apple's HSVColordata structure. Pure red = 0,65535, 65535.</td>
</tr>
<tr>
<td style="text-align: right;">2</td>
<td>CMYK. The four values in the colour data are cyan, magenta, yellow, and black. They are full unsigned 16-bit values. For example, pure cyan = 0,65535,65535,65535.</td>
</tr>
<tr>
<td style="text-align: right;">7</td>
<td>Lab. The first three values in the colour data are lightness, a chrominance, and b chrominance. Lightness is a 16-bit value from 0...10000. Chrominance components are each 16-bit values from -12800...12700. Gray values are represented by chrominance components of 0. Pure white = 10000,0,0.</td>
</tr>
<tr>
<td style="text-align: right;">8</td>
<td>Grayscale. The first value in the colour data is the gray value, from 0...10000.</td>
</tr>
</tbody>
</table>
<p>While supporting <code>CMYK</code> colours are beyond the scope of this
article as they require colour profiles, and I haven't the
foggiest on the <code>Lab</code> space, we can easily support <code>RGB</code>, <code>HSL</code>
and <code>Grayscale</code> spaces.</p>
<p>RGB is the simplest as .NET colours are already in this format.
The only thing we have to do is multiple each channel by 256 as
the specification uses the range 0-65535 rather than the typical
0-255.</p>
<p>Notice <code>value4</code> is simply initialized to zero as this space only
needs 3 of the 4 values.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
 <span class="keyword">case</span> ColorSpace<span class="symbol">.</span>Rgb<span class="symbol">:</span>
 value<span class="number">1</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>R <span class="symbol">*</span> <span class="number">256</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">2</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>G <span class="symbol">*</span> <span class="number">256</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">3</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>B <span class="symbol">*</span> <span class="number">256</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">4</span> <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<p>We can also support HSL without too much trouble as the <code>Color</code>
class already includes methods for extracting these values.
Again, we need to do a little fiddling to change the numbers
into the range used by the specification.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
 <span class="keyword">case</span> ColorSpace<span class="symbol">.</span>Hsb<span class="symbol">:</span>
 value<span class="number">1</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>GetHue<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">*</span> <span class="number">182.04</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">2</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>GetSaturation<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">*</span> <span class="number">655.35</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">3</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>GetBrightness<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">*</span> <span class="number">655.35</span><span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">4</span> <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<p>The last format we can easily support is grayscale. If the
source colour is already grey (i.e. the red, green and blue
channels are all the same value), then we use that, otherwise
we'll average the 3 channels and use that as the value.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
 <span class="keyword">case</span> ColorSpace<span class="symbol">.</span>Grayscale<span class="symbol">:</span>
 <span class="keyword">if</span> <span class="symbol">(</span>color<span class="symbol">.</span>R <span class="symbol">==</span> color<span class="symbol">.</span>G <span class="symbol">&amp;&amp;</span> color<span class="symbol">.</span>R <span class="symbol">==</span> color<span class="symbol">.</span>B<span class="symbol">)</span>
 <span class="symbol">{</span>
 <span class="comment">// already grayscale</span>
 value<span class="number">1</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span>color<span class="symbol">.</span>R <span class="symbol">*</span> <span class="number">39.0625</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>
 <span class="keyword">else</span>
 <span class="symbol">{</span>
 <span class="comment">// color is not grayscale, convert</span>
 value<span class="number">1</span> <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">short</span><span class="symbol">)</span><span class="symbol">(</span><span class="symbol">(</span><span class="symbol">(</span>color<span class="symbol">.</span>R <span class="symbol">+</span> color<span class="symbol">.</span>G <span class="symbol">+</span> color<span class="symbol">.</span>B<span class="symbol">)</span> <span class="symbol">/</span> <span class="number">3.0</span><span class="symbol">)</span> <span class="symbol">*</span> <span class="number">39.0625</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>
 value<span class="number">2</span> <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
 value<span class="number">3</span> <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
 value<span class="number">4</span> <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<h2 id="demo-application">Demo Application</h2>
<p>The usual sample application is available from the links at the
end of this article. The sample generates a random 256 colour
palette, then writes this to a temporary file using the
specified colour space. It then reads it back in, and displays
both palettes side by side for comparison.</p>
<h2 id="update-history">Update History</h2>
<ul>
<li>2009-08-10 - First published</li>
<li>2020-11-21 - Updated formatting</li>
</ul>

<p><small>
All content <a href="https://devblog.cyotek.com/copyright-and-trademarks">Copyright (c) by Cyotek Ltd</a> or its respective writers. Permission to reproduce news and web log entries and other RSS feed content in unmodified form without notice is granted provided they are not used to endorse or promote any products or opinions (other than what was expressed by the author) and without taking them out of context. Written permission from the copyright owner must be obtained for everything else.<br />Original URL of this content is https://devblog.cyotek.com/post/writing-photoshop-color-swatch-aco-files-using-csharp .
</small></p>Richard Mosshttps://www.cyotek.com/richard.moss@cyotek.comReading Photoshop Color Swatch (aco) files using C#urn:uuid:a613a036-56f1-4668-bbe2-c782192200a92014-01-22T21:27:55Z2014-01-22T21:27:55Z<p>In a <a href="/post/loading-the-color-palette-from-a-bbm-lbm-image-file-using-csharp">previous article</a> I described how to read the colour
map from a DeluxePaint LBM/BBM file. In the next pair of
articles, I'm going to describe how to load and save colour
swatch files used by Photoshop (those with the <code>.aco</code>
extension).</p>
<figure class="screenshot" ><a href="https://images.cyotek.com/image/devblog/loadphotoshopcolorswatch.png" class="gallery" title="A sample application showing loading of colour swatches from Photoshop colour swatch files" ><img src="https://images.cyotek.com/image/thumbnail/devblog/loadphotoshopcolorswatch.png" alt="A sample application showing loading of colour swatches from Photoshop colour swatch files" decoding="async" loading="lazy" /></a><figcaption>A sample application showing loading of colour swatches from Photoshop colour swatch files</figcaption></figure><h2 id="caveat-emptor">Caveat Emptor</h2>
<p>As usual, I'll start with a warning. I have a very limited set
of sample files to test with, so it may be that there's an error
in this code which means it can't handle all files. Certainly it
can't handle all colour spaces (more on that later). However,
I've tested it on a number of files download from the internet
without problems.</p>
<h2 id="structure-of-a-photoshop-colour-swatch-file">Structure of a Photoshop colour swatch file</h2>
<p>The structure of the <code>aco</code> file is straightforward, helped by
Adobe themselves publishing the <a href="http://www.adobe.com/devnet-apps/photoshop/fileformatashtml/#50577411_pgfId-1055819" rel="external nofollow noopener">specification</a> which is
something to appreciate. This article was created using the
October 2013 edition of this specification.</p>
<p>According to the specification, there's two versions of the
format both of which are are fairly similar. The specification
also implies that applications which support version 2 should
write a version 1 palette first, which would admirably solve
backwards compatibility problems. In practice this doesn't seem
to be the case, as some of the files I tested only had version 2
palettes in them.</p>
<p>The structure is simple. There's a 2-byte version code, followed
by 2-bytes describing the number of colours. Then, for each
colour, there are 10 further bytes, 2 each describing the colour
space and then four values to describe the colour. Version two
palettes also then follow this with a four byte integer
describing the length of the name, then the bytes which make up
said name.</p>
<table class="table table-condensed table-bordered">
 <thead>
 <tr>
 <th>Length
 </th>
 <th>Description
 </th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>2</td>
 <td>Version</td>
 </tr>
 <tr>
 <td>2</td>
 <td>Number of colours</td>
 </tr>
 <tr>
 <td rowspan="2">count * 10 <em>(+ 4 + variable (version 2 only))</em>
 </td>
 <td>
 <p> Colour data</p>
 <table class="table table-condensed table-bordered">
 <thead>
 <tr>
 <th>Length
 </th>
 <th>Description
 </th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>2</td>
 <td>Colour space</td>
 </tr>
 <tr>
 <td>2</td>
 <td>Colour data value 1</td>
 </tr>
 <tr>
 <td>2</td>
 <td>Colour data value 2</td>
 </tr>
 <tr>
 <td>2</td>
 <td>Colour data value 3</td>
 </tr>
 <tr>
 <td>2</td>
 <td>Colour data value 4</td>
 </tr>
 </tbody>
 </table>
 </td>
 </tr>
 <tr>
 <td>
 <p><em>Version 2 only</em></p>
 <table class="table table-condensed table-bordered">
 <thead>
 <tr>
 <th>Length
 </th>
 <th>Description
 </th>
 </tr>
 </thead>
 <tbody>
 <tr>
 <td>4</td>
 <td>Length of name string in characters</td>
 </tr>
 <tr>
 <td>length * 2</td>
 <td>Unicode code characters, two bytes per character</td>
 </tr>
 </tbody>
 </table>
 </td>
 </tr>
 </tbody>
</table>
<p>All the data in an <code>aco</code> file is stored in <a href="http://en.wikipedia.org/wiki/Endianness" rel="external nofollow noopener">big-endian</a>
format and therefore needs to be reversed on Windows systems.</p>
<p>Most colour spaces only use three of the four available values,
but regardless of how many are actually used, all must be
specified.</p>
<h2 id="colour-spaces">Colour Spaces</h2>
<p>I mentioned above that each colour has a description of what
colour space it belongs to. The specification defines the
following colour spaces:</p>
<table>
<thead>
<tr>
<th style="text-align: right;">Id</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: right;">0</td>
<td>RGB. The first three values in the colour data are red, green, and blue. They are full unsigned 16-bit values as in Apple's RGBColordata structure. Pure red = 65535, 0, 0.</td>
</tr>
<tr>
<td style="text-align: right;">1</td>
<td>HSB. The first three values in the colour data are hue, saturation, and brightness. They are full unsigned 16-bit values as in Apple's HSVColordata structure. Pure red = 0,65535, 65535.</td>
</tr>
<tr>
<td style="text-align: right;">2</td>
<td>CMYK. The four values in the colour data are cyan, magenta, yellow, and black. They are full unsigned 16-bit values. For example, pure cyan = 0,65535,65535,65535.</td>
</tr>
<tr>
<td style="text-align: right;">7</td>
<td>Lab. The first three values in the colour data are lightness, a chrominance, and b chrominance. Lightness is a 16-bit value from 0...10000. Chrominance components are each 16-bit values from -12800...12700. Gray values are represented by chrominance components of 0. Pure white = 10000,0,0.</td>
</tr>
<tr>
<td style="text-align: right;">8</td>
<td>Grayscale. The first value in the colour data is the gray value, from 0...10000.</td>
</tr>
</tbody>
</table>
<p>To avoid complicating matters, this article will concentrate on
<code>RGB</code> and <code>Grayscale</code> colour spaces, although I'll include the
basics of <code>HSV</code> too for if you have a conversion class kicking
around.</p>
<h2 id="reading-shortint-data-types-from-bytes">Reading short/int data types from bytes</h2>
<p>As I mentioned above, the values in this file format are all
big-endian. As Windows uses little-endian, we need to do some
bit shifting when we read each byte comprising either a <code>short</code>
(<code>Int16</code>) or an <code>int</code> (<code>Int32</code>), using the following helpers:</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="selector-tag">///</span> <span class="selector-tag">&lt;summary&gt;</span>
<span class="selector-tag">///</span><span class="comment"> Reads a 16bit unsigned integer in big-endian format.</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;/summary&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;param name=&quot;stream&quot;&gt;</span><span class="comment">The stream to read the data from.&lt;/param&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;returns&gt;</span><span class="comment">The unsigned 16bit integer cast to an &lt;c&gt;Int32&lt;/c&gt;.&lt;/returns&gt;</span>
<span class="keyword">private</span> <span class="keyword">int</span> ReadInt<span class="number">16</span><span class="symbol">(</span>Stream stream<span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">return</span> <span class="symbol">(</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">8</span><span class="symbol">)</span> <span class="symbol">|</span> <span class="symbol">(</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">0</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>

<span class="selector-tag">///</span> <span class="selector-tag">&lt;summary&gt;</span>
<span class="selector-tag">///</span><span class="comment"> Reads a 32bit unsigned integer in big-endian format.</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;/summary&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;param name=&quot;stream&quot;&gt;</span><span class="comment">The stream to read the data from.&lt;/param&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;returns&gt;</span><span class="comment">The unsigned 32bit integer cast to an &lt;c&gt;Int32&lt;/c&gt;.&lt;/returns&gt;</span>
<span class="keyword">private</span> <span class="keyword">int</span> ReadInt<span class="number">32</span><span class="symbol">(</span>Stream stream<span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">return</span> <span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">24</span><span class="symbol">)</span> <span class="symbol">|</span> <span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">16</span><span class="symbol">)</span> <span class="symbol">|</span> <span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">8</span><span class="symbol">)</span> <span class="symbol">|</span> <span class="symbol">(</span><span class="symbol">(</span><span class="keyword">byte</span><span class="symbol">)</span>stream<span class="symbol">.</span>ReadByte<span class="symbol">(</span><span class="symbol">)</span> <span class="symbol">&lt;&lt;</span> <span class="number">0</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<blockquote>
<p>The <code>&lt;&lt; 0</code> bit-shift in the above methods is technically
unnecessary and can be removed. However, I find it makes the
intent of the code clearer.</p>
</blockquote>
<h2 id="reading-strings">Reading strings</h2>
<p>For version 2 files, we need to read a string, which is
comprised of two bytes per character. Fortunately for us, the
.NET Framework includes a <code>BigEndianUnicode</code> (<a href="http://msdn.microsoft.com/en-us/library/vstudio/system.text.encoding.bigendianunicode(v=vs.90).aspx" rel="external nofollow noopener">MSDN</a>) class
that we can use to convert a byte array to a string. As this
class does the endian conversion for us, we don't need to do
anything special when reading the bytes.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="selector-tag">///</span> <span class="selector-tag">&lt;summary&gt;</span>
<span class="selector-tag">///</span><span class="comment"> Reads a unicode string of the specified length.</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;/summary&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;param name=&quot;stream&quot;&gt;</span><span class="comment">The stream to read the data from.&lt;/param&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;param name=&quot;length&quot;&gt;</span><span class="comment">The number of characters in the string.&lt;/param&gt;</span>
<span class="selector-tag">///</span> <span class="selector-tag">&lt;returns&gt;</span><span class="comment">The string read from the stream.&lt;/returns&gt;</span>
<span class="keyword">private</span> <span class="keyword">string</span> ReadString<span class="symbol">(</span>Stream stream<span class="symbol">,</span> <span class="keyword">int</span> length<span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">byte</span><span class="symbol">[</span><span class="symbol">]</span> buffer<span class="symbol">;</span>

 buffer <span class="symbol">=</span> <span class="keyword">new</span> <span class="keyword">byte</span><span class="symbol">[</span>length <span class="symbol">*</span> <span class="number">2</span><span class="symbol">]</span><span class="symbol">;</span>

 stream<span class="symbol">.</span>Read<span class="symbol">(</span>buffer<span class="symbol">,</span> <span class="number">0</span><span class="symbol">,</span> buffer<span class="symbol">.</span>Length<span class="symbol">)</span><span class="symbol">;</span>

 <span class="keyword">return</span> Encoding<span class="symbol">.</span>BigEndianUnicode<span class="symbol">.</span>GetString<span class="symbol">(</span>buffer<span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<h2 id="reading-the-file">Reading the file</h2>
<p>With the preliminaries done with, lets read the file!</p>
<p>We start off by reading the file version so we know how to
process the rest of the file, or at least the first part of it.
If we don't have a version 1 or version 2 file, then we simply
abort.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">using</span> <span class="symbol">(</span>Stream stream <span class="symbol">=</span> File<span class="symbol">.</span>OpenRead<span class="symbol">(</span>fileName<span class="symbol">)</span><span class="symbol">)</span>
<span class="symbol">{</span>
 FileVersion version<span class="symbol">;</span>

 <span class="comment">// read the version, which occupies two bytes</span>
 version <span class="symbol">=</span> <span class="symbol">(</span>FileVersion<span class="symbol">)</span><span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>

 <span class="keyword">if</span> <span class="symbol">(</span>version <span class="symbol">!=</span> FileVersion<span class="symbol">.</span>Version<span class="number">1</span> <span class="symbol">&amp;&amp;</span> version <span class="symbol">!=</span> FileVersion<span class="symbol">.</span>Version<span class="number">2</span><span class="symbol">)</span>
 <span class="keyword">throw</span> <span class="keyword">new</span> InvalidDataException<span class="symbol">(</span><span class="string">&quot;Invalid version information.&quot;</span><span class="symbol">)</span><span class="symbol">;</span>

 colorPalette <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadSwatches<span class="symbol">(</span>stream<span class="symbol">,</span> version<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">if</span> <span class="symbol">(</span>version <span class="symbol">==</span> FileVersion<span class="symbol">.</span>Version<span class="number">1</span><span class="symbol">)</span>
 <span class="symbol">{</span>
 version <span class="symbol">=</span> <span class="symbol">(</span>FileVersion<span class="symbol">)</span><span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">if</span> <span class="symbol">(</span>version <span class="symbol">==</span> FileVersion<span class="symbol">.</span>Version<span class="number">2</span><span class="symbol">)</span>
 colorPalette <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadSwatches<span class="symbol">(</span>stream<span class="symbol">,</span> version<span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>
<span class="symbol">}</span>
</pre>
</figure>
<p>In the above example, if a file has <em>both</em> versions, then I read
them both (assuming the file contains version 1 followed by
version 2). However, there's no point in doing this if you
aren't going to do anything with the swatch name. For example,
this demonstration program converts all the values into the
standard .NET <code>Color</code> structure - which doesn't allow you to
set the <code>Name</code> property. In this scenario, clearly it's a waste
of time reading the version 2 data if you've just read the data
from version 1. However, if you are storing the data in an
object that supports the name, then it's probably a good idea to
discard the previously read data and re-read the version 2 data.</p>
<h2 id="reading-colour-data">Reading colour data</h2>
<p>As the two documented file formats are almost identical, we can
use the same code to handle reading the data, and then perform a
little bit extra for the newer file format. The core of the code
which reads the colour data looks like this.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="comment">// read the number of colors, which also occupies two bytes</span>
colorCount <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>

<span class="keyword">for</span> <span class="symbol">(</span><span class="keyword">int</span> i <span class="symbol">=</span> <span class="number">0</span><span class="symbol">;</span> i <span class="symbol">&lt;</span> colorCount<span class="symbol">;</span> i<span class="symbol">++</span><span class="symbol">)</span>
<span class="symbol">{</span>
 ColorSpace colorSpace<span class="symbol">;</span>
 <span class="keyword">int</span> value<span class="number">1</span><span class="symbol">;</span>
 <span class="keyword">int</span> value<span class="number">2</span><span class="symbol">;</span>
 <span class="keyword">int</span> value<span class="number">3</span><span class="symbol">;</span>
 <span class="keyword">int</span> value<span class="number">4</span><span class="symbol">;</span>

 <span class="comment">// again, two bytes for the color space</span>
 colorSpace <span class="symbol">=</span> <span class="symbol">(</span>ColorSpace<span class="symbol">)</span><span class="symbol">(</span><span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>

 <span class="comment">// then the four values which comprise each color</span>
 value<span class="number">1</span> <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">2</span> <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">3</span> <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>
 value<span class="number">4</span> <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadInt<span class="number">16</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>

 <span class="comment">// and finally, the name of the swatch (version2 only)</span>
 <span class="keyword">if</span> <span class="symbol">(</span>version <span class="symbol">==</span> FileVersion<span class="symbol">.</span>Version<span class="number">2</span><span class="symbol">)</span>
 <span class="symbol">{</span>
 <span class="keyword">int</span> length<span class="symbol">;</span>
 <span class="keyword">string</span> name<span class="symbol">;</span>

 length <span class="symbol">=</span> ReadInt<span class="number">32</span><span class="symbol">(</span>stream<span class="symbol">)</span><span class="symbol">;</span>
 name <span class="symbol">=</span> <span class="keyword">this</span><span class="symbol">.</span>ReadString<span class="symbol">(</span>stream<span class="symbol">,</span> length<span class="symbol">)</span><span class="symbol">;</span>
 <span class="symbol">}</span>
<span class="symbol">}</span>
</pre>
</figure>
<h2 id="translating-the-colour-spaces">Translating the colour spaces</h2>
<p>Once we've read the colour space and the four values of the
colour data, we need to process it.</p>
<p>The first space, RGB, is simple enough. The Adobe format is
using the range 0-65535, so we just need to convert that to the
standard 0-255 range:</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">switch</span> <span class="symbol">(</span>colorSpace<span class="symbol">)</span>
<span class="symbol">{</span>
 <span class="keyword">case</span> ColorSpace<span class="symbol">.</span>Rgb<span class="symbol">:</span>
 <span class="keyword">int</span> red<span class="symbol">;</span>
 <span class="keyword">int</span> green<span class="symbol">;</span>
 <span class="keyword">int</span> blue<span class="symbol">;</span>

 red <span class="symbol">=</span> value<span class="number">1</span> <span class="symbol">/</span> <span class="number">256</span><span class="symbol">;</span> <span class="comment">// 0-255</span>
 green <span class="symbol">=</span> value<span class="number">2</span> <span class="symbol">/</span> <span class="number">256</span><span class="symbol">;</span> <span class="comment">// 0-255</span>
 blue <span class="symbol">=</span> value<span class="number">3</span> <span class="symbol">/</span> <span class="number">256</span><span class="symbol">;</span> <span class="comment">// 0-255</span>

 results<span class="symbol">.</span>Add<span class="symbol">(</span>Color<span class="symbol">.</span>FromArgb<span class="symbol">(</span>red<span class="symbol">,</span> green<span class="symbol">,</span> blue<span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<p>Next is HSL. How you process that depends on the class you are
using, and the range of values it accepts.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">case</span> ColorSpace<span class="symbol">.</span>Hsb<span class="symbol">:</span>
 <span class="keyword">double</span> hue<span class="symbol">;</span>
 <span class="keyword">double</span> saturation<span class="symbol">;</span>
 <span class="keyword">double</span> brightness<span class="symbol">;</span>

 hue <span class="symbol">=</span> value<span class="number">1</span> <span class="symbol">/</span> <span class="number">182.04</span><span class="symbol">;</span> <span class="comment">// 0-359</span>
 saturation <span class="symbol">=</span> value<span class="number">2</span> <span class="symbol">/</span> <span class="number">655.35</span><span class="symbol">;</span> <span class="comment">// 0-1</span>
 brightness <span class="symbol">=</span> value<span class="number">3</span> <span class="symbol">/</span> <span class="number">655.35</span><span class="symbol">;</span> <span class="comment">// 0-1</span>

 results<span class="symbol">.</span>Add<span class="symbol">(</span><span class="keyword">new</span> HslColor<span class="symbol">(</span>hue<span class="symbol">,</span> saturation<span class="symbol">,</span> brightness<span class="symbol">)</span><span class="symbol">.</span>ToRgbColor<span class="symbol">(</span><span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<p>The last colour space we can easily support is gray scale.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
<span class="keyword">case</span> AdobePhotoshopColorSwatchColorSpace<span class="symbol">.</span>Grayscale<span class="symbol">:</span>

 <span class="keyword">int</span> gray<span class="symbol">;</span>

 <span class="comment">// Grayscale.</span>
 <span class="comment">// The first value in the color data is the gray value, from 0...10000.</span>
 gray <span class="symbol">=</span> <span class="symbol">(</span><span class="keyword">int</span><span class="symbol">)</span><span class="symbol">(</span>value<span class="number">1</span> <span class="symbol">/</span> <span class="number">39.0625</span><span class="symbol">)</span><span class="symbol">;</span>

 results<span class="symbol">.</span>Add<span class="symbol">(</span>Color<span class="symbol">.</span>FromArgb<span class="symbol">(</span>gray<span class="symbol">,</span> gray<span class="symbol">,</span> gray<span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
 <span class="keyword">break</span><span class="symbol">;</span>
</pre>
</figure>
<p>Files using the Lab or CMYK spaces will throw an exception as
these are beyond the scope of this example.</p>
<figure class="lang-csharp highlight"><figcaption><span>csharp</span></figcaption><pre class="code">
 <span class="keyword">default</span><span class="symbol">:</span>
 <span class="keyword">throw</span> <span class="keyword">new</span> InvalidDataException<span class="symbol">(</span><span class="keyword">string</span><span class="symbol">.</span>Format<span class="symbol">(</span><span class="string">&quot;Color space &#39;{0}&#39; not supported.&quot;</span><span class="symbol">,</span> colorSpace<span class="symbol">)</span><span class="symbol">)</span><span class="symbol">;</span>
<span class="symbol">}</span>
</pre>
</figure>
<p>Although none of the sample files I tested mixed colour spaces,
they were either all RGB, all Lab or all CMYK, the specification
suggests that it's at least possible. In this case, throwing an
exception might not be the right idea as it could be possible to
load other colours. Therefore it may be a better idea to just
ignore such errors to allow any valid data to be read.</p>
<h2 id="wrapping-up">Wrapping up</h2>
<p>As with <a href="/post/loading-the-color-palette-from-a-bbm-lbm-image-file-using-csharp">reading LBM colour maps</a>, reading the Photoshop
colour swatches was also quite an easy process.</p>
<p>You can download a fully working sample from the link below, and
my next article will reverse the process to allow you to write
your own <code>aco</code> files.</p>
<h2 id="update-history">Update History</h2>
<ul>
<li>2014-01-22 - First published</li>
<li>2020-11-21 - Updated formatting</li>
</ul>

<p><small>
All content <a href="https://devblog.cyotek.com/copyright-and-trademarks">Copyright (c) by Cyotek Ltd</a> or its respective writers. Permission to reproduce news and web log entries and other RSS feed content in unmodified form without notice is granted provided they are not used to endorse or promote any products or opinions (other than what was expressed by the author) and without taking them out of context. Written permission from the copyright owner must be obtained for everything else.<br />Original URL of this content is https://devblog.cyotek.com/post/reading-photoshop-color-swatch-aco-files-using-csharp .
</small></p>Richard Mosshttps://www.cyotek.com/richard.moss@cyotek.com