Direct Fiber Positioning System Manual
[25-SEP-24] The DFPS-4A provides four positioners consisting of an actuator, a mast, and a ferrule with three fibers. One is a guide fiber that allows us to measure the location of the ferrule. The other two are detector fibers that allow us to collect light from celestial objects. The offset between the detector and guide fibers is known from calibration with an accuracy of ±20 μm. A rigid and stationary fiducial plate surrounds the tips of the masts and provides four guide sensors and four fiducial fibers. The positions and orientation of the guide sensors as well as the position of the fiducial fibers are known to within ±20 μm with respect to the local coordinate system of the fiducial plate.
The DFPS-4A global coordinate system is defined by three ball on the base plate. Two fiber view cameras within the DFPS-4A enclosure are calibrated by coordinate measuring machine so that they measure the absolute position of fiducial and guide fibers in the DFPS global coordinate system to within ±20 μm.
The calibration of the mast ferrules, fiducial fibers, guide sensors, and fiber view cameras together permit us to locate and orient the DFPS local coordinate system in celestial coordinate, and then to move a detector fiber onto a target in local coordinates. We must make sure that our target positions lie within the range of motion of their respective detector fibers. The mast tips move within 3.5-mm squares rotated by 45°. The DFPS Manager program will determine the ranges automatically at the press of a button.
[26-SEP-24] The following table defines unusual terminology we use in describing the DFPS.
| Term | Meaning |
|---|---|
| Actuator | The piezo-electric cylinder that bends when we apply voltage to its electrodes. |
| Mast | The carbon-fiber tube that turns the curvature of the actuator into movement of a detector fiber. |
| Controller | The logic, converters, and amplifiers that generate a single actuator's four electrode voltages. |
| Positioner | An actuator, mast, and controller that together move a detector fiber. |
| Ferrule | A cylinder with a precision center hole that presents one or more polished fiber tips. |
| Base Board | The printed circuit board that supports all the positioners of a single cell. |
| Service Board | The printed circuit board that holds the fiber controllers for all the positioners of a single cell. |
| Detector Fiber | A fiber used to capture and transport the light from a celestial object. |
| Guide Fiber | A fiber used to reveal the location of a detector fiber. |
| Guide Sensor | An image sensor at the edge of the positioner array that records the position of guide stars. |
| Fiducial Fiber | A fiber used to locate the positioner array with respect to celestial guide sensors. |
| Fiducial Plate | The metal frame that holds the guide sensors and fiducial fibers. |
| Fiber View Camera | A camera looking down on the fiber tips. |
| Global Coordinates | A coordinate system defined by three balls on the base plate. |
| Frame Coordinates | A coordinate system defined by the front, lower-left corner of the fiducial plate. |
| Local Coordinates | A coordinate system offset from the frame coordinate origin, at the nominal center of mast positions. |
| Mast Position | The position of the mast's guide fiber tip in local coordinates. |
| Detector Position | The position of one of a mast's detector fibers in local coordinates. |
[25-SEP-24] To run the DFPS Manager tool, clone our LWDAQ repository and check out the dfps branch. Run LWDAQ and the DFPS Manager will open as a standalone LWDAQ process. The System Server will be started automatically, but the mast controller will not be enabled.
We enter the IP address of the DFPS in the IP entry box. The flash is the exposure time we use when the fiber view cameras measure guide and fiducial fibers. The expose_s is the default exposure time when we acquire the guide sensor images.
The four guide sensor images are displayed side by side, after acquiring them all with the Guides button. as they are oriented on the fiducial plate. The origins of guide coordinates are the lower-left corner of the lower-left pixel in each image. Double-click on one of the guide sensor images and you will get a full-size view of the image. Click anywhere in the image and a cross will appear where you clicked. With the report box checked, you will see the local coordinates of the marked point in the guide sensor, including the z-position of the guide sensor itself, in millimeters. With the verbose box checked, you will get more details.
The fiber view images are down below, after pressing the Show button, which shows all guide and fiducial fibers. The Masts button instructs the manager to measure the positions of the guide fibers in all the masts.
Between the rows of images are entries that show the most recently measured mast positions in local coordinates. The positions are in millimeters and include only the x and y coordinates. Also shown are the current target positions. We enable the mast control system by checking the enable_mast_control box. The manager will measure and adjust the masts at intervals so as to bring their positions to the target positions. The default control system sample period is one minute, but we can make it faster or slower with the mast_control_period parameter. Press Configure to open the Configuration Panel and you will see this parameter along with many others in an array.
Other checkboxes are verbose, which directs lots of diagnostic messages to the text window, and report, which directs fewer messages that contain numerical data for performance testing. The Help button should open this manual, provided you are connected to the internet.
The Reset button. The manager will zero the actuator voltages, survey the fiducial fibers, adjust the pose of the local coordinate system with respect to the fiber view camera global system, and set the mast target positions to locations near the center of their range. The Utilities button opens the Utilities Panel.
[20-SEP-24] The Utilities Panel provides buttons that show us the current calibration constants and mast ranges, as well as to read new calibration constants for our instrument, or store our constants to disk.
The Survey Fiducials button instructs the manager to measure the fiducials and adjust the local coordinate pose. In the Mast and Detector Fiber Calibration utility, the MRanges button instructs the manager to measure the range of movement of all masts. As we rotate the DFPS, the mast sag will change, so using MRanges to update the mast ranges will correct for the sag. The same utility allows us the calibrate detector fibers, which is to measure their position in local coordinates relative to their guide fibers. We describe all the utilities in their own sections below.
[25-SEP-24] We are able to control the DFPS Manager over TCPIP on its host machine using the LWDAQ System Server. If we are running the DFPS Manager as a stand-alone LWDAQ process from within the dfps branch of the LWDAQ repository, the System Server will already be runnin and configured to receive connections on port 1090, and only from the local host address 127.0.0.1. If we are running the DFPS Manager from the master branch of LWDAQ, we must open the System Server from the LWDAQ File manu and start it running in receive mode. Once the server is running, we can connect to from the same host using address 127.0.0.1 and port 1090. The following Tcl commands connect, instruct, and read from the DFPS.
set sock [socket 127.0.0.1 1090] fconfigure $sock -buffering line -blocking 1 puts $sock "DFPS_Manager_mast_get 2" gets $sock result puts $result 3.012704 -0.996000 1.896970 close $sock
The script opens a socket to the DFPS Manager, sends and instructs to measure a mast position, reads the result, and prints the result to the console. The script configures the socket for line buffering. A newline characters in the outgoing data will cause the socket to flush. A newline character in incoming data will cause the socket to make the incoming data available for reading. The script configures the socket to be blocking so that reads from the socket will not return until the socket is ready to be read out. In our further examples, we will omit the opening, configuring, and closing instructions for brevity. Opening and closing sockets requires no significan over-head in the operation of the DFPS, so long as only one or two are open at a time. We can open and close a socket for each instruction if we want to.
The following script resets the DFPS-4A by calling DFPS_Manager_reset. The reset routine returns and empty string, but the manager will send a newline character anyway, so we can still use the socket to wait for the reset to complete.
puts $sock "DFPS_Manager_reset" gets $sock result puts "Reset complete." Reset complete.
When the DFPS Manager starts up, its server and watchdog processes are running, but the mast controller is not. The following command turns on the controller with sample period sixty seconds.
DFPS_Manager_configure_mast_control 1 60
The following Tcl commands acquire an ascii image from guide sensor three with a two-second exposure. We read and print out the string of numbers that describes the image properties. We read the entire image in ASCII format and print some representative pixel values from within the light-sensitive region of the sensor.
puts $sock "DFPS_Manager_guide_acquire 3 2" gets $sock result puts $result 73.2 2.4 119.0 66.0 700 520 7.4 puts $sock "DFPS_Manager_guide_get_ascii 3" gets $sock img puts [lrange $img 10000 10009] 70 71 74 72 75 72 71 71 71 73
When we read binary data from the manager, the manager will mark the end of the binary data by closing the socket. Thus your control software need only read until the socket is closed. It does not need to know the exact size of the image. In the following code we open a socket, send our command, then read until the manager closes the socket. After that, we close the socket at our end as well.
set sock [socket 127.0.0.1 1090] fconfigure $sock -buffering line -blocking 1 puts $sock "DFPS_Manager_guide_get 3" fconfigure $sock -translation binary -buffering none -blocking 1 set img [read $sock] puts [string length $img] 364000 close $sock
We could instead read exactly 36400 bytes from the socket, and leave teh socket open, but closing sockets after each command, or after only one or two commands, is a good way to punctuate communication with the manager.
The following converts a position in the coordinates of guide sensor number two into local coordinates.
puts $sock "DFPS_Manager_local_from_guide 2 2345.5 4235.1" gets $sock result puts $result 22.639 23.929 2.700
The command below gets the the most recent measurement of detector fiber number two in mast three, as well as four numbers describing the range of motion of the detector.
puts $sock "DFPS_Manager_detector_get 3 2" gets $sock result puts $result 0.094 -0.203 -0.978 -5.731 3.638 0.07
The following Tcl commands set the target position of detector fiber one in mast two. The target position is the local x and y in millimeters to which we would like the detector to move. If the control system is active and the target position is within the range of the mast, the mast will be driven to the target position. The routine returns the offset between the most recent measurement of the detector position from the new target position.
puts $sock "DFPS_Manager_detector_set 2 1 3.5 -0.5" gets $sock result puts $result -3.382 0.544
We can call any of the DFPS Manager procedures through the server socket.
[26-SEP-24] The Fiber View (FVC) Calibration utility combines two FVC images with Coordinate Measureing Maching (CMM) measurements of fiducial positions in DFPS global coordinates, as well as CMM measurements of the FVC mounting balls in global coordinates, to obtain the calibration constants of the two FVCs. The utility opens with a button in the Utility Panel. The program takes as input two images L.gif and R.gif from the left and right FVCs respectively, and a text file from the CMM.
The CMM text file must contain the diameter and x, y, and z coordinates of the cone, slot, and flat balls in the two FVC mounts. After that we must find diameter, x, y, and z coordinates of each calibration source ferrule. The file containing these measurements must be named CMM.txt. In addition to the measured diameters and coordinates, CMM.txt may contain any number of words that are not real number strings and any number of white space charcters. All words that are not real numbers will be ignored. Here is an example CMM text file with the correct format:
+---------------------+--------------+------+-----------+---------+ | Feature Table | | | | | +---------------------+--------------+------+-----------+---------+ | Length Units | Millimeters | | | | | Coordinate Systems | csys | | | | | Data Alignments | original | | | | | | | | | | | Name | Control | Nom | Meas | Tol | | g1 | Diameter | | 12.702 | ±1.000 | | g1 | X | | 0.000 | ±1.000 | | g1 | Y | | 0.000 | ±1.000 | | g1 | Z | | 0.000 | ±1.000 | | g2 | Diameter | | 12.700 | ±1.000 | | g2 | X | | 100.390 | ±1.000 | | g2 | Y | | 0.000 | ±1.000 | | g2 | Z | | 0.000 | ±1.000 | | g3 | Diameter | | 12.698 | ±1.000 | | g3 | X | | 1.023 | ±1.000 | | g3 | Y | | -0.155 | ±1.000 | | g3 | Z | | 175.224 | ±1.000 | | l1 | Diameter | | 6.349 | ±1.000 | | l1 | X | | 79.614 | ±1.000 | | l1 | Y | | 51.505 | ±1.000 | | l1 | Z | | 199.754 | ±1.000 | | l2 | Diameter | | 6.347 | ±1.000 | | l2 | X | | 119.777 | ±1.000 | | l2 | Y | | 51.355 | ±1.000 | | l2 | Z | | 264.265 | ±1.000 | | l3 | Diameter | | 6.350 | ±1.000 | | l3 | X | | 79.277 | ±1.000 | | l3 | Y | | 51.400 | ±1.000 | | l3 | Z | | 275.713 | ±1.000 | | r1 | Diameter | | 6.352 | ±1.000 | | r1 | X | | -104.039 | ±1.000 | | r1 | Y | | 51.210 | ±1.000 | | r1 | Z | | 199.297 | ±1.000 | | r2 | Diameter | | 6.352 | ±1.000 | | r2 | X | | -108.680 | ±1.000 | | r2 | Y | | 51.004 | ±1.000 | | r2 | Z | | 275.110 | ±1.000 | | r3 | Diameter | | 6.354 | ±1.000 | | r3 | X | | -148.231 | ±1.000 | | r3 | Y | | 50.989 | ±1.000 | | r3 | Z | | 261.059 | ±1.000 | | u1 | Diameter | | 2.498 | ±1.000 | | u1 | X | | -28.554 | ±1.000 | | u1 | Y | | 103.614 | ±1.000 | | u1 | Z | | -91.666 | ±1.000 | | u2 | Diameter | | 2.399 | ±1.000 | | u2 | X | | 1.447 | ±1.000 | | u2 | Y | | 103.722 | ±1.000 | | u2 | Z | | -92.199 | ±1.000 | | u3 | Diameter | | 2.401 | ±1.000 | | u3 | X | | -28.490 | ±1.000 | | u3 | Y | | 73.650 | ±1.000 | | u3 | Z | | -92.161 | ±1.000 | | u4 | Diameter | | 2.372 | ±1.000 | | u4 | X | | 1.433 | ±1.000 | | u4 | Y | | 73.749 | ±1.000 | | u4 | Z | | -92.267 | ±1.000 | +---------------------+--------------+------+-----------+---------+
The calibrator works by minimizing disagreement between actual spot positions and modelled spot positions. When we press Fit, the simplex fitter starts minimizing this disagreement by adjusting the calibrations of the left and right FVCs. The fit applies the fit_scaling values to the eight calibration constants of the cameras. We can fix any one of the eight parameters by setting its scaling value to zero. We always fix the pivot.z scaling factor to zero because this parameter has no geometric implementation.
The functions of the buttons are as follows. The Stop button aborts fitting. The Show button draws crosses in the two camera images to mark the locations at which we expect to see the spots given the CMM measurements and the current camera calibration constants. An accurate fit will have these crosses centered perfectly on the actual white spots in the images. The Displace button displaces the camera calibration constants from their current values by an amount proportional to each constant's scaling factor. The Fit button starts the the simplex fitter adjusting calibration constants to minimize disagreement. The Read button selects a CMM text file with a file browser window. Once we select a file, the Fiber View Calibrator will read CMM measurements from the file, read images L.gif and R.gif from the same directory, display the images, and check the disagreement between the current calibration constants and the measurements. The Defaults button restores the cameras to their default calibration constants.
To use the calibrator, press Read and select your measurements. The calibrator will display the images and the expected spot positions. Press Fit. Within less than a second, the fit will converge to camera calibration constants. If you would like to watch the fit, set fit_show. Now the fit will take about a minute, but each update of the camera constants will cause the crosses on the images to move, so we can see how the fit is performing. The camera calibration constants produced by the FVC Calibrator immediately become part of the DFPS Manager's calibration constant array. We can save them with the Save_Calibration button.
[20-SEP-24] The Guide Sensor Calibration utility uses a 100-mm square rasnik (Red Alignment at NIKhef) mask mounted in a frame identical to the DFPS fiducial plate to obtain the position and orientation of the plate's guide sensors in both frame and local coordinates. The utility opens with a button in the Utility Panel. The frame holding the rasnik mask is the calibration frame. To calibrate the four guide sensors of the DFPS-4A, we place a tube in the aperture of the DFPS and shine parallel light down the tube so as to obtain a contact print of the rasnik mask on our four sensors. We have the fiducial plate pressed up against an x-origin block on the left side as seen from the aperture. We press the calibration frame against the same bar, with the mask origin on the lower left. This is the 0° orientation of the calibration frame. We press the Acquire 0 button take images of the mask on all four guide sensors. The images show up in the calibration window, with the results of rasnik analysis. We rotate into the 90° orientation and press Acquire 90, and so on. When we have a full set of four images from each of the four orientations, with successful analysis of all sixteen images, we press Calculate and calibrator calculates the origins of all four guide sensors in local coordinates, as well as their rotations anti-clockwise with respect to the local coordinate system. We call these the sensors "poses". They are part of the DFPS Manager's calibration constant array.
[20-SEP-24] The Fiducial Fiber Calibration utility uses a pair of fiber view cameras and rotation of the fiducial plate into four orientations to obtain the positions of the fiducial fibers in local coordinates. The fiducial plate must be free to rotate, so we unrestrain its four fiducial optical fibers. We place in the 0° orientation, press up against the x-origin block, and measure the fiducial positions in global coordinates with the Acquire 0 button. We rotate to 90° and continue with Acquire 90. When we have the global coordinates of the fiducial fibers, as measured by the fiber view cameras, in all four orientations, we press Calculate. The utility will calculate the positions of all the fiducials using all six possible pairs of orientations, and print a table of the fiducial optical centers, averages and standard deviations. The DFPS Manager fiducial calibration will be updated immediately with the result of this new calibration.
[25-SEP-24] The Mast and Detector Calibration utility opens with a button in the Utility Panel. It provides two functions. One is to calibrated guide fibers, the other is to determine the range of motion of the masts.
To calibrate a detector fiber, we connect its output on the DFPS detector feedthrough panel to a fiber-optic light source. The DFPS-4A should come with its own detector calibration fiber coiled on the base plate in front of the fiducial stage. We leave one end of this fiber plugged into the injector. We run the other end out of the aperture and around to the detector fiber we want to calibrate. We connect the two. We enter the mast and detector numbers that identify this detector fiber into the boxes in the Detector Calibration utility. We press Calibrate. The utility measures the position of the mast's guide fiber and detector fiber separately. When measuring the detector fiber, it flashes the injector LED for the time given in the Detector Calibrator's flash entry box. The units of time for this parameter are seconds. The LED will flash at the power level given by pwr. We must flash the detector fiber with hundreds of times the intensity, and for twenty times longer, than we flash the guide fiber, because the fiber view cameras will be viewing the detector fiber outside the detector fiber's emission cone. The cameras see only second-order fringes of the emitted light, but still enough to measure the location of the detector. By simple subtraction, we obtain the calibration of the detector fiber, which is the vector from the guide fiber center to the detector fiber center.
As we rotate the DFPS the masts may sag, which adds an offset to their range of motion. The MRanges button initiates an automatic re-measurement of the mast ranges. We press Mranges button and the utility proceeds to move all masts to the bottom, left, top, and right corners, wait for several seconds to let the actuators settle, and measure the position on the guide fibers. Once it has the local coordinate positions of the guides in all four corners, it calculates the center of each range, the average side length of the rotated square that is the nominal range, and the rotation anti-clockwise of this square beyond the expected 45°. This angle we express in radians. The coordinates and lengths are in millimeters. These four numbers are our measurement of the range. We have one range for each mast.
[26-SEP-24] In the following subsections, we present the definitions and help text we extract automatically from the DFPS_Manager.tcl script. You will find this script in the LWDAQ/Tools folder.
proc DFPS_Manager_configure_mast_control {enable period_s}
DFPS_Manager_configure_mast_control starts or stops the mast controller and adjusts the mast control period. We pass 0 or 1 for enable to disable or enable the controller respectively. We pass a real-valued period in seconds. The controller will measure mast positions with this period, and adjust actuator voltages after its measurements.
proc DFPS_Manager_controller_set {id upleft upright}
DFPS_Manager_controller_set sets the north, south, east, and west electrode voltages of one or all controllers. It will set the voltages on one controller if we pass it a hexadecimal identifier other than the hexadecimal wildcard identifier, or if we pass it a decimal integer specifying a particular mast. From a mast index, we can obtain the mast's controller identifier using the global controllers list. In order to distinguish between integer mast numbers and hexadecimal controller identifiers, we must pass the identifiers with a "0x" prefis. The control values themselves must be unsigned integers between 0 and 65535. If the values exceed this range, they will be clipped to the range. The return string consits of the controller id and the DAC values that were actually applied after any clipping.
proc DFPS_Manager_controller_set_all {}
DFPS_Manager_controller_set_all sets the drive voltages of all controllers to the values specified in the upleft and upright configuration parameters. the routine does this by transmitting the control voltages with the controller wildcard identifier. It also sets the individual mast controller voltage values to the global upleft and upright value to reflect the change.
proc DFPS_Manager_controller_zero_all {}
DFPS_Manager_controller_zero_all sets the drive voltages of all mast actuators to their zero values. The routine does this by transmitting the control voltages with the controller wildcard identifier. It also sets the individual mast controller voltage values to the dac_zero value to reflect the change.
proc DFPS_Manager_detector_get {mast detector}
DFPS_Manager_detector_get returns the local x and y coordinate of a detector fiber in millimeters, as deduced from the most recent measurement of its mast position, as well as four numbers specifying the range of motion of the fiber. It calls mast get to obtain the mast position and mast ranges, and we simply add the detector fiber's offset calibration to the mast position and its range center to obtain the same values for the detector. In the DFPS-4A we have four masts numbered 1-4 and within each mast we have two detector fibers numbered 1-2.
proc DFPS_Manager_detector_set {mast detector x_d y_d}
DFPS_Manager_detector_set attempts to drive a particular detector fiber to a specified local x and y position in millimeters. We specify the detector with its mast and fiber number. The routine calculates the mast position that would put the detector fiber in the correct location, and sets the mast target position accordinly. Thus the target position is not the detector fiber position, but rather the mast position that should give rise to the desired detector position. We obtain the mast target by subtracting the detector's calibration offset from the detector target. Note that this routine does not adjust the mast's actuator voltages. The routine assumes that the control system will adjust the actuator voltages when it finds that the mast target and measured positions no longer agree. The routine returns the initial offset between the detector and target positions.
proc DFPS_Manager_dfcalib {}
DFPS_Manager_dfcalib measures the position of a guide fiber in local coordinates, measures the position of the chosen detector fiber in local coordinates, and subtracts the detector position from the guide position to obtain the x-y offset of the detector with respect to the guide fiber. We add this offset to the mast position, which is the guide fiber position, to obtain the detector position. The routine assumes that we have the detector calibration fiber plugged into the detector fiber output connector on the DFPS, so that light enters the detector and can be seen by the fiber view cameras. The optical energy we must inject into the detector must be intense: thousands of times more energy than we need to see the guide fiber. The fiber view cameras will be seeing the detector fibers outside their cone of emission, so that we see only traces of light at the fringes of the detector numerical aperture. During the calibration we will see the guide fiber flash twice, once for each FVC, and the detector fiber flash twice. Both will appear to be in the same location to the naked eye, but the detector fiber will be much brighter when seen looking down its axis.
proc DFPS_Manager_displace_all {}
DFPS_Manager_displace_all adds a displacement to the mast target positions. The masts will move only if the mast controller is active. We use this routine to mesure the step response of the control system.
proc DFPS_Manager_examine_calibration {}
DFPS_Manager_examine_calibration opens a new window that displays the CMM measurements of the left and right mounting balls, the camera calibration constants, and the fiducial plate measurements.
proc DFPS_Manager_frot {}
DFPS_Manager_frot opens the Fiducial Rotation Calibration window.
proc DFPS_Manager_frot_acquire {orientation}
DFPS_Manager_frot_acquire takes an orientation name as input, which directs where its output will be saved. It goes through the fiducials listed in the manager's fiducial_leds string and checks their positions one after another. It saves their positions in the frot measurement for the named position.
proc DFPS_Manager_frot_calculate {}
DFPS_Manager_frot_calculate takes the four measurements of fidicial fibers from four orientations and calculates for each fiducial its position in frame coordinates. For each orienation we construct the two-dimensional rotation matrix that transforms vectors in the 0-degree orientation to those in the new orienation. For the 0-degree orientaion this matrix is the identity matris. For each fiber and each pair of orientations, we subtract the second rotation matrix from the first, invert the difference matrix, and apply this transform to the vector between the two global positions of the fibers. The result is the vector from the center of the plate to the fiber. We now correct for a plate whose center is not exactly at our fiducial coordinate origin. If the width of the plate is 140 mm, for example, and our coordinate origin is at 65 mm, the center is 5 mm to the right of the coordinate origin, so we must add 5 mm to the x-coordinate of the vector from the center to the fiber in order to obtain the x-coordinate of the vector from the origin to the fiber.
proc DFPS_Manager_fsurvey {}
DFPS_Manager_fsurvey measures the four fiducial positions in the global coordinate system of the fiber view cameras and then proceeds to adjust the pose of the local coordinates so as to match the calibrated fiducial positions with the observed fiducial positions. If we execute this routine, translate the fiducial plate by 5 mm in x, and execute again, the pose of the local coordinates will move by 5 mm in x. Knowing the pose of the fiducial coordinates, we can transform global measurements of guide fibers into local coordinates, and so connect them with the local coordinates of star image on the guide sensors.
proc DFPS_Manager_fsurvey_err {params}
DFPS_Manager_fsurvey_err returns a measure of the disagreement between the measured positions of the fiducials and the positions we predict from our calibration of the fiducials and our fiducial coordinate pose. This routine will be called by the simplex fitter.
proc DFPS_Manager_fvc_click {fvc x y cmd}
DFPS_Manager_fvc_click handles mouse clicks on fiber view camera images. It takes a camera side "left" or "right", an x and y coordinate, and a command. The mag_fvc command tells the routine to open a new magnified view of a the fiber view image.
proc DFPS_Manager_fvcalib {}
DFPS_Manager_fvcalib opens the Fiber View Camera Calibrator window.
proc DFPS_Manager_fvcalib_altitude {params}
DFPS_Manager_fvcalib_altitude is the error function for the fitter. The fitter calls this routine with a set of parameter values to get the disgreement, which it is attemptint to minimise.
proc DFPS_Manager_fvcalib_check {}
DFPS_Manager_fvcalib_check projects the image of each source in the left and right cameras to make a bearing line in the left and right mount coordinates using the current camera calibration constants, transforms to global coordinates using the mounting ball coordinates, and finds the mid-point of the shortest line between these two lines. This mid-point is the FVC measurement of the source position. It compares this position to the measured source position and reports the difference between the two.
proc DFPS_Manager_fvcalib_defaults {}
DFPS_Manager_fvcalib_defaults restores the cameras to their default, nominal calibration constants.
proc DFPS_Manager_fvcalib_disagreement {{params ""} {show "1"}}
DFPS_Manager_fvcalib_disagreement calculates root mean square square distance between the actual image positions and the modeled image positions we obtain when applying our mount measurements, FVC calibration constants, and measured source positions. We pass our FVC calibration constants into the routine with the params argument. If we omit this argument, the routine uses the constants stored in the left and right camera entries of our config array. Another optional parameter enables or disables the display of the blue crosses that show where the current parameters suggest the sources must be. By default, the display is enabled. This routine is called by the simplex fitter two or three hundred times do obtain the optimal camera calibration constants. The fit takes a fraction of a second with the display disabled, roughly ten seconds with the display enabled. All the time goes into clearing and drawing the images on the screen.
proc DFPS_Manager_fvcalib_displace {}
DFPS_Manager_fvcalib_displace displaces the camera calibration constants by a random amount in proportion to their scaling factors. The routine does not print anything to the text window, but if show_fit is set, it does update the modelled source positions in the image. We want to be able to use this routine repeatedly to move the modelled sources around before starting a new fit, while reserving the text window for the fitted end values.
proc DFPS_Manager_fvcalib_fit {}
DFPS_Manager_fvcalib_fit gets the camera calibration constants as a starting point and calls the simplex fitter to minimise the disagreement between the modelled and actual bodies by adjusting the calibration constants of both parameter. The size of the adjustments the fitter makes in each parameter during the fit will be shrinking as the fit proceeds, but relative to one another thye will be in proportion to the list of scaling factors we have provided. These factors are applied twice: once to each camera. If the scaling factors are all unity, all parameters are fitted with equal steps. If a scaling factor is zero, the parameter will not be adjusted. If a scaling factor is 10, the parameter will be adjusted by ten times the amount as a parameter with scaling factor one. At the end of the fit, we take the final fitted parameter values and apply them to our body models.
proc DFPS_Manager_fvcalib_get_params {}
DFPS_Manager_fvcalib_get_params puts together a string containing the parameters the fitter can adjust to minimise the calibration disagreement. The fitter will adjust any parameter for which we assign a scaling value greater than zero. The scaling string gives the scaling factors the fitter uses for each camera calibration constant. The scaling factors are used twice: once for the left camera and once for the right. See the fitting routine for their implementation.
proc DFPS_Manager_fvcalib_read {{fn ""}}
DFPS_Manager_fvcalib_read either reads a specified CMM measurement file or browses for one. The fiber view calibrator reads the global coordinates of the balls in the left and right FVC mounts, and the locations of the four calibration sources. Having read the CMM file the routine looks for L.gif and R.gif in the same directory. These should be the images returned by the left and right FVCs of the four calibration sources. In these two images, the sources must be arranged from 1 to 4 in an x-y grid, as recognised by the BCAM Instrument.
proc DFPS_Manager_fvcalib_show {}
DFPS_Manager_fvcalib_show calls the disagreement function to show the location of the modelled sources, and prints the calibration constants and disagreement to the text window, followed by a zero to indicated that zero fitting steps took place to produce these parameters and results.
proc DFPS_Manager_global_from_local {x_L y_L z_L}
DFPS_Manager_global_from_local takes a point in local coordinates and transforms it into global coordinates using the local coordinate pose. We past the local x, y, and z coordinates of the point as separate parameters into the routine. See local_from_global for more information about the local and global coordinate systems.
proc DFPS_Manager_gscalib {}
DFPS_Manager_gscalib opens the Fiducial Plate Calibrator window.
proc DFPS_Manager_gscalib_acquire {orientation}
DFPS_Manager_gscalib_acquire reads images from all four guide sensors, analyzes them with the correct orientation codes, displayes them in the gscalib window and returns the mask x and y coordinates of the top-left corner of the image, as well as the anti-clockwise rotation of the mask image with respect to the image sensor. We must specify an orientation of the fiducial plate so that we can get the rasnik analysis orientation code correct.
proc DFPS_Manager_gscalib_calculate {}
DFPS_Manager_gscalib_calculate takes the four rasnik measurements we have obtained from the four orientations of the mask and calculates the mask origin in frame coordiates, the mask rotation with respect to frame coordinates, counter-clockwise positive, and the origins of the four guide sensors in frame coordinates as well as their rotations counter-clockwise positive with respect to frame coordinates.
proc DFPS_Manager_guide_acquire {guide exposure_s}
DFPS_Manager_guide_acquire acquires an image from one of the DFPS guide sensors with a specified exposure time. It stores the image in the LWDAQ image array with the name dfps_guide_n, where n is the guide sensor number. It returns a string of information about the image, as obtained from the Camera Instrument. If the string is an error message, it will begin with "ERROR:". Otherwise it will contain seven numbers. These are the average, stdev, maximum, and minimum intensity in the image in units of eight-bit counts, followed by the number of rows and the number of columns, and finally the pixel size in microns. Multiply the number of rows by the number of columns to get the image size in bytes. Multiply the number of rows by the pixel size to get the height of the image in microns. Multiply the number of columns by the pixel size to get the width.
proc DFPS_Manager_guide_acquire_all {}
DFPS_Manager_guide_acquire_all capture images from all guide sensors and displays them in the manager window. It uses the default guide exposure time exposure_s.
proc DFPS_Manager_guide_click {guide x y cmd}
DFPS_Manager_guide_click handles mouse clicks on guide sensor images. It takes a guide sensor number, an x and y coordinate, and a command. The mag_g command tells the routine to open a new magnified view of a guide sensor. The mark_g and mark_gm commands tell the routine to mark a guide sensor view, based upon the x-y coordinates of a mouse click in the normal guide sensor display or the magnified guide sensor display. The actual marking, which will be a cross of some sort, will be done in the guide_mark routine, which will in turn be called by local_from_guide, which we call from this routine.
proc DFPS_Manager_guide_from_local {guide x_L y_L z_L}
DFPS_Manager_guide_from_local takes a local coordinate position and transforms it into the coordinates of one of the guide sensors. Because the guide sensor is a two-dimensional plane, we take the three-dimensional local coordinate point and project it onto the guide sensor in the z-direction. We pass the local coordinates into the routine with a string of three numbers xyz in millimeters. We pass the local coordinate point as three separate parameters x, y, and z in millimeters. The routine returns the guide coordinate x and y in microns.
proc DFPS_Manager_guide_get {guide}
DFPS_Manager_guide_get returns the contents of a guide image as a byte array. The image must be one we have acquired previously with guide_acquire. If we encounter an error, the routine returns an array of zero-bytes of the correct size to satisfy a process that expects a full image of bytes. The routine sets the global binary_result flag. If the guide_get was requested through the system server, this flag will tell the system server that it should configure the server socket for binary transfer, and send the byte array as a single binary block with no end of line character.
proc DFPS_Manager_guide_get_ascii {guide}
DFPS_Manager_guide_get_ascii returns the byte array contents of a guide image as a string of space-delimited decimal values, each value between 0 and 255 to represent eight-bit grayscale. The routine calls guide_get to obtain the binary image, then translates into decimal ascii.
proc DFPS_Manager_guide_mark {guide x_g y_g {color "2"}}
No description available.
proc DFPS_Manager_guide_put_square {guide x_L y_L z_L width {shade "200"}}
DFPS_Manager_guide_put_square creates a white square in a guide sensor image by over-writing real image pixels. It takes as input a guide sensor number, a local coordinate point as x, y, and z in millimeters, a square width in microns, and an optional eight-bit grascale intensity. The routine uses the guide sensor and fiducial plate calibrations to project the square image onto the guide sensor. The projection includes widening that mimics defocus in a telescope that would result from the guide sensor being offset in the z-direction from the focal plane. We perform the defocus with the global focal_ratio parameter. The square will have intensity "shade", which defaults to a bright value. The routine returns the guide coordinates of the center of the square, and the square's width in microns after application of defocus.
proc DFPS_Manager_id_bytes {id_hex}
DFPS_Manager_id_bytes returns a list of two bytes as decimal numbers that represent the identifier of the controller. Thus 0xFF10 returns as "255 16". The identifier we pass into the routine must be a four-digit hexadecimal value with the prefix "0x".
proc DFPS_Manager_init {}
DFPS_Manager_init creates and initializes the DFPS Manager Tool's configuration (config) and information (info) arrays. It reads saved configuration (but not information) parameters from disk if we have previously saved our configuration to disk. All the configuration parameters are visible in the tool's configuration array, where there are save and unsave buttons to create and delete a default configuration file.
proc DFPS_Manager_local_from_global {x_G y_G z_G}
DFPS_Manager_local_from_global takes a point in global coordinates and transforms it into local coordinates using the local coordinate pose. We pass the global x, y, and z coordinates as separate parameter. The DFPS global coordinate system is defined by three half-inch steel balls sitting on the base plate in front of the fiducial stage. The DFPS local coordinate system is defined by its fiducial plate. The fiducial plate defines a frame coordinate system with its front, lower-left corner as the frame coordinate origin, the bottom front edge as the frame coordinate x-axis, and the y-axis perpendiculare to the fiducial stage. The local coordinates are at x = local_offset_mm, y = local_offset_mm in frame coordinates. In the DFPS-4A, local_offset_mm is 65 mm. The local coordinate pose consists of the origin of local coordinates expressed as a point in global coordinates and three rotations that allow us to obtain the local coordinates by rotating about the global x, y, and z axes. We obtain the local coordinate pose using our fiducial survey procedure. We have the positions of the fiducial fibers in local coordinates from our fiducial rotation calibration. The fiducial survey procedure measures the position of the fiducials in global coordinates using the fiber view cameras and adjusts the pose so as to minimize the error between the modeled fiducial positions and the measured fiducial positions. If the transformation between local and global coordinates is to be accurate, we must be sure to survey the fiducials at the start of each observing session.
proc DFPS_Manager_local_from_guide {guide x_g y_g}
DFPS_Manager_local_from_guide converts a point in a guide sensor to a point in local coordinates. We specify the point in the guide sensor with the guide sensor number, the guide x-coordinate in microns, and the guide y-coordinate in microns. The guide point is two-dimensional, but our calibration of the guide sensor provides us with the local z-coordinate of the sensor surface. The calibration also provides the local x and y of the guide origin and the anti-clockwise rotation in milliradians of the guide coordinate system with respect to local. The guide coordinate system has its origin at the bottom-left corner of the lower-left pixel in the guide image. The x-axis is to the right, the y-axis is upwards. We can view the guide sensor calibrations with the examine_calibration procudure. The local coordinate system is at the approximate center of the fiducial plate. We calibrate the sensors and fiducials in frame coordinates, then offset the frame coordinates by local_offset_mm in both x and y to obtain local coordinates. The frame coordinate system is at the front, lower-left corner of the fiducial plate, with its x-axis running along the front edge and the y-axis perpendicular to the fiducial stage. The routine returns x, y, and z coordinates of the transformed local point in millimeters.
proc DFPS_Manager_mast_get {mast}
DFPS_Manager_mast_get returns the most recent measurement of a mast's local x and y position as well as the most recent measurement of mast dynamic range. The routine does not return the local z-coordinate of the mast. During DFPS operation, we are assuming the guide sensors, guide fibers, and detector fibers are all in the same local z-plane. In the return string, we have first the local x and y coordinates in millimeters, then four numbers that describe the mast's range of motion. This range we assume to be a square rotated by forty-five degrees in a local coordinate z-plane. We give the local x and y coordinates of the center of this square in millimeters. We give the side of the square in millimeters. Last of all is a small rotation, given in radians, by which the square is rotated anti-clockwise from its nominal forty-five orientation. Use mast_get to obtain the mast position when the mast controller is running, because the mast controller is already measuring the mast position every control sample period.
proc DFPS_Manager_mast_measure {mast}
DFPS_Manager_mast_measure measures the position of a mast and returns the local x, y, and z coordinates of a mast. The position of the mast is defined as the opitcal center of its guide fiber. We flash the mast's guide fiber once for each fiber view camera and use the FVC calibration to obtain the global coordinates of the the optical centroid of the fiber tip. We transform this centroid into local coordinates using the local coordinate pose, which we have obtained previously using the fiducial survey routine. The routine returns the x, y, and z coordinates of the guide fiber in local coordinates, which is what we take to be the mast position. The fiber control system uses this routine monitor the position of all masts. There is no need for us to call this routine to get the local x and y position of a mast when the controller is running. We can use the mast_get routine to get the most recent measurement of mast position, and in addition that routine returns the most recent measurement of mast range.
proc DFPS_Manager_mast_measure_all {}
DFPS_Manager_mast_measure_all measures the positions of all masts one by one and returns their x-y positions in local coordinates. It also reports these positions if the report flag is set.
proc DFPS_Manager_mast_set {mast x_t y_t}
DFPS_Manager_mast_set sets the target position of a mast's guide fiber. We specify the target position with only x and y in local coordinates, because there is no point in specifying a z-coordinate for a positioner that moves only in x and y. The routine assignes the specified values to the target xy string belonging to the specified mast and re-calculates the mast offsets. It does not make any effort to change the actuator control voltages, but instead relies upon the control system to move the mast to the correct position. It returns the offsets from the new target, which it calculates from the x and y coordinates of the most recent mast measurement.
proc DFPS_Manager_mcalib {}
DFPS_Manager_mcalib opens the Detector Fiber Calibration window.
proc DFPS_Manager_mranges {{masts ""}}
DFPS_Manager_mranges measures the center of the range of motion of a set of masts, the length of the side of the rotated square that is the range, and the rotation of the range counter-clockwise in local coordinates as seen looking down on the mast tip from the aperture of the instrument. The rotation is in radians. The routine stores these values in each mast's range parameter. If no masts are specified, all masts are measured. In order to make sure the masts do not interfere with one another, the procedure moves all masts together, using the controller wild card. It waits for the mcalib settling time at each corner before recording the position. At the end of the process, mranges returns all masts to their zero position.
proc DFPS_Manager_open {}
DFPS_Manager_open creates the DFPS Manager window if it does not exist, brings it to the front if it does exist.
proc DFPS_Manager_read_calibration {{fn ""}}
DFPS_Manager_read_calibration reads calibration constants from a named file, or from the default file if no file is specified.
proc DFPS_Manager_reset {}
DFPS_Manager_reset surveys the fiducials to obtain a new local coordinate pose, sets the mast target positions to the centers of the mast ranges, zeros the control voltages on all controllers, re-measures the mast positions, and shows all fiducial and guide sources.
proc DFPS_Manager_save_calibration {{fn ""}}
DFPS_Manager_save_calibration saves the fiber view mounts, camera parameters, fiducial positions, guide sensor positions, detector fiber offsets, actuator ranges, and actuator maps to disk in the Tools/Settings folder.
proc DFPS_Manager_show_spots {}
DFPS_Manager_show_spots flashes all the fiducials and guides so we can see their images in the fiber view images. It finds all the spots, but may get them mixed up.
proc DFPS_Manager_sources_global {spots}
DFPS_Manager_sources_global calculates source positions in global coordinates from a set of left and right camera image positions. Each image is a "spot" with a centroid position measured in microns from the top-left corner of the top-left pixel. We pass it a list containing the coordinates of the spots in the forma "x1l y1l x1r y1r... xnl ynl xnr ynr" where "n" is the number of sources, "l" specifies the left camera, and "r" specifies the right camera. The routine returns a list of source positions in "x1 y1 z1 ... xn yn zn" in global coordinates. The routine checks to see if the spot positions are invalid, which is marked by coordinates "-1 -1 -1 -1", and if so, it returns for the source position the global coordinate origin.
proc DFPS_Manager_spots {{leds ""}}
DFPS_Manager_spots captures an image of the sources whose light sources are listed in the leds argument. If we pass an empty string for the elements, the routine combines the fiducial and guide elements to obtain a list of all available sources. It returns the coordinates of the two images of each source in the left and right cameras in the format "x1l y1l x1r y1r... xnl ynl xnr ynr", where "n" is the number of sources it flashes.
proc DFPS_Manager_transmit {commands}
DFPS_Manager_transmit takes a string of command bytes and transmits them through a Command Transmitter such as the A3029A. The routine appends a sixteen-bit checksum. The checksum is the two bytes necessary to return a sixteen-bit linear feedback shift register to all zeros, thus performing a sixteen-bit cyclic redundancy check. We assume the destination shift register is preloaded with the checksum_preload value. The shift register has taps at locations 16, 14, 13, and 11.
proc DFPS_Manager_utils {}
DFPS_Manager_utils opens the Utilities Panel, where we have various options for calibrating the DFPS optical components, transmitting commands to fiber controllers, and opening LWDAQ instruments.
proc DFPS_Manager_utils_transmit {}
DFPS_Manager_utils_transmit sends the command in the utils_cmd parameter to controller utils_id.
proc DFPS_Manager_watchdog {}
DFPS_Manager_watchdog watches the system commands list for incoming commands, manages periodic survey of the fiducial fibers, and manages the mast position controller. It posts itself repeatedly to the LWDAQ event queue. Each time it runs, it checks the fiducial survey timer, the mast control timer, and the server command list. A fiducial survey causes the fiber view cameras to measure the fiducial positions, followed by adjustment of the local coordinate pose in the global DFPS coordinates. This pose allows us to convert fiber view camera measurements of mast positions into local coordinates. The mast controller measures mast positions, calculates their offsets from their target positions, and adjusts the actuator drive voltages so as to move the mast closer to its target position. We can enable and disable the mast controller, as well as set the controller sample period, with the configure_mast_control routine. The system server takes commands from the server socket, executes them, and returns the command result string over the same socket.