Orienta 0.4.7

Orienta 0.4.7

This release fixes an error in "BG Static" that imprinted the bands of one pattern on every pattern of the scan, a detector-geometry error that appears with kikuchipy 0.12 and newer, the atom positions Hough indexing read for silicon and MgCu₂, the symmetry used for monoclinic phases, the .ang and .ctf exports, and several settings that had no effect. It adds control over the Hough reflector list, pattern-centre refinement with several phases, and adding a phase by its file path. The installers move to kikuchipy 0.13.1, orix 0.15.0 and PyEBSDIndex 0.3.10.1.

The open points of the Phase Library page that v0.4.6 planned for this release (groups, keyboard use and some panels) are not part of it; they are planned for a later release.

What was fixed

Area	What went wrong	Fix
BG Static in the EBSD viewer, the first step of the recommended pipeline, and batch processing with static background removal (Hough, Dictionary)	The pattern at scan position (0, 0) was used as the background and subtracted from every pattern, so its bands were imprinted on all patterns. "BG Dynamic" was not affected.	The average of all patterns of the scan is subtracted. For large, lazily loaded files it is computed block by block from the file, with a progress bar, and cached for the dataset. A static background stored in the file is not used, because for Oxford files the loaded patterns are already processed by the acquisition software, and the stored background belongs to the unprocessed ones.
Detector distance with kikuchipy 0.12 or newer (Oxford files)	The newer Oxford reader reports the camera binning, and Orienta applied it a second time to a pixel size that was already per binned pixel. The detector distance came out too large by the binning factor (8× for 156×128 px modes). This affected spherical indexing (the built-in GPU indexer and EMSphInx) and the pattern-simulation tools; Hough and dictionary indexing were not affected. With the kikuchipy 0.11.3 that the v0.4.6 installers ship, only Oxford files whose header contains Camera Binning Mode could be affected.	Pixel size and binning are now combined in one place, and kikuchipy 0.11.3 and 0.13.1 give the same detector geometry. When an exported result with the doubled geometry is imported, its geometry is corrected for the pattern-simulation tools where this is unambiguous (otherwise the log reports it). Its stored orientations are not changed; re-index affected results.
Hough indexing with silicon or MgCu₂ (any CIF of the 24 two-origin space groups written in origin choice 2)	The CIF reader that Hough uses expanded the atoms with the operators of origin choice 1, whatever the file was written in: silicon came out with 16 atoms in the cell instead of 8, MgCu₂ as Mg32Cu8 instead of Mg8Cu16. For silicon the reflector list then held the diamond-forbidden {222} and lacked {220} and {224}.	Hough reads these files with their origin choice, as the simulation path does since v0.4.6; a file whose origin choice cannot be decided is refused with a message (a non-standard setting named only by its symbol is read with a warning). Of the 36 CIF files we checked, only silicon and MgCu₂ were affected.
Monoclinic phases with unique axis b (for example Al13Fe4, β-AlFeSi)	The symmetry used to compare orientations had the two-fold axis along z, while it lies along y in Orienta's crystal frame (x ∥ a, z ∥ c*). Two orientations related by the real two-fold axis were treated as 180° apart: pixels of one grain could be split into different grains, boundaries could be drawn inside a grain, KAM could leave out neighbours, and IPF colours differed within a grain. Stored orientations from spherical and Hough indexing are not affected (for Hough this follows from the code and was not measured); the orientation grid of dictionary indexing did not cover every orientation of these phases, so dictionary results can hold wrong orientations.	Grain reconstruction, KAM, grain boundaries, IPF colours, pole figures and the dictionary orientation grid use the real two-fold axis, and the default Hough reflector list is expanded with it (Hough results may differ; the size of the change was not measured). Phases with unique axis c and all other crystal systems are unchanged. That the spherical indexer stores orientations in this frame was checked with patterns rendered from the Al13Fe4 master; the corrected calculations were checked on synthetic orientation maps. Nothing has yet been compared on a measured Al13Fe4 map. Re-index dictionary results of these phases.
Settings on the PC refinement page	Minimum d-spacing, structure-factor threshold, maximum reflectors and number of bands were shown but never reached the indexer.	The first three are replaced by the per-phase reflector-family table, and the number of bands is applied.
Kikuchi-line overlay in PC refinement after picking a pattern from the list	The pattern image was delivered at the size of a rendered figure (914×750 pixels for a 156×128 pattern), while the lines are in pattern pixels, so the lines were drawn shrunk into the top-left corner.	The pattern image is delivered at its own pixel size.
"Global CI" in PC refinement	After a global PC refinement the badge showed the CI of a single calibration pattern, and it could disagree with the value reported after "Index All".	Global CI is the mean CI over all calibration patterns, each with its winning phase, indexed at the current pattern centre; a refinement re-indexes all of them at the refined pattern centre. After a manual change of the pattern centre it shows N/A until the patterns are indexed again.
Kikuchi-line overlay in PC refinement for some phases (observed for MgZn2 and π-Al8FeMg3Si6)	The phase's structure was modified on every call, so the overlay reflectors changed from the second pattern on.	The structure is copied before use, and the reflector list is computed once per phase.
EDAX UP1/UP2 files on a hexagonal grid	They were read as if the grid were square, giving a single row or a distorted map with at most a warning.	They are refused with an error when the version-3 header or the .osc file shows a hexagonal grid. A version-1 file without its .osc cannot be checked; keep the .osc next to it, or export hexagonal scans as H5, which Orienta resamples. Detection was tested with synthetic headers only.
Connection between page and backend	A connection that had silently died was not detected, and after reconnecting the page did not re-read its state.	The page detects a dead connection, reconnects with increasing wait times, and re-reads its state afterwards.
.ang export	Results whose map was kept on the pixel grid (seen for spherical indexing and for Hough indexing with the EDS chemistry prior) were written with a step of 1.0 and x/y in pixels, so lengths and areas were wrong by the step size and its square. Lattice constants were written as 1.000 for spherical results and in batch exports, and for monoclinic phases the symmetry field held 112, which is not a TSL code.	Step and coordinates in micrometres; a cropped map starts at 0 and its origin is in the header. Lattice constants from the phase's structure, CIF or master file; the export stops with a message if none is known. TSL code 20 for monoclinic phases with unique axis b. The header states the reference frame, the scan geometry (for Oxford sources) and the phase-assignment method. Re-export affected files.
Batch .ctf export	For scans from Oxford systems the Euler angles were written in the EDAX TSL frame although .ctf is an Oxford format, so φ1 differed by 90° from the source system's own angles and from the light .h5. Lattice constants were written as 1.000.	Written in the frame of the source file, the same angles as in the light .h5, with the lattice constants of the phase's structure, CIF or master file. Scans from EDAX systems keep the EDAX frame, which is their own. Re-export affected files.
Repeated or batch .ang export	Exporting over an existing file failed or kept the old file; batch files wrote Bruker pattern-centre values under the TSL names.	Overwriting works; the pattern centre is written in the TSL convention (or left at zero, with a note, when the detector size is not known).
Hough indexing from a source installation with pyopencl	PyEBSDIndex rebuilt its OpenCL kernels on every indexing call, and their memory was not freed (about 250 MB per call); after about 55 calls in one session Hough indexing failed with an OpenCL out-of-memory error until the app was restarted (measured on one GPU and driver under Windows; the number depends on the machine). The installers use the CPU band detector and were not affected.	Orienta reuses one OpenCL context per GPU for these calls. In a loop of 300 calls, each building an indexer and indexing 8 patterns, memory stayed constant; before the fix the same loop failed at call 56. Results are unchanged.
start_app.py with port 8000 already in use	It started anyway and attached to whatever answered on that port, which could be an old backend it could not stop.	It refuses to start and explains how to find the process that holds the port.
Group headings in the phase picker	"Pure elements" and "Other" were shown in German in every language.	Translated into all four interface languages.

What is new

Feature	What it does
Hough reflector families	On the Indexing and PC refinement pages, each phase has a table of its reflector families with d-spacing, relative structure factor and multiplicity. It shows which families PyEBSDIndex actually uses. You can untick families, add a family, keep the strongest N, or reset to the default. Without a selection the default reflector list is used, so the table ch...

Orienta 0.4.6

Orienta 0.4.6

Orienta can now be installed on Windows, macOS (Apple Silicon) and Linux without installing Python or git yourself. This release also adds add-ons, a citation panel for every result, per-particle EDS export and a new phase library page. The full list of changes is in the changelog.

If you built master patterns with an earlier version, or index silicon or MgCu₂ with Hough, please read this.

CIFs in space groups with two origin choices (for example silicon or MgCu₂). In the 24 space groups with two origin choices, atoms could land on the wrong orbit during conversion. Silicon came out with 16 instead of 8 atoms per unit cell, and MgCu₂ as Mg32Cu8 instead of Mg8Cu16. Master patterns built from such a structure are wrong throughout. Conversion and reading for master-pattern simulation are fixed, but files made with an earlier version keep the error: convert the CIF again; delete the Monte-Carlo file, the master pattern and any saved dictionary built from that structure; simulate them again; and index maps made with Dictionary or Spherical indexing again. Orienta now writes a warning to its log when it reads a .xtal file whose origin setting cannot be verified.

Hough indexing reads the CIF directly, through a separate reader that this fix does not cover: it still expands silicon to 16 atoms and MgCu₂ to Mg32Cu8. How much this changes Hough results has not been measured; treat Hough results on phases in these 24 space groups with caution and, where a master pattern exists, compare them with a Dictionary or Spherical run.

The changelog archived with this version, and an earlier version of these notes, also name Al₃Fe₂Si as affected. It was re-checked and is not affected: the converted structure has the atom count and density of its CIF.

Masters from Orienta Engine in 15 space groups. .sht master patterns built with Orienta Engine (the built-in simulator) in an earlier version carry a wrong symmetry number for 15 space groups, including Pm-3m (221), P-43m (215), P432 (207), P23 (195), P4/mmm (123) and P6/mmm (191). Build them again and re-index maps made with Spherical indexing that used them. Masters simulated with EMsoft are not affected.

What's new

• Installers for all three systems. Each package sets up its own private Python on first start. Your measurement files stay where they are; Orienta only reads them.
• Add-ons. Another group's analysis can run inside Orienta and its results can be shown as a layer on the phase map. Nothing runs until you allow it. An add-on is Python code: once allowed, it runs with your permissions, so install add-ons only from sources you trust. Add-ons live in ~/.orienta/addons; a worked example ships with the program.
• Citations for every result. Phase Maps → Citations gives a BibTeX file, a methods paragraph and a reference list for the method you actually ran, and they travel with the exported file.
• EDS export per particle (size, shape, composition), saved presets and a plausibility report.
• Phase library. A page showing what is in your crystal library: formula, space group, elements and which indexing methods each phase supports. You can search it, give phases your own names and synonyms, and sort phases into groups. Open points around groups, keyboard use and some panels are planned for 0.4.7. Nothing on this page deletes or moves a crystal file.
• Spherical indexing is now used directly for cubic m-3/23 and orthorhombic mmm phases, without the earlier detour through Hough.

Downloads

System	File	Requirements
Windows	Orienta.Setup.0.4.6.exe	64-bit; 2.5 GB free, 9 GB with NVIDIA GPU packages
macOS	Orienta-0.4.6-arm64.dmg	Apple Silicon (M1 or newer), macOS 14 or later; 12 GB free
Linux	Orienta-0.4.6.AppImage	x86-64; 2.5 GB free, 9 GB with NVIDIA GPU packages

On first start the setup downloads Python and the required packages. orienta-runtime-v0.4.6.zip is the program package the installers use; you do not need to download it.

SHA-256 checksums (each file also has a .sha256 next to it):

b53e6871406b2c59af86d4d6ead3ee98cbc7d2a50f7a7e7da573eca410a8717a  Orienta.Setup.0.4.6.exe
7e9ebb173916f20e4597f04480fcc00d78c6e579b31228d81698a563200d6837  Orienta-0.4.6-arm64.dmg
896574f948a41e782a9635c3383f2933064c5f512730c95e5fee2070a1dd41dd  Orienta-0.4.6.AppImage
d03e64160f6008ddced22d7bfa4f7396853605dcd705e97a6d0fe8b5989e149e  orienta-runtime-v0.4.6.zip

To check a download:

Windows   certutil -hashfile Orienta.Setup.0.4.6.exe SHA256
macOS     shasum -a 256 Orienta-0.4.6-arm64.dmg
Linux     sha256sum Orienta-0.4.6.AppImage

First start

The Windows installer is not signed, and the macOS app is signed without a paid Apple certificate, so both systems ask once before the first start.

• Windows: "Windows protected your PC" → More info → Run anyway.
• macOS: drag Orienta into Applications. On macOS 15 and later, double-click it once; macOS says it cannot verify Orienta; click Done, then open System Settings → Privacy & Security, scroll down to the message about Orienta, click Open Anyway and confirm. On macOS 14, right-click Orienta → Open and confirm with Open.
• Linux: make the file executable first (chmod +x Orienta-0.4.6.AppImage); without that, it will not start from a double-click. Ubuntu 22.04 and newer do not install FUSE 2 by default, and this AppImage needs it. Either install it once (sudo apt install libfuse2 on 22.04, sudo apt install libfuse2t64 on 24.04 and newer), or start with ./Orienta-0.4.6.AppImage --appimage-extract-and-run.

Platform differences

• EMsoft simulations are available on Windows only, because Orienta runs EMsoft through WSL. Orienta Engine, the built-in simulator, runs on all three systems.
• GPU acceleration requires an NVIDIA graphics card (Windows or Linux). On a Mac, Orienta computes on the processor.

Updating

Installed with an installer: from this version on, Settings → About Orienta → Check for updates tells you when a newer version is published. On Windows, run the new installer over the existing installation; there is no need to uninstall first. On macOS, replace Orienta in Applications with the new version; on Linux, replace the AppImage. On all three systems the data folder (including the crystal library) and the settings live outside the program and are kept.

Installed from a git clone: the update is offered inside the app, as before; see the update guide.

Unzipped from a downloaded archive, or an installer test build before 0.4.6: these cannot update themselves; download the new version from this page.

If you tested a pre-release build of 0.4.6 and share a database folder between computers, update all of them: a phase group edited with this version cannot be read by an earlier test build.

How to cite

To cite Orienta in general, use the concept DOI, which always points to the latest version: 10.5281/zenodo.22664080

To cite this exact version: 10.5281/zenodo.23006390

To build from source instead, see INSTALL.md.

Orienta v0.2.6 — first public release

The first release of Orienta as a public repository. Nothing in the application behaves differently from v0.2.5 — this release is about what the project says about itself, because from here on an archived copy carries a DOI that people will cite.

The README now matches the code. An audit compared every claim against what is actually wired up. "texture/ODF" was overstated (the index and entropy come from texture-component volume-fraction bins, not from an ODF), the spherical default is the built-in GPU indexer rather than EMSphInx, EDAX hexagonal-grid scans open sheared instead of being refused, and the status line was too pessimistic about ML and refinement. There is now a Known limitations section that carries these and the rest.

Attribution that was missing. EMsoft and SHTfile are credited with their licence texts under licenses/ — three files transcribe tables and coefficients from them, and both are BSD-3-Clause, which requires the notice to travel with the source. three.js is listed as redistributed rather than as an external dependency, and vanta.js now has the copyright notice MIT requires beside it.

The Materials Project key no longer lives in the source. It comes from your own settings, with MP_API_KEY as a fallback. If you used the database builder's online lookup, enter your own key under Settings → API keys.

See CHANGELOG.md for the full entry.

---

Requires Python 3.11 and Node.js 20.19+ to build the interface. Read the Known limitations section in the README before relying on a result.

Orienta v0.2.3

How to get it

If you installed Orienta by cloning the repository, open the app and it will
offer this update itself (or Settings → About Orienta → Check for updates).

This release fixes a crash that made the Phase Maps page unusable in
v0.2.0-v0.2.2. If you use that page, please update.

---

v0.2.3 — 2026-08-27

Fixes for four things users reported, three of which read as "it just does
nothing".

• The Phase Maps page crashed every time it was opened. It has been
  unusable since v0.2.0 — three separate reports were this one fault.
• Detector width no longer starts at an impossible value. It was preset to
  0.1 mm, which is not a detector at any pattern size; that value quietly
  skewed the pattern centre and everything computed from it. It is now read
  from the measurement file, and where the file does not carry it, estimated
  and clearly labelled as an estimate. A value no real detector could have is
  now called out — this matters because a wrong detector geometry leaves the
  maps looking perfectly correct.
• Choosing a map layer now shows that layer. Until now the map only
  reloaded when you pressed "Refresh", so picking "Grain boundaries" appeared
  to do nothing at all. When a layer cannot be drawn yet, the reason is shown
  as a warning instead of a quiet status line.
• IPF maps no longer offer a colormap. IPF colours are a fixed code for
  crystal directions, not a value range; the setting never had any effect on
  them and only suggested otherwise. Colormaps remain where they belong, on
  Band Contrast, KAM, GOS and the other scalar maps.
• The status bar shows the grid size as "150×201" again, instead of the
  raw escape sequence it had been printing.
• "Load CIF" no longer fails in browser mode.

Orienta v0.2.2

How to get it

If you installed Orienta by cloning the repository, open the app and it will
offer this update itself (or Settings → About Orienta → Check for updates).

An installation unpacked from a ZIP has no link back to the repository and
therefore cannot update itself. Clone the repository instead if you want
automatic updates.

---

v0.2.2 — 2026-08-27

Problem reports become easier to file and easier for us to act on.

• "⚠ Report a problem" is now in the toolbar at the top of every page. You
  no longer have to leave the page where something went wrong in order to
  report it — which also means the record of what happened is more complete.
• A picture of the window is included automatically (desktop app only),
  taken the moment you open the dialog, so you no longer need to make a
  screenshot yourself. You can leave it out if the screen shows something you
  would rather not share.
• Every report carries a short error id. The same fault produces the same
  id on every machine, so if two people run into one problem it is visible as
  one problem instead of two unrelated reports. It is shown in the dialog and
  written into the report.
• "Open a GitHub issue" opens a new issue with your description, the
  version, the error id and the preceding events already filled in — you only
  drag the report file into it. (GitHub does not allow programs to attach
  files to an issue, so that last step stays manual.)

Orienta v0.2.1

How to get it

If you installed Orienta by cloning the repository, you do not need this page:
open Orienta, and it will offer the update itself (Settings → About Orienta →
Check for updates, if you would rather not wait).

If you are still on v0.1.0, update once by hand — git pull and then
git checkout v0.2.1 in the Orienta folder — after that it updates itself.

A note on the source archives below: an installation unpacked from a ZIP
has no link back to the repository and therefore cannot update itself.
Clone the repository instead if you want automatic updates.

---

v0.2.1 — 2026-08-27

Fixes to the update check itself, found by running it against a real
installation.

• Says when it cannot sign in. A private repository answers "not found"
  rather than "access denied" when credentials are missing, so the check used
  to report "server unreachable" and send you looking for a network problem.
  It now tells you to sign in once instead.
• The check never opens a credential window on its own. It runs in the
  background at start-up, where a prompt nobody asked for would either hang or
  appear out of nowhere.
• "Check for updates" now says what it found — up to date, not signed in,
  or unreachable — instead of only ever reporting "up to date".
• Release notes with dashes and umlauts are no longer garbled on Windows.

---

v0.2.0 — 2026-08-27

The first release since v0.1.0, and a large one: 164 changes. The headline
items are a rebuilt EDS phase map, cropping a scan to a selection, and a
one-click problem report.

Staying up to date

• Orienta now checks for a new release when it starts and offers to install
  it: it fetches the new version, installs any changed packages, rebuilds the
  interface and restarts. If any step fails, your working version stays exactly
  as it was.
• Only released versions are offered, never work in progress.
• You can skip a version, postpone the question, or switch the check off
  entirely under Settings → About Orienta.
• Installations set up from a downloaded archive (rather than a git clone)
  cannot update themselves; they are told so, with instructions, instead of
  being offered a button that cannot work.

Reporting problems

• Every install now has a version. Settings → About Orienta shows it;
  quote it in bug reports.
• "Report a problem…" in Settings and on the crash screen packages your
  description, the app version, environment details and the log files into one
  zip to attach. It contains no measurement data and is never sent
  automatically. See the guide.
• Orienta now keeps log files (logs/), so the cause of a failure survives
  closing the window — including crashes that happen before the interface even
  appears.

EDS phase map

• The map is grouped into regions by chemistry first, and phases are
  assigned to those regions afterwards — instead of deciding pixel by pixel.
  Regions can be merged, split, grown, shrunk and snapped to chemical edges.
• Region inspector below the map: full composition with spread, enrichment
  against the map background, neighbours, and candidate phases with their
  deviation.
• Magic-wand selection — click a feature to select all of it, with live
  preview, a readout of what is selected, undo, and map-wide phase replacement.
• Rules that decide which phases may compete for a region (e.g. "silicon at
  least twice the background"), so ambiguous EDS signals stop pulling the wrong
  phase in.
• Phase colours you pick, shared with the EBSD phase map, and an overview
  that folds many regions into few phases.
• The phase map has its own tab, can be zoomed with the scroll wheel,
  overlaid on an element map or the SEM image, and exported by right-click.
• EDS-only files (Aztec element-distribution exports without EBSD data) now
  open directly on the EDS page.

Cropping a scan

• Crop to a rectangle, ellipse or lasso selection in the EBSD viewer —
  patterns, EDS maps, band contrast and per-pixel data all follow, without loss.
• Export the crop as a standalone file (a 546 MB source became a 42 MB file
  in testing, patterns bit-identical).
• Indexing, including batch runs, honours a non-rectangular selection.
• Electron images follow the crop window through their own micrometre geometry.

Indexing & phase identification

• Render-verified phase check and grain reassignment — find and correct
  regions where a phase was assigned that the pattern does not support.
• Pseudo-symmetry tools: map-wide variant unification, grain flip with coset
  snap and undo, a variant gallery with neighbour-grain and reference-pixel
  candidates.
• Grain-stabilised IPF colouring removes the speckle caused by colour-key
  discontinuities, and IPF maps can be filtered to a single phase.
• EDAX .up1/.up2 and .osc files can be loaded.
• Hough indexing works for CIFs written in a non-standard space-group setting
  (previously it tried to allocate over a terabyte and failed).
• Spherical indexing falls back to the CPU on machines without an NVIDIA GPU
  instead of crashing.
• Indexing speed is reported as patterns/second for all three methods, so
  they can be compared.

Maps, images and export

• Image export everywhere — right-click a pattern, map or preview for a
  dialog with crop, resolution, format, border, scale bar and caption.
• Scale bars and colour keys are movable objects in the exported figure,
  not fixed columns.
• Grain boundaries as a map layer, classified by misorientation into three
  freely adjustable bands.
• Layer picker with search that only offers layers which can actually be
  drawn, and says what is missing for the rest.
• Value-scale legends for every layer whose colours mean a number.
• 3D crystal-structure viewer for CIF and XTAL files in the database browser.

Fixes worth knowing about

• Closing the app now really stops the backend. A surviving backend used to
  hold port 8000 and, after a drive was unplugged, served dead file handles —
  every file load then failed with a cryptic error.
• Band contrast comes from a single service with a clear order of preference
  (native → stored → computed) and is named accordingly, instead of silently
  substituting a different measure.
• Saved results re-import with the geometry they were computed with, so a
  pattern match after reloading matches again.
• Batch indexing with Hough or Dictionary no longer crashes at startup.

New in the interface

• New wordmark, logo and favicon.
• The About section carries the licence notice, the version and the problem
  report button.

Main

Initial beta release. Source + 4 example phases are in the repository; the 3 example EBSD datasets are attached below — download them into sample_data/patterns/. Archived release: https://doi.org/10.5281/zenodo.21021938