TODO: Clarify coordinate systems

[tlambert03]

i'm generally observing that coordinate systems are indeed a sticky point, that I'm still a little bit confused about exactly when and where these coordinate systems need to be declared, what they depend on (is it the stage? is it the plotting system? is it some transformation system? all of the above? etc...). And if I'm a bit confused, then I'm certain that the average user would probably be a bit confused...

And so I'd like to see it all given a more formal treatment, some documentation somewhere that

1. explicitly lays out all of the objects in the codebase that are in some way "coordinate-system aware"
2. clarifies who/what defines that coordinate system
3. discusses how it should be customized in certain cases (for example, if my stage treats +X as to the left vs to the right... what should I do)?

don't you think it is better to just set a coordinate system that useq is using and is up to the user to convert the unit depending on their stage coordinate system?

once I understand the above a bit better, i think the answer to this question will probably be more obvious.

Originally posted by @tlambert03 in #172 (comment)

[fdrgsp]

I spent a bit more time on the useq plate code. As a starting point I think it is easier to define the coordinate system we want and always use the same. Then maybe we can find a way to let the users set the system they want to use.

We are already using a cartesian coordinate system where -x is left, +x is right, -y is down and +y is up in the _PointsPlan. For example, when we create grid points or random points we always assume that the center is (0, 0) and we move along the x and y axis as mention before: -x is left, +x is right, -y is down and +y is up.

So I think it can be a good idea to keep the same coordinate system also for the WellPlatePlan for now. This simply means that we need to apply a correct transformation to the set of point that represent the center of the wells of a plate. For example, if we assume that well A1 is centered at (0, 0) and well spacing is 10, then well A2 should
be centered at (10, 0), well B1 should be centered at (0, -10), and so on. It also means that we do not need to invert any axis when we generate the positions per well since the _PointsPlan use the same coordinate system.
The center well positions looks like this (for a 96 well plate):

This approach also makes it easy to plot and visualize the position.

If we decide to keep the coordinate system constant, then it does not matter what is the coordinate system of the microscope stage because it will be up to the user to invert the coordinate if necessary (I did few test in the past with Nikon stages and Prior stages and they use different coordinate systems, so it is hard to generalize).

In this PR #175 I updated the code so that we use the cartesian coordinate system where -x is left, +x is right, -y is down and +y is up. We only need to apply the transformation once and we do not even need to invert any coordinates when we use the plot function.

[tlambert03]

sounds good, thanks for clarifying! we should put something like this somewhere in the docs. can be very brief. don't need to do it now

[marktsuchida]

For reference, MMStudio's stated convention has the Y axis flipped: https://micro-manager.org/Coordinates_and_Directionality, first paragraph (note that some of what is written there might be aspirational). There are probably arguments for either way, but it might be worth noting this when writing the docs.

[fdrgsp]

Thanks @marktsuchida!