Documentation Questions

[xi]

There is a lot of explanation why a better contrast formular is needed and how it can be used, but I have not yet found the actual formular. I would have expected it in "APCA in a nutshell". I would also have expected to get a reference implementation in an easy to find file (I guess it exists somewhere in this repo, but I was not able to find it yet).

[Myndex]

Hi Tobias @xi

Thank you for commenting!

but I have not yet found the actual formular

The formula is literally the very first file in the documentation folder in this repo, and is also in the main readme files here and at the apca-w3 repo, and in the white paper. Here's a direct link to it.

The Tomb of the Shared Knowledge

Most of the "key" documentation is cleverly hidden away in the documentation folder.

And I was just playing around with GitHub's addition of LaTeX math and MathJax, and you can see the base algorithm here..

The main README in the documentation folder also has the LaTeX math, as well as a plain-language walk-through.

Raining Cats a Logs

And then there is a master catalog of links, resources, articles, etc., which you will find at git.myndex.com

But also, this project has been going on for over three years, and only recently focused on the task of organizing the mass of documentation and supporting materials. This is a continuing process, and things like a pseudocode version, some LaTeX math versions, JS and Node versions, OpenOffice/LibreOffice versions, and plain language walk-throughs have been made, and I'm collating it all down to a reasonable collection.

I was thinking "APCA in a Nutshell" should be targeted more at end-users (meaning designers) and kept in plain language for broadest access. Nevertheless, I am interested in your opinion?

Please let me know what you expected or where you expected to find things, and I'll make adjustments.

Satellite Repos

To add, this is the MAIN repo, there is also the apca-w3 repo (the specific version for W3/WCAG3) and the bridge-pca repo (a backwards compatible replacement for WCAG 2).

Please let me know if this answers your questions.

Thank you for reading,

Andy

[xi]

But also, this project has been going on for over three years, and only recently focused on the task of organizing the mass of documentation and supporting materials. This is a continuing process, and things like a pseudocode version, some LaTeX math versions, JS and Node versions, OpenOffice/LibreOffice versions, and plain language walk-throughs have been made, and I'm collating it all down to a reasonable collection.

That's good to hear. There is just so much information and some important bits are hard to find among all that. Boiling it down to a small set of well structured documents is really important IMHO.

I was thinking "APCA in a Nutshell" should be targeted more at end-users (meaning designers) and kept in plain language for broadest access. Nevertheless, I am interested in your opinion?

People have different approaches to understanding. I consider myself an end user and I was really searching for the formula. Other people probably need other forms of information. I believe the important bit is to have a good structure so that readers can skip over the sections that are not helpful for them and concentrate on the sections that are.

I also think it would be helpful to have a comparison between this formula and the one from WCAG 2. As far as I understand, the basic luminance calculation is pretty similar. The main differences then are:

• The formula distinguishes between foreground and background color
• The result is a difference, not a ratio
• The result is signed

From the other material I had assumed that font size directly factors into the formula, but apparently that is not the case.

To sum up: I really think there should be some version of the formula in a prominent place. I don't mind whether it is pseudocode, LaTeX, or a plain language description.

[Myndex]

Hi @xi

That's good to hear. There is just so much information and some important bits are hard to find among all that. Boiling it down to a small set of well structured documents is really important IMHO.

It's a monumental project and since this is a nonprofit, pro bono project, I don't have a budget for a research assistant… So it's taking me a little while to weed through it all. Particular since I have a high priority to get some papers published sooner rather than later..

Nevertheless, the math has always been in the README file in documentation at the very least.

So then to ask, what is a better or more standardized place to put things? I assumed the README in the documentation folder would be ideal...

People have different approaches to understanding. I consider myself an end user and I was really searching for the formula.

See, I've been sharply criticized for writing "too technical". I did have the formula, pseudocode, and a walkthrough for like, 3 years, on the /root README here at the repo and a few other places, but due to criticism I moved the "big" README file to the documentation folder, because so many say it's "too much".

Everything IS in the documentation folder.

THE VERY VERY BIG README FILE OF APCA Watch out for accountants in that building sailing by next door...

I also think it would be helpful to have a comparison between this formula and the one from WCAG 2.

I do have many, some in terms of visual examples, or charts. But also some in terms of the math. There are multiple discussion threads here and at the Low Vision Task Force repo were we are specifically comparing apples to apples.

Going back to 2019, here is the first white paper on the early SAPC.

Next, this draft white paper discusses some of the theory.

And here is a comparison to the maths of WCAG 2 and APCA.

Much more recently, there is this thread in discussions that is a direct comparison of WCAG 2 and APCA, including charts and graphs.

Another comparative example, focused on color vision, is "What’s Red & Black & Also Not Read?".

And then there is this third party peer review by Sam Waller, a PhD at Cambridge UK, comparing the two, which includes a simple live experiment.

And there is this interesting third party peer review by Roger Attill, and he coded his own software test apps to compare them.

As far as I understand, the basic luminance calculation is pretty similar

The only similarity is the use of sRGB coefficients that reference the CIE 1931 2° standard observer.

APCA is NOT using a basic luminance calculation. The linearization is modified, which I cover in this page, and also Chris Lilly and I have discussed this at length in a couple threads in Silver.

The main differences then are:

• The formula distinguishes between foreground and background color
• The result is a difference, not a ratio
• The result is signed

Those are all side benefits, and were engineered into the method intentionally. But those are not the primary beneficial feature(s).

What's APCA Got?

APCA is specifically tuned for readability. APCA predicts contrast perception for high-spatial-frequency stimuli (text) at a supra-threshold level on a self-illuminated monitor, and in a perceptually uniform way across the available visible range, including certain optional compensation factors. APCA is adjustable for different use cases if needed, and APCA is extensible to add features and enhancements.

APCA-W3 is adjusted and tuned for readability of web content in typical environments with standard resolution displays (i.e. worst common-case scenario) and works in conjunction with a set of guidelines being developed for WCAG 3. Those guidelines are either "level based" like WCAG 2, or using a lookup table for font/line weight etc.

If you look at the comparative articles above, it should be clear this is a very different approach.

From the other material I had assumed that font size directly factors into the formula, but apparently that is not the case.

No, your assumption is correct, that IS the case, in a key way. It's just not directly obvious. And this is the subject of the main paper I am writing right now, and is beyond what I can get into right now... The last time I gave a live presentation on it, it took hours, and I was rushing. The full SACAM math is much more complicated. APCA is an irreducibly simplified contrast appearance model.

While it is true that the most basic version of APCA as the one in public beta right now works with essentially achromatic luminance, there are (unreleased) modules for hue. But also, the linearization used right now makes a useful shift in red bringing it closer to reality (it is not a complete HK effect compensation, but this is part of the protan compensation that is being worked on).

To sum up: I really think there should be some version of the formula in a prominent place. I don't mind whether it is pseudocode, LaTeX, or a plain language description.

Well, as I mentioned above, it always has been, and I'm sorry you weren't able to find it.

The LaTeX is on the README in documentation, and I also put a copy in it's own file in the documentation folder two days before you posted this issue. The code is well commented and is in the src folder, in JS for the javascript and in PORTED for an OpenOffice version. There are also svgs of the LaTeX math in the images folder, and at the satellite repository, apca-w3, which also has an npm package, and the math is in the documentation folder and image folder. The code at apca-w3 might be a little easier to follow too.

Nevertheless, I realize there may be too many OTHER things in the way, so to be proactive I've added more prominent links for some of these things in view of your concern. Sorry you experienced problems, Rather than close this issue, I'll move it to DISCUSSIONS as I think it is of general interest, and please feel free to ask further questions!

Thank you for reading,

Andy