Unify stage coordinates' units across instamatic #109

Baharis · 2025-02-04T17:32:22Z

The context

Currently, instamatic uses multiple different types to handle stage position variables. Stage length coordinates x, y, z are sometimes expressed as int in nanometers (Jeol microscope), sometimes as float in microns (FEI microscopes); sometimes, the same values are also supplied as neither int nor float but rather their numpy counterparts. This is especially harmful for a server without numpy that is unable to convert numpy.int32 to int. Similarly, even though documentation suggests the angles should always be instances of int (though this is also not very clear), in numerous places the angles are instances of float:

From src/instamatic/microscope/interface/fei_microscope.py, FEIMicroscope lines 148–156 — micron distances, float degrees:

    def getStagePosition(self):
        """Return numbers in microns, angles in degs."""
        return (
            self.stage.Position.X * 1e6,
            self.stage.Position.Y * 1e6,
            self.stage.Position.Z * 1e6,
            self.stage.Position.A / pi * 180,
            self.stage.Position.B / pi * 180,
        )

From src/instamatic/microscope/interface/jeol_microscope.py, JeolMicroscope lines 282–285 — nanometer distances, int degrees:

    def getStagePosition(self) -> Tuple[int, int, int, int, int]:
        """X, y, z in nanometer a and b in degrees."""
        x, y, z, a, b, result = self.stage3.GetPos()
        return x, y, z, a, b

From src/instamatic/controller.py, find_eucentric_height lines 404–414 (excerpt) — nanometer numpy.int_ stage.z:

        zc = self.stage.z
        print(f'Current z = {zc:.1f} nm')
        zs = zc + np.linspace(-dz, dz, steps)
        for i, z in enumerate(zs):
            self.stage.z = z

This PR aims to unify the units used to express the position of microscope stage across instamatic. To this aim, it firstly introduces a small module instamatic.typing with two new Annotated types: int_nm and float_deg. These types are thin wrappers around int and float i.e. type(int_nm(1.0)) == int. The sole purpose of the new annotated wrappers is to display the unit in type hints in addition to the comments. The only difference between int and int_nm is an annotation that appears next to the later in the integrated development environment:

int_nm and float_deg are just type hints; in order to enforce actual change, some interface methods, including these passed to stage.get and stage.set, have been modified to now always accept and return:

x, y, z as annotated type int_nm, actual type int
a, b as annotated type float_deg, actual type float

Major changes

FEIMicroscope and FEISimuMicroscope's get/setStagePosition now communicate distances in nanometers instead of microns, making their behavior consistent with the rest of Instamatic.

Minor changes

Whenever there is a room for any ambiguity, x/y/z & a/b are now hinted to be of int_nm & float_deg type;
- These new types are just thin Annotated wrappers around int and float and affect only type hinting;
- In python 3.7 and 3.8 where Annotated is not available, they are just aliases of (equal to) int and float.
setStagePosition input x/y/z/a/b input is now correctly marked as typing.Optional;
getStagePosition and setStagePosition methods now return an instance of StagePositionTuple.
StagePositionTuple was moved to a new src/instamatic/microscope/typing.py to remove risk of circular imports and allow use as type hints;
When expressed in nanometers, distances are printed using z = {zc} nm instead of z = {zc:.1f} nm as the trailing decimal is irrelevant (always zero).
Minor improvements to microscope implementations' and stage's doc-strings and type-hints.

Bug fixes

Fixed issue introduced in Tecnai bigfixes, Microscope client documentation and EAFP #108 where microscope.components.stage:Stage.set could raise TypeError if supplied only partial optional input due to use of round.
In microscope.client.py:MicroscopeClient._eval_dct, change hint type from dict to Dict to comply with python 3.7.

Effect on the codebase

This change might be breaking for existing script. If there are any scripts designed and used on FEI machines only that use hard-coded distances expressed in microns, they will need to be updated to utilize nanometers instead. However, with this step they should become a step closer to be fully interoperable between machines.

To the best of my understanding the change of units in FEI should have no tangible effect on Joel microscopes whatsoever.

Compatibility note

This PR is accompanied by and should be merged alongside PR #2 of Instamatic Tecnai Server.

…tions and `float_deg` stage tilts

Baharis · 2025-02-04T17:52:15Z

@stefsmeets I plan to go through existing uses of the stage component and try to gauge where it was designed with FEI's microns rather than Jeol's nanometer in mind. Still, do you know if there are any modules, commands, or scripts that were developed strictly for or by FEI groups?

stefsmeets

Lovely work, didn't know you could do this with types. I'm not aware of any specific bits that use the 'FEI' way, mostly the code converts to the same scale in the microscope class.

Have you managed to get this to work in mypy? We should consider adding that as a test if we are adding more and more types to ensure that the types are actually enforced and checked.

I left some comments in the code to clean up some of the types.

Let me know once it is ready and I'll happily merge this.

stefsmeets · 2025-02-05T19:54:08Z

src/instamatic/microscope/components/stage.py

+        x: int_nm = None,
+        y: int_nm = None,


Suggested change

x: int_nm = None,

y: int_nm = None,

x: Optional[int_nm] = None,

y: Optional[int_nm] = None,

stefsmeets · 2025-02-05T19:54:54Z

src/instamatic/microscope/interface/fei_microscope.py

+        x: int_nm = None,
+        y: int_nm = None,
+        z: int_nm = None,
+        a: float_deg = None,
+        b: float_deg = None,
