AlignRef2 Web beta — Quick Start Guide

Start with the demo

AlignRef2 aligns serial images, such as histological sections, using translation and rotation. Automatic registration, visual review, manual correction, common cropping and export are available in one browser workflow. The original AlignRef + MultiStackReg instructions remain available as the Legacy workflow.

Launch AlignRef2 →

Public URL: https://satorumuro.github.io/AlignRef/

Select Load images → Try demo dataset to load 132 mouse-brain sections without supplying your own files. About 9.84 MB is downloaded when you click. The demo has not been pre-registered by AlignRef2.

Basic workflow

1. Load your images

   Use Choose images for multiple files or Choose folder for a directory. Prepare one file per section. Filenames are sorted naturally: image1, image2, image10. Loading another stack replaces the current work, so save first.

2. Check the order and canvas

   Check Slice and the filename above the viewer. Press F for next or R for previous, or use the mouse wheel over the viewer. Fit to Window shows the whole image. Different image sizes are centered on a common canvas using the largest width and height, without scaling the source images. Set padding to White or Black with Canvas background.

3. Run automatic registration

   Under Automatic registration, choose Channel: Gray, Red, Green or Blue. Gray and the default Proxy limit of 768 are a starting point. Proxy limit sets the longest side of the reduced image used for computation; it does not reduce export dimensions.

   For Reference, Middle slice uses the middle image; Current slice uses the image you are viewing. Select Run Rigid Registration. Adjacent pairs are aligned outward from the reference across the entire loaded stack. Set Position Start / End do not limit automatic registration.

4. Review every result

   Use Previous image overlay or Next image overlay, adjust Overlay opacity, or turn on Flicker to alternate images. Read Registration warnings. A high correlation score does not establish anatomical correspondence. Missing tissue, low contrast, large shifts and changes in shape may require correction.

5. Record and apply a manual correction

   Go to a section to use for the correction, show a neighboring overlay and select Start Recording Position. Use W A S D to move by 1 px and Q E to rotate by 0.1°. Hold Shift for ten times the step. Slice navigation is locked while recording.

   Select Finish Recording Position to store the correction. This removes the preview without applying it. Set Set Position Start and Set Position End as described below, check the range, then select Apply Position & Rotation once. Use Undo last change (Ctrl+Z) to undo an application. Cancel Recording discards a recording preview.

6. Crop if needed

   Select Start Crop and drag a rectangle in the viewer. Drag inside to move it or drag a corner to resize it. Apply Crop sets a common output region for every image; Undo Crop restores the previous region. Clear Crop Box removes only the pending selection. To add space, use Expand Canvas +100 px each side.

7. Save images and settings

   Choose PNG (default) or JPEG under Format. Export to folder creates a new subfolder in the location you select. For small stacks, use Download ZIP (small stacks); the encoded image files are limited to 256 MB in total. Both export 8-bit images and transforms.json.

   Save transforms.json saves transform settings only, not source images. To resume, load the same original images in the same order, then select Load transforms.json. Image count and individual dimensions must match. Transforms map by order, not by filename. Save before closing or reloading the page.

Start / End define the manual correction range

The endpoints select which sections receive the same recorded translation and rotation. Slice numbers start at 1 and are distinct from numbers in filenames.

1. After Finish Recording Position, both endpoints are set to the current slice.
2. Go to the first desired section and select Set Position Start.
3. Go to the last desired section and select Set Position End.
4. Check the values and checkmarks under Position range, and the Apply to slices … message, before applying.

Unset values appear as “—”. Setting an endpoint briefly shows its slice number in the status message and marks the button. Reversed endpoints retain their entered order: Start: 72 / End: 34 displays the application range 34–72 and Start > End.

Each additional click on Apply adds the correction again. Undo an accidental application. Re-running automatic registration replaces the automatic transforms but retains applied manual corrections, so review the combined result afterward.

Keyboard & mouse

Slice navigation is suppressed while editing input fields, menus or sliders. If shortcuts or wheel navigation do not respond, finish the active operation or recording, then click the viewer. Wheel events outside the viewer scroll normally. Navigation buttons and the Slice number field are also available.

Supported formats and 16-bit TIFF

No automatic contrast stretching is applied. Images occupying only a small part of the 16-bit range may appear dark. Preserving 16-bit precision, TIFF export and round-trip retention of physical pixel spacing or ICC/EXIF metadata are not implemented. Keep your original images separately.

Your images stay on your device

Images you load are processed locally in your browser and are not uploaded to any server. Loading, alignment and preparation of exports run in the browser.

The application code is downloaded from this site. Try demo dataset downloads public images from the AlignRef site when clicked. These requests do not upload your local images. External source links open only when you follow them.

Troubleshooting

A TIFF will not open

Read the filename and error, and check the supported subset above. Export multi-page or tiled TIFFs as supported single-page, strip-based files before loading. A failed load leaves the previous stack intact.

Image sizes differ or padding appears

Images are centered on a canvas with the maximum width and height, without resizing. Check the background color and crop to a common region if needed. Physical pixel sizes are not automatically harmonized.

A large stack is slow or the browser is heavy

Try a small subset first and close unused tabs. A smaller Proxy limit reduces computation, but inspect the resulting alignment. Prefer Export to folder for large outputs. Each TIFF decode times out after 60 seconds. The canvas limit is 32,767 px per side and 100 MP; device memory may impose a lower practical limit.

Start / End show unexpected values

Finish Recording Position sets both endpoints to the current slice, so choose the range after finishing. Check Slice and the filename before setting each endpoint, and read the range again before Apply.

Alignment looks wrong or reports warnings

Inspect every section with overlays and manually correct the necessary range. Registration does not repair tissue deformation or missing content. A failed adjacent pair inherits the preceding automatic transform and is flagged; inspect downstream sections as well.

Saving, cancelling and resuming

If folder export is unavailable, use ZIP for a small stack. Cancel stops an active operation, but files already written to an export folder remain there. Work is not automatically restored after a reload. Save exported images and transforms.json.

Credits & licenses

Software code is licensed under Apache-2.0. Demo images are separately licensed under CC BY-SA 4.0.

The demo is derived from subj03 of the Mouse Brain Architecture Project / Brain Architecture Project (BAP). The license basis is the BAP Policy. The source files were obtained from the JHU-hosted distribution of the Mouse Brain Architecture Project subj03 dataset. JHU is the source host.

Demo preparation retained odd-numbered sections, used a common canvas and converted images to JPEG. The 132 supplied JPEGs are distributed unchanged. When sharing demo images or adaptations, retain BAP attribution, source/license links and a description of additional changes, and share adaptations under CC BY-SA 4.0. DATA_LICENSE.md is included with demo image exports. No BAP/JHU endorsement is implied.

Related publication and citation · Technical details and limitations