Orientation & setup
- Say what PupilMetrics Research is for, and what it is not
- Start a trial or activate a licence
- Walk through the scan flow and use the desktop shortcuts
What the app is
PupilMetrics Research photographs both eyes and measures the static pupil against the iris: pupil–iris (P/I) ratio, pupil shape and position, the collarette (ANW) and the shape of the pupil margin itself. A separate PLR mode records the pupil's response to a flash of light. Every result is stored on the device, so the next visit can be compared with this one.
It is a research and educational tool for practitioners. It is not a medical device. No FDA clearance, CE mark or equivalent exists for it, and nothing it reports is a diagnosis. You interpret the numbers; the clinical decisions are yours.
Licensing
| Tier | Duration | Machines |
|---|---|---|
| Trial | 14 days or 20 analyses, whichever ends first. Every feature. | 1 |
| Standard | 1 year | 1 |
| Professional | Lifetime | 1 |
| Enterprise | Lifetime | Multiple |
On the licence screen, click Start Free Trial, or paste a key and click Activate License. Activation contacts licenses.cnri.edu once to bind the key to the machine, and after that the app runs offline. A capture that fails is not counted against the 20 trial analyses. On iOS, purchases are made in the app rather than with a key.
The scan flow
The patient form asks for name, age and sex. Main complaints and the practice name are optional, and the practice name is remembered between sessions. Enter the age carefully: it chooses the age band the pupil is compared against, and for PLR it chooses the reference ranges.
Desktop shortcuts
| Key | Action |
|---|---|
| F11 | Toggle fullscreen |
| Ctrl + H | Open scan history from anywhere |
| Esc | Go back or close the current dialog |
The settings icon in the title bar is available on every screen. It holds the practice name, the language (20 locales), camera and PDF options.
Which statement best describes PupilMetrics Research?
- A cleared diagnostic medical device
- A research and educational tool whose measurements the practitioner interprets
- A cloud service that stores scans remotely
- An automated screening test for brain injury
It is not a medical device, and its data stays on the device. Every number is an observation that you interpret.
Capturing a usable image
- Choose a camera source for the situation
- Read the quality gate and fix what it reports
- Frame, light and steady an eye so the measurements hold
- Import archived photos correctly
Almost every doubtful result goes back to the image. A blurred capture does not produce a missing number. It produces a confident wrong one, which is worse. Two extra minutes at capture save you from interpreting a measurement of glare, eyelash or the wrong circle.
Capture order
The app captures the right eye (OD) first, then the left eye (OS). Analysis needs both.
Camera sources
You choose the source for each eye on the camera mode selector.
| Source | Use it when |
|---|---|
| Iriscope / External | A Dino-Lite AM4115ZT or compatible USB iriscope. The deepest integration, and the primary setup on Windows. |
| Wireless iriscope | Windows, with the HF4115-RUT and WF-20 adapter. Connect the computer to the iriscope's own Wi-Fi network first. |
| Binocular Iriscope | A dual-lens USB camera, so one capture holds both eyes. |
| Quality-gated auto-capture | Phones and tablets, rear or front camera. The recommended mobile method, because the gate takes the photo only when the frame passes. |
| Manual Capture | You need the shutter yourself: a macro attachment, or lighting that makes the gate reject good frames. |
| Load from Gallery | Re-analysing an archived photo. The file is copied into the app's folder, so the original is never changed. |
The quality gate
Every frame is checked against five criteria at once. An image that fails does not reach analysis.
| Criterion | Must be | Catches |
|---|---|---|
| Sharpness | ≥ 100 | Motion blur, missed focus |
| Brightness | 30–230 of 255 | Under- and over-exposure |
| Contrast | ≥ 30 | Flat frames with no detail |
| Pupil confidence | ≥ 30% | No detectable pupil: a blink, or the eye off target |
| Centre offset | ≤ 28% of the shorter side | A pupil too far from the centre of the frame |
RED at least one criterion fails, and the live message names it. AMBER borderline: a small adjustment is enough. GREEN every criterion passes and the photo is taken automatically. A separate “not an eye” check runs after capture in every mode, manual included.
Lighting, framing, stability
- Lighting. Diffuse and even. The iriscope's own LED ring is ideal. Extra lamps add reflections on the cornea.
- Framing. Let the iris fill at least half the frame width, centred. A pupil near the edge of the frame costs decentration accuracy directly.
- Distance. About 2–3 cm from the eye with a Dino-Lite. Adjust until the pupil margin is sharp, because the margin is what the zone findings and the P/I ratio are measured from.
- Stability. Brace your hand or the device, and ask the patient to fix their gaze on a distant point. The gate rejects blink frames by itself.
On Windows, install the DNVideoX driver before you connect a Dino-Lite for the first time. Full sensor resolution in Settings captures at the camera's maximum (1280×1024 on a Dino-Lite Premier) from the next time the camera opens.
Reflections near the pupil
When a reflection lies closer to the pupil border than 20% of the pupil radius, the app shows a warning on the result card, in the PDF and on the stored scan. The analysis still runs and nothing is withheld, but a border finding on that eye may have been produced by the light rather than by the iris. The warning marks images at risk. It does not catch every affected image.
Phones and imported photos
Hold the phone upright and let the eye fill the frame. Every capture path, imports included, ends in a 4:3 crop step. For an imported photo it matters more than it looks: the detector searches for the iris edge at set fractions of the frame width, so an arm's-length photo with a small iris in the middle puts the edge outside that search. Cropping to the eye brings it back into range. Enlarging the image does not, because the fraction stays the same. You can import both eyes in one action: the app asks for the right eye, then the left.
Do
- Ask the patient to look at a distant point
- Brace your hand or the device
- Shift slightly to move a reflection off the pupil border
- Let the iris fill at least half the frame width
- Use the same device, distance and zoom at every visit
Avoid
- Overhead lights reflecting in the cornea
- Pre-cropping phone photos into wide strips
- Switching to manual mode just to get past a gate that is right
- Mixing devices or framings in one patient's history
The quality gate turns green. What happens next?
- You press the shutter
- The photo is taken automatically
- The app switches to manual mode
- Analysis runs on the live preview
Green means all five criteria pass, and the gate takes the photo itself.
An arm's-length phone photo shows a small iris in the middle of a wide frame. What should you do?
- Enlarge the image before importing it
- Import it unchanged, because the ML model corrects for it
- Crop tightly around the eye in the 4:3 crop step
- Convert it to black and white
The detector looks for the iris edge at a fraction of the frame width. Cropping changes that fraction. Enlarging does not.
Reading the static measurements
- Read P/I ratio, shape, position and anisocoria against their bands
- Grade flattening and protrusion zone findings
- Explain why the millimetre figure is a conversion
- Use the confidence grade to decide whether to trust a result
Two pipelines, on purpose
Every image goes through two independent analyses. The classical computer-vision pass works on the full-resolution pixels and finds the pupil and iris boundaries. The ML model sees a 224×224 crop centred on the iris and predicts the P/I ratio only, through a calibrated linear fit (R² = 0.856). The result card says which of the two produced the P/I you are reading. Where the two disagree, the confidence score falls, and that disagreement is useful information in itself.
- Pupil
- The dark centre. The cyan line across it is its diameter.
- Collarette
- The autonomic nerve wreath (ANW), drawn in amber.
- Iris
- Its outer edge is the limbus. The line underneath is the iris diameter.
A schematic, not to scale. Each ratio below divides a diameter by the iris diameter, so the numbers do not depend on the size of the image.
P/I ratio (pupil ÷ iris × 100)
| P/I | Label |
|---|---|
| < 15% | Miosis (very constricted) |
| 15–19.9% | Constricted |
| 20–29.9% | Normal for adults in indoor light |
| 30–39.9% | Dilated |
| ≥ 40% | Mydriasis (very dilated) |
The millimetre figure is a conversion
The app measures a ratio. The image has no scale reference, so the app cannot measure millimetres directly. Every millimetre figure is the ratio multiplied by an assumed iris diameter: 12.0 mm for adults and teenagers, less for young children. Real adult irises run from about 10.2 to 13.0 mm. Treat the millimetre column as a convention that makes bands comparable, and the ratio as the measurement.
Pupils get smaller with age, so the result is also compared against an age band:
| Age | Expected | Normal range |
|---|---|---|
| Under 1 | 2.2 mm | 2.0–2.5 mm |
| 1–5 | 4.0 mm | 3.5–4.5 mm |
| 6–11 | 4.3 mm | 3.8–4.8 mm |
| 12–19 | 4.2 mm | 3.5–5.0 mm |
| 20–39 | 3.5 mm | 3.0–4.2 mm |
| 40–59 | 3.0 mm | 2.5–3.5 mm |
| 60 and over | 2.7 mm | 2.3–3.2 mm |
Infants are measured against a smaller assumed iris, because a newborn's iris is about 10 mm, not 12. With the adult figure, every infant pupil read about 20% too large, and normal infants were reported above their band.
Try it: P/I and anisocoria
Enter the pupil and iris diameters in pixels for each eye. The example values are invented. Change them and watch the bands move.
Zone findings: flattening and protrusion
The pupil margin is compared, zone by zone, with its own median radius. A flattening means the margin is pulled inward at that zone. A protrusion means it bulges outward. Each eye reports up to four of each.
| Deviation | Severity |
|---|---|
| < 1.5% | Not reported |
| 1.5–2.9% | Within limits, not flagged |
| 3.0–5.9% | Mild |
| 6.0–9.9% | Moderate |
| ≥ 10% | Significant |
Each finding names its zone, its clock span and its deviation, and then the association claimed for that zone, in that order: the measurement comes before the interpretation. The associations are research-derived theoretical frameworks from historical literature. A protrusion is a measured deviation of the margin; what it means is a hypothesis.
Collarette (ANW) ratio
| ANW ratio | Status |
|---|---|
| < 25% | Spastic: ring drawn inward |
| 25–35% | Normal |
| > 35% | Atonic: ring expanded outward |
A difference of up to 10% between the two eyes' ANW ratios counts as normal. When one eye reads Spastic and the other Atonic, the app flags a Functional Frustration pattern.
Shape, position and symmetry
| Measure | Flagged when | Notes |
|---|---|---|
| Ellipseness | < 95% | Minor ÷ major axis. Below 95% the form is named: horizontal, vertical or diagonal oval, chord-like or irregular. |
| Decentration | ≥ 6% of iris radius | Offset of the pupil centre from the iris centre, with a direction and an angle. |
| Anisocoria | ≥ 0.25 mm mild · ≥ 0.50 mm moderate · ≥ 1.00 mm severe | From moderate upward, a TBI research-observation flag is raised. It is a reference, not a diagnosis. |
Anisocoria is graded on the converted millimetre difference: the P/I difference in percentage points × 12.0 mm ÷ 100. It only compares like with like. If one eye's P/I came from the ML model and the other's from the classical pass, the comparison uses the classical value for both, because a mixed pair would measure the gap between two methods rather than between two pupils.
Hybrid confidence and the grade
One score combines capture quality (20%), classical confidence (35%), ML plausibility (20%) and the agreement between the two P/I values (25%). The grade follows from it: A from 85%, B from 70%, C from 55%, D below that. Three caps stop a good average from hiding a bad part: weak classical detection caps the score at 40%, poor capture quality at 50%, and strong disagreement between the two P/I values at 35%.
A flattening in one zone measures 7.2%. What severity is that?
- Within limits
- Mild
- Moderate
- Significant
Moderate runs from 6.0 to 9.9%. Mild is 3.0–5.9%, and Significant starts at 10%.
The two eyes' P/I ratios differ by 4.5 percentage points, both from the same pipeline. How is the anisocoria graded?
- None
- Mild
- Moderate, with the TBI research flag
- Severe
4.5 × 12.0 mm ÷ 100 = 0.54 mm, which falls in the 0.50–1.00 mm moderate band. The TBI flag is a research-observation reference, not a diagnosis.
The pupillary light reflex
- Say when a PLR recording adds something a still image cannot
- Record under conditions that make the numbers comparable
- Read each parameter's verdict and the recording's grade
- Explain why the measured frame rate matters
A still image shows the pupil at one moment. The light reflex shows how it responds: how soon it starts to constrict, how far and how fast it goes, and how quickly it recovers. PLR results appear on their own screen and in their own history tab. They are not merged into the static iris analysis, because they are a different measurement.
Sources
| PLR source | What to expect |
|---|---|
| Direct USB | Event-driven capture from a USB Dino-Lite, measured at about 27–30 fps, with a microsecond timestamp on every frame |
| Wired iriscope | The older bridge path with LED stimulus, about 15 fps |
| Wireless iriscope | A Wi-Fi Dino-Lite (WF-20) with LED stimulus |
| Phone video | Android, rear or front camera |
Recording
Dim the room first. Each recording starts with about three seconds of darkness, so the pupil reaches its dark-adapted size, and then the flash fires. Keep the eye centred and still, and let the patient rest before a repeat, so the pupil can re-adapt.
Every parameter gets its own verdict
Latency, constriction, maximum constriction velocity and T75 recovery are each compared with the reference range for the patient's age group (18–40, 41–60, 61 and over) and marked Normal, Borderline or Abnormal:
- Normal: inside the reference limits (the mean ± 2 SD).
- Borderline: outside them, but within 3 SD of the mean.
- Abnormal: beyond 3 SD.
Velocity is flagged only when it is too slow, and T75 only when recovery takes too long. When no age was entered, the ranges fall back to the 18–40 adult band, and the result says so rather than defaulting silently. For adults 18–40, the limits are:
| Parameter | Reference limits, 18–40 | Evidence |
|---|---|---|
| Latency | 161–289 ms | Published |
| Constriction | 18.6–43.4% | Published |
| Max velocity | ≥ 2.6 mm/s | Estimated |
| T75 recovery | ≤ 2.4 s | Published |
Each range carries an evidence tag on the report: Published (taken from a peer-reviewed study, Bitsios et al. 1996), Interpolated (the 41–60 band, between two published bands) or Estimated (all velocity and PIPR ranges). Treat a borderline or abnormal flag on an estimated range as a hypothesis.
Velocity in mm/s depends on an assumed iris diameter, 11.5 mm by default, like every millimetre figure. Latency, constriction percentage and T75 are times or ratios, so the assumption does not affect them.
The frame rate is measured, not assumed
The report states the frame rate it actually achieved. A camera that promises 30 fps and delivers 15 puts every time-based metric out by a factor of two, so the app reports what it measured. At 30 fps one frame lasts about 33 ms, which means latency differences smaller than one or two frames are not meaningful. Latency-sensitive work needs 60–120 fps.
The grade
Each recording gets a letter grade from the strength of its response and the quality of its signal. If 30% or more of the frames were rejected for quality, the grade drops one letter. A grade of D or lower points to a capture problem, not a finding: dim the room, wait for the dark baseline, centre the eye, and record again after a rest.
No age was entered before a PLR recording. What are the parameters compared against?
- Nothing: the verdicts are left blank
- The 18–40 adult ranges, and the result says so
- The 61-and-over ranges, to be cautious
- An average of all three age groups
The ranges fall back to the 18–40 band, and the result states that no age was provided.
Two recordings at 30 fps show latencies 20 ms apart. What can you conclude?
- The second patient reacts more slowly
- One of the recordings is Abnormal
- The camera is faulty
- Nothing yet: 20 ms is less than one frame
At 30 fps one frame is about 33 ms. Latency differences below one or two frames are not meaningful.
Visual tools
- Pick the right overlay for what you are looking for
- Compare both eyes side by side
- Keep the texture tools in their proper place
The chips on the results screen switch overlays on and off over the captured iris. None of them changes a measurement: every metric and export is calculated from the original capture.
| Tool | What it shows |
|---|---|
| Enhance | CLAHE contrast, equalised tile by tile rather than across the whole image. It brings out crypts and fibre texture without blowing out the bright areas. |
| 3D Relief | The iris as a height map: brightness becomes elevation, so raised fibres stand up and crypts sink, textured with the original image. |
| Heatmap | A thermal scale over local pigment density. Heterochromia sectors and a darkened ciliary zone become obvious. |
| Gabor | A bank of oriented filters at four scales, the classic texture operator of iris analysis. Fibres and furrows show as bright ridges. |
| LBP | Local binary patterns over the stroma, with a histogram. It does not depend on how the eye was rotated at capture. |
| Annotate | Freehand drawing on the image, with Undo and Clear. Save PNG writes the image and your marks as one file. |
Visual Compare
Visual Compare shows both irides in zoomable panels with the bilateral metrics beneath. Mirror OD flips the right eye so both are shown nasal side inward, the usual bilateral orientation. Sync Pan ties the panels together, so you look at the same region of each eye. Each panel shows that eye's confidence, so an asymmetry caused by one poor capture shows up as one poor capture.
The Research tab
The Research tab gathers more specialised instruments in a full-screen workspace, for comparative case studies and teaching. Routine use does not need it. Its automatic detections (crypts, contraction furrows, heterochromia sectors) are proposals: confirm each one by eye before you write it down.
You want to compare LBP texture between two patients captured on different iriscopes. What is the problem?
- Texture measures depend on lighting and the camera, so they are only comparable within one patient on one device
- LBP only works on the right eye
- LBP needs the 3D Relief view switched on first
- There is no problem: LBP is rotation-invariant, so it is device-invariant too
Rotation invariance is not device invariance. Texture measures are device-relative and need a calibration the app does not perform.
History, timeline & exports
- Find and reopen past scans
- Read a patient's timeline critically
- Choose the right export for the job
One scan is a data point
Every completed analysis is written to the local database as soon as the results screen finishes loading. There is no save step to forget. Open Scan History with Ctrl + H on the desktop, or with the button on the results screen. Static scans and PLR recordings are kept in separate tabs, and any record reopens with its full result.
Serial Scan Timeline
From a history record, the Serial Scan Timeline plots up to six series for that patient across every scan on file: P/I, ellipseness and hybrid confidence, for each eye. Each series can be switched on and off.
The thumbnail strip is the point. A spike in a trend line is one click from the image that produced it, so you can recognise an artefact as an artefact instead of writing it up as a change. Confidence is plotted next to the metrics for the same reason: a series that moves while its confidence falls is telling you about the capture, not the patient.
Exports
| Format | Use it for |
|---|---|
| The primary report. Both eye images sit on page one unless you turn images off, the practice name appears on every page header, and the whole report is written in the current app language. | |
| TXT | The same clinical content without images, for pasting into a health record or an email. |
| JSON | The machine-readable record. Keep it alongside the PDF: it is the authoritative version, and it carries the app version and the parameters the analysis ran under. |
| A paper copy of the report. |
Auto-save PDF is off by default. Turn it on in Settings and a report is written at the end of every analysis. Everything is written locally. Nothing is synced, so moving a patient's records to another machine means moving the files yourself.
When is a scan saved to history?
- Automatically, as soon as the results screen finishes loading
- Only when you export a PDF
- Only when you press a Save button
- When the app closes
Saving is automatic. There is no save step to forget.
Which export is the authoritative, machine-readable record of an analysis?
- TXT
- The annotated PNG
- JSON
The JSON carries every value and the parameters the analysis ran under. Keep it alongside the PDF.
Best habits, limits & troubleshooting
A routine for every scan
- Enter the age as well as the name. It chooses the age band and the PLR reference ranges.
- Prepare the room: no overhead glare, and a distant point for the patient to look at.
- Capture OD, then OS, the same way: same device, distance and zoom.
- Read the confidence grade first. At D, recapture.
- Check for a reflection warning before you read the zone findings.
- Export the PDF and keep the JSON with it. The history record is already saved.
What this software is not
- Not a medical device. Every measurement, flag and report is observational and educational, not a diagnostic conclusion.
- Not validated against a reference instrument. There is no method-comparison study, no test–retest repeatability figure, and no sensitivity or specificity against a criterion standard yet.
- Millimetres are converted, not measured. The ratio is the measurement.
- Zone associations are a theoretical framework. The deviation is measured. Its meaning is a hypothesis.
- Texture measures are device-relative, and automatic detections are suggestions to confirm by eye.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The gate never turns green | Glare, blur or an off-centre eye | Read the message, change the angle, brace your hand. Use manual mode only if the lighting really is unusual. |
| An imported photo fails, or its P/I looks odd | The iris is too small in the frame | Crop tightly to the eye in the 4:3 crop step. Enlarging does not help. |
| P/I jumps between visits | Different framing or device | Standardise the capture before you read it as a change. |
| Confidence is low and the grade is D | A poor capture, or the two P/I values disagree | Recapture. Do not interpret the numbers. |
| A zone finding sits next to a reflection | Glare on the pupil border | Shift slightly to move the reflection, and recapture. |
| Dino-Lite not detected | Driver or connection | Install the DNVideoX driver, connect before launching, try another USB port. |
| PLR grade D or lower | Room too bright, eye movement, or the baseline was cut short | Dim the room, wait for the dark baseline, centre the eye, rest 30 seconds and record again. |
Tips from practice
- Question a finding that disagrees with what you see. Look at the capture and the fitted boundaries before you believe either one.
- Treat the timeline as data. It is only as reliable as your consistency from visit to visit.
- Use Mirror OD with Sync Pan in Visual Compare to scan both eyes for symmetry quickly.
- Annotate before you export. A saved PNG with the region circled explains a finding faster than a paragraph.
- Enhance, then Heatmap. CLAHE shows the structure, and the heatmap shows the pigment on top of it.
A patient's P/I rose 6 points since the last visit, which was captured with a different phone. What should you do first?
- Report a significant change
- Recapture with the original device and framing before reading it as a change
- Delete the older scan
- Average the two values
P/I depends on framing, so standardise the capture before you trust the difference.
Final exam
Twenty multiple-choice questions covering all seven modules. Answer every question, then submit to see your score and an explanation of each answer. You can retake the exam as often as you like, and your best score is kept in this browser.
This course teaches how to operate PupilMetrics Research. The zone associations it mentions are research-derived theoretical frameworks, not diagnostic claims. PupilMetrics Research is a research and educational tool, not a medical device.