npm package published!

[Myndex]

Hello -- @tkeenoy @joshuakraemer @OrKoN @UXPublishing @abdulmhamid @NateBaldwinDesign @markov00

Just wanted to let you know that we finally have an npm package to make APCA updates easier.

https://www.npmjs.com/package/apca-w3

And the new API is trivially easy — you can send the colors as hex strings (#abc123), as rgb(0,0,0), as named colors (magenta, aquamarine), or as a 24 bit number (i.e. hex 0xf279a or decimal int 16123456)

Usage:
Lc = APCAcontrast(sRGBtoY(textColor),sRGBtoY(backgroundColor));
It returns a signed int, rounded to the nearest whole number.

Also, the font lookup table has been modified.

Thank you!

Andy

[OrKoN]

Thanks! Great news! We are going to check it out.

[NateBaldwinDesign]

Fantastic, thank you!

[abdulmhamid]

That's great! We'll pull these updates in soon.

[NateBaldwinDesign]

@Myndex it may be easier to use if the JS you distribute on npm is exported as a javascript module. Eg, at the end of the file, adding

module.exports = {
   APCAcontrast,
   sRGBtoY,
   // any other necessary functions to export
}

Prior to the npm module release, I manually added this module exports statement to the end of the APCA file in order to access the functions in my own scripts.

Then, for the npm readme guidelines, I would expect to see an example of the import as well:

import { APCAcontrast, sRGBtoY } from 'apca-w3';

const Lc = APCAcontrast(sRGBtoY(textColor), sRGBtoY(backgroundColor));

It's also unclear if the sRGBtoY function is needed explicitly, as well as what formats are supported for the color input. For example, I would expect common string formats, especially conforming to the CSS Module Level 4 + specs for colors. But at the bare minimum, these options:

• Hex: "#f26322"
• RGB: "rgb(242, 99, 34)"
• HSL: "hsl(19deg, 89%, 54%)"

Additional CSS Module level 4 color formats that would be desirable:

• Lab: "lab(61%, 54, 62)"
• LCh: "lch(61 ,82, 49deg)"

The specifics behind the request to support those string formats is that they are more likely to be used in web applications. However, object or coordinate arrays would be ok as well, however more formatting structure would be needed (eg, [242, 99, 34, 'rgb] or { r: 242, g: 99, b: 34}.

Example of basic usage that I would expect
I would hope that the module is simple enough to pass this to return a result, without manual sRGBtoY conversion:

import { APCAcontrast } from 'apca-w3';

const contrast = APCAcontrast('#ffffff', '#888888');
// returns ~66.89

Please let me know if I'm missing something obvious that would have answered these questions/concerns elsewhere :-)

[Myndex]

Hi Nate @NateBaldwinDesign

Please let me know if I'm missing something obvious that would have answered these questions/concerns elsewhere :-)

Only that...

LOL. Yea a big oops for me I had meant to set up the exports (I left some export declarations commented out apparently), but I think my approach was less than accurate regarding setting it up as a module.

it may be easier to use if the JS you distribute on npm is exported as a javascript module. Eg, at the end of the file, adding
module.exports = {

Very helpful, thank you.

It's also unclear if the sRGBtoY function is needed explicitly, as well as what formats are supported for the color input.

It is at the moment as the luminance (Y) used in APCA is based on actual monitor output, and so sRGBtoY() uses a slightly different method than the piecewise. The idea is that the sRGBtoY() is a function that is replaced and optimized for different color spaces.

I would expect common string formats... at the bare minimum, these options:

• Hex: "#f26322"
• RGB: "rgb(242, 99, 34)"
• HSL: "hsl(19deg, 89%, 54%)"

HSL is not implemented at the moment. The following are the available input types for sRGBtoY, and sorry if the documentation was not clear. All are automatically recognized:

STRINGS:

• No Alpha

  • '#abc' or 'abc' (interpreted as 'aabbcc')
  • '#abcdef' or 'abcdef' (hash is ignored)
  • 'rgb(123, 45, 67)'
  • 'aquamarine' or 'magenta' (full CSS4 named colors list)

• With Alpha (alpha is NOT presently calculated, and assumed as fully opaque)

  • '#abcf' or 'abcf' (interpreted as 'aabbccff')
  • '#123456ff' or '123456ff' (hash is ignored)
  • 'rgba(123, 45, 67,255)'

NUMBER:

• As hex
  • 0xabcdef
• As integer
  • 11259375

No alpha parsing for numbers in part as there are big and little endian issues that need to be resolved.

I will add HSL per the code samples in CSS soon.

Additional CSS Module level 4 color formats that would be desirable:

• Lab: "lab(61%, 54, 62)"
• LCh: "lch(61 ,82, 49deg)"

Ugh. CSS 4's use of LAB and LChab has it referenced to D50 and not D65, and it is its own colorspace, not sRGB.

HSL on the other hand is just a polar version of sRGB, so that can reasonably go into sRGBtoY() — The CSS instantiation of LAB and LCh need their own helper function IMO.

For the other spaces in CSS, they will be handled along the lines of ' displayP3ToY() ' and ' rec2020ToY() '.

The reason for abstracting them out of the main contrast calculation is to provide the opportunity to model different display types, including HDR, separately from the actual contrast calculation. This is also related to a substantial block of unreleased "goodies".

The basic APCA, and sRGBtoY is simplified, but weighted toward actual monitor outputs. The matrixes and other simple transforms are all approximations, with Bradford being somewhat best. But all still approximations. Multi dimensional LUTs may be more accurate but probably more accurate than needed for the simpler contrast models. All of this is part of a series of trade offs or compromises — the basic APCA is still a mere pair of colors. This is to keep it simple as possible (already, there are objections to "it's complicated").

The larger SAPC and APCA models are more complete appearance models, with more inputs, more fun... and also, not done... !

The specifics behind the request to support those string formats is that they are more likely to be used in web applications. However, object or coordinate arrays would be ok as well, however more formatting structure would be needed (eg, [242, 99, 34, 'rgb] or { r: 242, g: 99, b: 34}.

Much easier to add objects or arrays, which are already there in some previous versions and in the larger SAPC stuff...

So on my list and checking it twice:

• Fix the module so it can be imported easily,
• add HSL and
• add object and arrays for inputs to sRGBtoY()

---

Example of basic usage that I would expect I would hope that the module is simple enough to pass this to return a result, without manual sRGBtoY conversion:

import { APCAcontrast } from 'apca-w3';

const contrast = APCAcontrast('#ffffff', '#888888');
// returns ~66.89

So the only problem here is that the colorspace is not clearly defined. And as multiple spaces are being added to the spec, it needs to be clear...

Thank you again Nate for your help and discussion here.

Andy

[OrKoN]

@Myndex @NateBaldwinDesign my 2c for the discussion: I think we definitely need module exports to be able to use the package but I would say I'd prefer to remove any color parsing from the package. E.g., in Chrome DevTools we already have code dealing with color parsing and there is no need to duplicate the code inside the APCA package. I assume there are many 3rd party libs for color parsing too. Therefore, I'd suggest to consider removing color parsing in the NPM package and accepting only the raw color data (e.g., ints or rgb array). Converting different color spaces to Y would also ideally accept raw data so that the package does not need to contain parsing logic.

[abdulmhamid]

You could split the parsing into separate, exported functions, allow people to import them as they need, and use them to return the array used in sRGBtoY— I don't think a separate npm package is necessary. Splitting the parsers (i.e separate functions for hex, rgb, hsl, etc.) would be beneficial for several reasons and having an extra method that checks the value then calls the appropriate one of the others would be useful for generic cases. These should also enable some tree shaking.

Another possibility — largely to prevent a chain of prerequisite methods that ends up like APCAcontrast(sRGBtoY(parseColor(textColorVar)), sRGBtoY(parseColor(bgColorVar))) — would be to call sRGBtoY from within APCAcontrast and expect color arrays instead of Y there. This may be simpler for those who opt not to use a parsing function but there are trade-offs in either scenario.

Unrelated to the module integration discussion, I'm curious about the sRGBtoY method. It looks very similar to the relative luminance calculation in 1.4.3 without correction factors for low numbers. Is the correction not needed here? This is the luminance check we are using for legacy contrast ratios:

export function luminance(rgb: number[]): number {
    const multipliers = [0.2126, 0.7152, 0.0722];
    return rgb.reduce((acc, item, index) => {
        let num = item / 255;
        num = num <= 0.03928 ? num / 12.92 : Math.pow((num + 0.055) / 1.055, 2.4);

        acc += num * multipliers[index];
        return acc;
    }, 0);
}

Also, do you foresee the alpha channel being necessary in this method in the future? Nevermind, I see the comments in the main file.

Do you know what versioning of the npm package will look like moving forward? I'm unsure what the path is given the current version number.

As a future note/wishlist item, I may open an issue or PR for TypeScript definitions for each of the methods.

Thanks again — I'm happy to clarify any of my comments here and contribute where I can.

Abdul

[Myndex]

Hi Abdul @abdulmhamid

Unrelated to the module integration discussion, I'm curious about the sRGBtoY method. It looks very similar to the relative luminance calculation in 1.4.3 without correction factors for low numbers. Is the correction not needed here? This is the luminance check we are using for legacy contrast ratios:

The method used in WCAG_2 is incorrect in part, and not relevant to what we are doing in APCA in part.

That reduction to luminance is part of a spec that was developed in the mid 1990s having less to do with actual luminance and more to do with computational convenience, namely, not having an infinite slope at 0.

In the case of APCA, I am concerned only with modeling real world monitor performance. The adjustments in the black area are handled by the soft clamps in the APCA input stage, which are later down the line.

There HAS been some discussion about using only the "standard" math like the (correct) one in the IEC document, even though this does not model actual monitor output, and then making up the difference later. But by making the adjustment earlier we also help to correct for the incorrect offsets of the primary coefficients... which itself is a tangled mess having to do with approximations throughout the history of colorimetry including but not limited to the fact that blue is know to be wrong in the 2° observer, and the 2° observer is what we use for most of this...

I consider the matter far from settled, though we are approaching the point where some lines are being drawn in the sand. The fact that HDR is on the horizon makes it all that much more "interesting".

TL;DR

Don't assume for any moment that there is some "absolute" in the area of visual perception: there are sets of empirical data of small samples of observers that are then averaged and aggregated into approximations that "generally work pretty well".

In the case of contrast on self illuminated displays, there are a set of attributes that make the perception of said colors and luminance unique compared to surface colors, to the point that L* (Lstar being derived to fit surface colors) does not function as expected. Once we know that and model it, it's all downhill from there...

TTL;DRAA

Or put another way, comparing APCA to WCAG_2 contrast is not like comparing apples and oranges, it's more like comparing apples and a can of Crush.

[Myndex]

And to add @abdulmhamid

Also, do you foresee the alpha channel being necessary in this method in the future? Nevermind, I see the comments in the main file.

There have been requests to handle some alpha related operations before returning a contrast, so that is planned.

Do you know what versioning of the npm package will look like moving forward? I'm unsure what the path is given the current version number.

Things are going to be "normally semantically versioned" once we get through the growing pains (namely of me trying to figure out how things are best set up for you and other developers...!)

SO — yea, I am trying to be responsive to comments and concerns in this area. My intention is the 0.1.0 pre-release will be as soon as I "hope" we are past the potential avalanche of breaking changes as we suss things out.

As a future note/wishlist item, I may open an issue or PR for TypeScript definitions for each of the methods.

I am open to all of that. Once the "basic" interface is stable, and accommodates the future expansion of the main SAPC branches, then I'll be able to spend more time in this regard. If you think it is of value sooner than later, then I'm open to adding some collaboration at least in the W3 licensed version in the apca-w3 repo.

Thanks again — I'm happy to clarify any of my comments here and contribute where I can.
Abdul

Thank you Abdul all of these comments are helpful!

Andy

[abdulmhamid]

Thanks for the context. The similarities caught my attention and it's interesting to see the rationale.

[OrKoN]

@Myndex I think using rgb/rgba arrays as inputs makes the most sense! If someone needs to parse CSS color formats, there are several modules out there that provide parsing utilities (one example: https://github.com/colorjs/color-rgba). So I feel there is no need to re-implement/maintain color parsing just for APCA.

[NateBaldwinDesign]

For the other spaces in CSS, they will be handled along the lines of ' displayP3ToY() ' and ' rec2020ToY() '.

@Myndex this got me thinking. Does APCA return different contrast values between sRGB and Display P3? If so, this could be a complex issue. Colors for user interface design are typically used across devices (iOS/Android/Web) so one platform may render the RGB in Display P3, whereas another would render it in sRGB. And while there are ways to transform between those spaces for platforms that support one or the other, desktop can be a different beast. For example, you may design an application that on MacOS is shown in Display P3 on the native display (eg, the display of a macbook pro). A user, however, may have peripheral displays (like I do) that only support sRGB. So the application may meet contrast requirements when displayed in Display P3, but not in sRGB (or vice versa) if that's what I'm reading into here. What are your thoughts?

[Myndex]

...Does APCA return different contrast values between sRGB and Display P3? ...

Hi Nate @NateBaldwinDesign

Okay, so #abcdef in srgb is a uniquely different color than #abcdef is P3, or #abcdef in rec2020. THEREFORE, yes, #abcdef against #123456 will result in different Lc values. depending on the colorspace.

From a practical point, the difference could be seen as minor, as far as the basic APCA is concerned.

However, there are unreleased modules that directly deal with color weighting for various form of CVD and those are significant.

One key example: in sRGB, the red primary is actually red orange. But in a rec2020, the red is on the spectral locus and it is far enough away from the M cone response that somebody with protanopia won't see it, where as protan does see the sRGB "red" as it is well into the M cone response.

For normal vision, the part is most important are the coefficients used for each of the primaries in terms of each primary proportion of the estimated luminance output of a given display's color space. The transformation matrix is, and therefore the coefficients for each of these different color spaces is uniquely different. sRGB and rec709 are the same, but P3 and rec 2020 are definitely different.

And we haven't even begun to talk about HDR.

So yes it's complicated. And it's part of the planning of the work that I'm doing here with APCA, to take these things into account and to minimize the differences in terms of predicting contrast for readability.

I hope that answers? This is a worthy topic for further discussion though.

[Myndex]

An npm version apca-w3-0.0.98-g-4g.2. that should address the export issue is just published, and next I will address the array-as-input

A question: so in the npm package, is the preferred embodiment to leave the parsing function, bu just have it so that if can be imported or not imported? So:

module.exports = {
   APCAcontrast,
   sRGBtoY,
   displayP3toY,
   colorParsley
}

And then you just not import colorParsley() if it's not needed?

I would prefer to keep this as all one package with no dependencies...

[alexkrolick]

Here's a stab at supporting all the various JS module formats, using some build tooling: Myndex/apca-w3#1

Also added a demo page, to test out the NPM package, as well as start exploring a "calculator"/"checker" interface that's more plug-and-play than the table format. That's a separate discussion though.

Would appreciate if anyone with strong opinions on how to publish NPM packages in 2021 could weigh in on the dist output (it's currently cjs, esm, and umd via swc).