diff --git a/README.md b/README.md index 17ed769..e9015dd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,9 @@ # LAT Alignment -Tools for LAT mirror alignment +Tools for Large Aperture Telescope (LAT) mirror alignment. +While these tools are currently specific to the Simons Observatory LAT, +much of the library could be generalized to any telescope alignment. + +For details on usage please check the guide (WIP! Doesn't exist yet!). ## Installation Technically after cloning this repository you can just run `python lat_alignment/alignment.py PATH/TO/CONFIG`, @@ -13,191 +17,6 @@ This has two main benefits over running the script directly: This is nice because now you can call the code from the measurement directory where you are most likely editing files, saving you the hassle of having to `cd` or wrangle long file paths. -## Usage -1. Create the appropriate directory structure for your measurement (see [File Structure](#file-structure) for details). -2. Place the measurement files in the appropriate place in your created directory (see [Measurement Files](#measurement-files) for details). -3. Create a file with any information about the measurement that could prove useful (see [Description File](#description-file) for details). -4. Create a config file for your measurement (see [Config File](#config-file) for details). -5. Run the alignment script with `lat_alignment /PATH/TO/CONFIG` -6. Follow the instructions in the output to align panels. This output will both be printed in the terminal and written to an output file (see [Output File](#output-file)) - -### File Structure -Measurements should be organized in the following file structure -``` -measurements -| -└───YYYYMMDD_num -| |config.txt -| |description.txt -| |output.txt -| |adjusters.yaml -| | -| └───M1 -| | |XX-XXXXXX.txt -| | |XX-XXXXXX.txt -| | |... -| | -| └───M2 -| | |XX-XXXXXX.txt -| | |XX-XXXXXX.txt -| | |... -| | -| └───plots -| └───M1 -| | |XX-XXXXXX_surface.png -| | |XX-XXXXXX_hist.png -| | |XX-XXXXXX_ps.png -| | |... -| | -| └───M2 -| |XX-XXXXXX_surface.png -| |XX-XXXXXX_hist.png -| |XX-XXXXXX_ps.png -| |... -| -└───YYYYMMDD_num -| |config.txt -| |description.txt -| |adjusters.yaml -| | -| └───M1 -| | |XX-XXXXXX.txt -| | |XX-XXXXXX.txt -| | |... -| | -| └───M2 -| |XX-XXXXXX.txt -| |XX-XXXXXX.txt -| |... -| | -| └───plots -| └───M1 -| | |XX-XXXXXX_surface.png -| | |XX-XXXXXX_hist.png -| | |XX-XXXXXX_ps.png -| | |... -| | -| └───M2 -| |XX-XXXXXX_surface.png -| |XX-XXXXXX_hist.png -| |XX-XXXXXX_ps.png -| |... -|... -``` - -#### Measurement Directories -Each directory `YYYYMMDD_num` refers to a specific measurement session. Where `YYYYMMDD` refers to the date of the measurement and `num` refers to which number measurement on that date it was. For example the second measurement taken on January 1st, 2022 would be `20220101_02`. - -This is the file path that should be provided to `alignment.py` as the `measurement_dir` argument. - -#### Config File -The file `config.yaml` contains configuration options. Below is an annotated example with all possible options. - -```yaml -# The measurement directory -# If not provided the dirctory containing the config will be used -measurement_dir: PATH/TO/MEASUREMENT - -# The path the the dirctory containing the cannonical adjuster locations -# If not provided the can_points directory in the root of this repository is used -cannonical_points: PATH/TO/CAN/POINTS - -# Coordinate system of measurements -# Possible vaules are ["cad", "global", "primary", "secondary"] -coordinates: cad # default value - -# Amount to shift the origin of the measurements by -# Should be a 3 element list -origin_shift: [0, 0, 0] # default value - -# FARO compensation -compensation: 0.0 # default value - -# Set to True to apply common mode subtraction -cm_sub: False # default value - -# Set to True to make plots if panels -plots: False # default value - -# Where to save log -# If not provided log is saved to a file called output.txt -# in the measurement_dir for this measurement -log_file: null # Set to null to only print output and not save - -# Path to a yaml file with the current adjuster positions -# If null (None) then all adjusters are assumed to be at 0 -# You probably want to point this to the file generated -# in the previous alignment run if you have it -adj_path: null # default value - -# Path to where to store the adjuster postions after aligning -# If null (None) will store in a file called adjusters.yaml -# in the measurement_dir for this measurement -adj_out: null # default value - -# Defines the allowed adjuster range in mm -adj_low: -1 # default value -adj_high: 1 # default value -``` - -If you are using all default values make a blank config with `touch config.yaml` - -#### Description File -Each measurement directory should contain a file `description.txt` with information on the measurement. Any information that could provide useful context when looking at the measurement/alignment after the fact should be included here (ie: who performed the measurement, where the measurement was taken, etc.). - -#### Output File -Output generated by `alignment.py`. -By default this is saved at `measurement_dir/output.txt` - -Note that this file gets overwritten when `lat_alignment` is run, so if you want to store multiple copies with different configs or something rename them or change the `log_file` in the config. - -#### Adjuster Positions -Positions of adjusters after applying the calculated adjustments. -This is a yaml file nominally saved at `measurement_dir/adjusters/yaml` - -Each element in the file is in the format: -``` -PANEL_NUMBER: [X, Y, ADJ_1, ADJ_2, ADJ_3, ADJ_4, ADJ_5] -``` - -#### Mirror Directories -Directories containing the measurements files within each root measurement directory. `M1` contains the measurements for the primary mirror and `M2` contains the measurements for the secondary mirror. If you don't have measurements for one of the mirrors you do not need to create an empty directory for it. - -#### Measurement Files -Files containing the point cloud measurements for a given panel. Should live in the mirror directory that the panel belongs to. Files should be named `XX-XXXXXX.txt` where `XX-XXXXXX` is the panel number. The numbering system is as follows: -* First four digits (`XX-XX`) are the telescope number. For the LAT this is `01-01` -* Fifth digit is the mirror number. This is `1` for the primary and `2` for the secondary. -* Sixth digit is the panel row -* Seventh digit is the panel column -* Eight digit is the panel number (current, spare, replacement, etc.) - -#### Plot Directory -If the `plots` option is set to `True` then the root measurement will contain a directory called `plots`. Within this directory will be directories for each mirror measured, `M1` for the primary and `M2` for the secondary. Each of these will contain three plots per panel measured: -* `XX-XXXXXX_surface.png`, a plot of the panel's surface in the mirror's coordinate system. -* `XX-XXXXXX_hist.png`, a histogram of the residuals from the panel's fit. -* `XX-XXXXXX_ps.png`, a plot of the power spectrum of the residuals from the panel's fit. - -Where `XX-XXXXXX` is the panel number. - -## Coordinate Systems -The relevant coordinate systems are marked in the diagram below: - -![LAT coordinate systems](./imgs/coords.png) - -Where the orange circle marks the `global` coordinate system, the green circle marks the `primary` coordinate system, and the blue circle marks the `secondary` coordinate system. - -Additionally there is a `cad` coordinate system that is defined as the coordinate system from the SolidWorks model. It is given by the following transformation from the `global` coordinate system: -``` -x -> y - 200 mm -y -> x -z -> -z -``` -It is currently unclear why the 200 mm offset exists. - -Note that the files in the `can_points` directory are in the `cad` coordinate system. - -All measurements should be done in one of these four coordinate systems modulo a known shift in the origin. - ## Bugs and Feature Requests For low priority bugs and feature requests submit an issue on the [git repo](https://github.com/simonsobs/LAT_Alignment). diff --git a/docs/config_file.md b/docs/config_file.md new file mode 100644 index 0000000..477fe71 --- /dev/null +++ b/docs/config_file.md @@ -0,0 +1,108 @@ +# Configuration File + +## Fields + +??? info "`mode`" + + The alignment mode to use. + + Possible values are: + + * `panel`: For aligning panels within one mirror. + * `optical`: For aligning optical elements relative to each other (as solid bodies). + +??? info "`mirror`" + + The mirror that we want to align panels to. + Only used if `mode` is `panel`. + + Possible values are: + + * `primary`: To align the primary mirror. + * `secondary": The align the secondary mirror. + +??? info "`align_to`" + + Which optical element to keep fixed and align the others to. + Only used if `mode` is `optical`. + + Possible values are: + + * `primary`: To align to the primary mirror. + * `secondary": The align to the secondary mirror. + * `receiver": The align to the receiver. + * `bearing": The align to the bearing. + +??? info "`measurement`" + + The path to the photogrammetry data we are using to do the alignment. + If this is a relative path it is taken relative to the directory that the + configuration file is in. + +??? info "`data_dir`" + + The path to the data files that define the panel corners and the adjuster positions. + If this is a relative path it is taken relative to the directory that the + configuration file is in. + + You genrally don't need to provide this since the package will use its own bundled + data files by default. + +??? info "`load`" + + Additional keyword arguments to pass to + [`io.load_photo`](https://simonsobs.github.io/LAT_Alignment/latest/reference/io/#lat_alignment.io.load_photo). + + +??? info "`compensate`" + + Amount to compensate mirror measurements by in mm. + This is for backwards compatiblilty with laser tracker data and is $0$ by default. + + +??? info "`common_mode`" + + Additional keyword arguments to pass to + [`mirror.remove_cm`](https://simonsobs.github.io/LAT_Alignment/latest/reference/mirror/#lat_alignment.mirror.remove_cm) + +??? info "`adjuster_radius`" + + How close to an adjuster a data point needs to be in order for us to use its residual as + a secondary correction when computing adjustments. + Only used if `mode` is `panel`. + + This is $100$ mm by default. + +??? info "`vmax`" + + The maximum value to use in the colorbar when plotting mirror surface. + The colorbar is symmetric so `vmin = -1*vmax`. + +??? info "`adjust`" + + Additional keyword arguments to pass to + [`adjustments.calc_adjustments`](https://simonsobs.github.io/LAT_Alignment/latest/reference/adjustments/#lat_alignment.adjustments.calc_adjustments) + +??? info "`title`" + + The title of the measurement. + This is used both in plots and in output filenames. + + +## Example Configuration Files +These are typical configuration files, +you usually will not need to touch fields other than the ones shown here. + +### Panel Alignment + +```yaml +mode: "panel" +mirror: "secondary" +measurement: "data_20240911_1430.csv" +title: "M2 20240911 1430" +vmax: 50 +``` + +### Optical Element Alignment + +WIP! Check back later! diff --git a/docs/coordinate_systems.md b/docs/coordinate_systems.md new file mode 100644 index 0000000..fb8c2d6 --- /dev/null +++ b/docs/coordinate_systems.md @@ -0,0 +1,77 @@ +# Coordinate Systems + +There are many coordinate systems that have been used to describe the +LAT mirror, most of them were used a single time and them replaced. +Here we describe the six coordinate systems that are actively used. +These six coordinate systems can be organized into two groups: +the "Optical" coordinate systems and the "Vertex" coordinate systems. +Each of these groups contains three coordinate systems: "Global", "Primary", and "Secondary"; +where "Global" is a global reference frame for the whole telescope, +"Primary" is an internal reference frame for the primary mirror, +and "Secondary" is an internal reference frame for the secondary mirror. + +In general this software package does all of its computations in the +"Optical" systems, but it is useful to understand the "Vertex" systems +so that one can utilize measurements provided by Vertex. + +Note that this page is mostly to give the user an understanding of how +these coordinate systems are defined. You should never have to transform +between them by hand. For that please use the +[`transforms.coord_transform`](https://simonsobs.github.io/LAT_Alignment/latest/reference/transforms/#lat_alignment.transforms.coord_transform) function. + + +### Optical Coordinate Systems + +The optical coordinate systems are designed to be logical given the optics of the telescope. + +For "Primary" and "Secondary" the axis are defined such that: + +* The $x$ axis changes as the panel column number changes. +* The $y$ axis changes as the panel row number changes. +* The $z$ axis is normal to the mirror surfaces. + +And the origin is at the center of the mirror surface. +The mirror model in [`mirror.mirror_surface`](https://simonsobs.github.io/LAT_Alignment/latest/reference/mirror/#lat_alignment.mirror.mirror_surface) +is computed in these coordinates. + +The directions of the axis relative to the mirror surface is not the same for the two mirrors, +check the diagram below to see where they point. + +The "Global" coordinate system is defined such that: + +* The $x$ axis is tangent to the telescope's azimuth rotation. +* The $y$ axis points towards the receiver. +* The $z$ axis points in the direction that light enters the telescope. + +And the origin is set so that the origin of the "Primary" system +lies along the "Global" $z$ axis and the origin of the "Secondary" +system lies along the "Global" $y$ axis. + +![Diagram describing the Optical coordinate systems](./imgs/coords.png) + + +### Vertex Coordinate Systems + +The vertex coordinate systems were developed by Vertex and are used for all of there +alignment purposes. If you get data from Vertex it is likely in this format. + +For "Primary" and "Secondary" the axis are defined such that: + +* The $x$ axis changes as the panel row number changes. +* The $y$ axis changes as the panel column number changes. +* The $z$ axis is normal to the mirror surfaces. + +The origins are the same as in the "Optical" coordinate systems. +See the diagram below for the orientation of these axes. + +The "Global" coordinate system is defined such that: + +* The $x$ axis points towards the receiver. +* The $y$ axis is tangent to the telescope's azimuth rotation. +* The $z$ axis points out of the telescope. + +The origin is offset by 120 mm along the "Vertex" $x$ +(so the "Optical" $y$ axis). The reason for the offset +is unclear. + +![Diagram describing the Vertex coordinate systems](./imgs/coords_va.png) diff --git a/imgs/coords.png b/docs/imgs/coords.png similarity index 100% rename from imgs/coords.png rename to docs/imgs/coords.png diff --git a/docs/imgs/coords_va.png b/docs/imgs/coords_va.png new file mode 100644 index 0000000..f8d4a56 Binary files /dev/null and b/docs/imgs/coords_va.png differ diff --git a/lat_alignment/alignment.py b/lat_alignment/alignment.py index 63bec24..9dd82ce 100644 --- a/lat_alignment/alignment.py +++ b/lat_alignment/alignment.py @@ -76,8 +76,8 @@ def main(): cfgdir = os.path.dirname(os.path.abspath(args.config)) meas_file = os.path.abspath(os.path.join(cfgdir, cfg["measurement"])) - if "dat_dir" in cfg: - dat_dir = os.path.abspath(os.path.join(cfgdir, cfg["dat_dir"])) + if "data_dir" in cfg: + dat_dir = os.path.abspath(os.path.join(cfgdir, cfg["data_dir"])) corner_path = os.path.join(dat_dir, f"{mirror}_corners.yaml") adj_path = os.path.join(dat_dir, f"{mirror}_adj.csv") else: