Reference Align · Windows, macOS and Linux

Your photo, at the right scale and angle.

Use a known distance in a photo to size it in Onshape. Pick a second line to set its angle. You can use the same pair of points for both.

This guide opens without an internet connection. Connecting to Onshape needs the internet.

1. Extract and open

  1. Download the package for your computer. On a Mac, choose Apple Silicon for an M-series chip or Intel for an Intel processor; check Apple menu → About This Mac if unsure.
  2. Extract the whole ZIP. On Windows, right-click it and choose Extract All… → Extract. On macOS, double-click the ZIP. On Linux, use your archive manager’s Extract action.
  3. In the extracted folder, open START-REFERENCE-ALIGN.cmd (Windows), START-REFERENCE-ALIGN.command (macOS), or START-REFERENCE-ALIGN.sh (Linux). Keep the folder contents together. Run the launcher from this folder, not from inside the ZIP.
  4. Your browser opens Reference Align. Keep the small Reference Align app window open while you work; minimizing it is fine.

The browser page talks to the app on your own computer. Its address starts with http://127.0.0.1:. You do not need a website, a developer account for hosting, or any programming tools.

These packages do not have a trusted publisher signature. Read the launch help below if your computer blocks the app. No system security settings need to be turned off.

2. Connect your Onshape account once

The Connection panel opens on first use. Onshape requires an API key so this app can read and update your document; this account step cannot be skipped when writing to Onshape.

  1. Use the panel’s link to Onshape’s API keys page. Sign in with the account that can edit your document.
  2. Create a key. Enable Read documents and Write documents. Leave the other permissions off.
  3. Copy the access key and secret key into the matching boxes in Reference Align. Copy both before closing Onshape’s key dialog: the secret is shown only once.
  4. Press Test connection, then Save and continue.

The app saves the connection on this computer. You do not need to create or edit a credentials file. Keep the key private; do not put it in a screenshot or send it with a support request.

Choose Try an image without connecting to preview calibration with local images first. Writing to your Part Studio requires the connection.

3. Choose your document, photo and plane

  1. Open the intended Part Studio in Onshape and copy its address from the browser. Use the editable workspace, not a saved version.
  2. In Reference Align’s Document panel, paste the address and press Load this document.
  3. Press Load local image and choose your photo, then reopen Document from the rail (or top bar on a narrow window). If the photo is already an image tab in the document, reopen Document and choose that image instead.
  4. Choose the Plane: Top, Front, Right, your own plane, or the same plane as a sketch.
  5. Press Install into this document and confirm. The app uploads the chosen local image if needed and creates the calibrated reference feature.
  6. If the photo is not visible in the center, press Load selected Onshape image before picking points. This is needed when you chose an existing image tab instead of loading a local file.

If a calibrated reference already exists, select it under Target. Use Load selected Onshape image if the photo is not yet visible. You only need to install the feature once in that Part Studio.

No manual FeatureScript copying or right-panel extension setup is needed for this workflow. Keep Onshape and Reference Align open in separate browser tabs.

4. Scale, rotate, preview, apply

  1. Scale: pick S1 and S2 on two pixels whose real distance you know. Enter that distance and its unit.
  2. Rotation: open the Rotation section. Use S1 → S2, or turn that switch off and pick R1 and R2 along a line whose direction you know. Choose horizontal, vertical or the angle you want.
  3. Anchor: choose the point that should stay fixed while the image is calibrated.
  4. Press Preview calibration. Inspect the image and calculated values. Change the picks if needed, then preview again.
  5. Press Apply to Onshape and confirm. The feature updates in your Part Studio; the app saves a backup before changing it.

Changing the image’s plane clears the old preview. Preview again before applying calibration on its new plane.

If Onshape now shows the same photo twice, Reference Align may offer to hide the old image’s sketch. Suppression hides the whole sketch, including any other geometry in it; use it only when that is what you want.

If something gets in the way

Windows does not recognize the app

This build has no trusted signing certificate, so Windows may show “Windows protected your PC.” Only proceed if you trust the source you obtained it from. Where Windows permits it, More info → Run anyway opens an unsigned app. On a managed computer, ask your administrator if that option is unavailable.

A checksum can detect a changed download when compared with a value obtained from a trusted source. A ZIP and checksum supplied together by an unknown sender do not establish who made the app or whether it is safe. Do not disable antivirus to run it.

macOS blocks the launcher

Only proceed if you trust the download’s source. After trying to open START-REFERENCE-ALIGN.command, go to System Settings → Privacy & Security → Open Anyway if that option is offered, then confirm. This approves that app, not every downloaded app. See Apple’s official instructions. If the option is unavailable, ask your administrator or report the exact warning. Do not disable Gatekeeper or remove security protections.

Use the Apple Silicon package for an M-series Mac and the Intel package for an Intel Mac. Keep all extracted files beside the launcher, including any app and runtime folders supplied in your package; you do not need to install Node.

Linux opens the launcher as text or says permission denied

Right-click START-REFERENCE-ALIGN.sh, open Properties → Permissions, and allow this file to run as a program. Do the same for reference-align if necessary. Then choose Run or Run in Terminal for the launcher. Names vary by desktop; this changes only the extracted files, not system security settings.

The browser did not open, or the page stopped responding

Check that the Reference Align app window is still open. Copy the full local address printed there into your browser, including its port number. The app chooses another available local port if its normal one is occupied; use the address from this launch.

If you closed the app window, open your platform’s START-REFERENCE-ALIGN launcher again and use the new page. You can close both the browser tab and app window when finished.

The key test fails

Check that both complete strings are in the correct boxes and that you used the Onshape account that owns or can edit the document. If the secret was lost, create another key. The app’s message distinguishes a rejected key from a connection problem.

Install or Apply is unavailable

Read the reason beside the button. Install needs an image first. Apply needs a selected calibrated feature and a current preview. A saved-version link is read-only; paste the Part Studio’s workspace address instead.

Open Settings in the rail if an action is switched off. On a narrow window, Connection, Document and Settings are in the top bar.

My plane or sketch is unavailable

A plane or sketch used by an existing reference image must occur before that image in the feature list. Move the feature to a valid position in Onshape, then refresh the Document panel. A plane that cannot be resolved also shows a reason.