# API reference¶

This reference manual details the public modules, classes, and functions in orix, as generated from their docstrings. Many of the docstrings contain examples, however, see the user guide and the demos for how to use orix.

Caution

orix is in an alpha stage, so there will be breaking changes with each release.

The list of top modules:

 base Base class for 3d objects. crystal_map Crystallographic map of rotations, crystal phases and key properties associated with every spatial coordinate in a 1D, 2D or 3D space. io Load and save utilities. plot Extensions of Matplotlib's projections framework for plotting Vector3d, Rotation, Orientation, Misorientation, and CrystalMap. projections Projections of orix.vector.Vector3d to various other representations. quaternion Four-dimensional objects. sampling Generation of grids on S2 or SO(3) (rotation space). scalar Dimensionless quantities. vector Three-dimensional quantities.

## base¶

Base class for 3d objects.

Note that this class is not meant to be used directly.

exception orix.base.DimensionError(this, data)
class orix.base.Object3d(data=None)

Base class for 3d objects.

property data_dim

The dimensions of the data.

For example, if data has shape (4, 5, 6), data_dim is 3.

Notes

Deprecated since version 0.8: Property data_dim is deprecated and will be removed in version 0.9. Use ndim instead.

Type

[Deprecated] int

dim = None

The number of dimensions for this object.

Type

int

classmethod empty()

An empty object with the appropriate dimensions.

flatten()

Returns a new object with the same data in a single column.

get_random_sample(size=1, replace=False, shuffle=False)

Return a random sample of a given size in a flattened instance.

Parameters
Returns

New, flattened instance of a given size with elements drawn randomly from this instance.

Return type

new

property ndim

The number of navigation dimensions of the instance.

For example, if data has shape (4, 5, 6), data_dim is 3.

Type

int

reshape(*shape)

Returns a new object containing the same data with a new shape.

property shape

Shape of the object.

Type

tuple

property size

Total number of entries in this object.

Type

int

squeeze()

Returns a new object with length one dimensions removed.

transpose(*axes)

Returns a new object containing the same data transposed.

If ndim is originally 2, then order may be undefined. In this case the first two dimensions will be transposed.

Parameters

axes (int, optional) – The transposed axes order. Only navigation axes need to be defined. May be undefined if self only contains two navigation dimensions.

Returns

A transposed instance of the object.

Return type

obj

unique(return_index=False, return_inverse=False)

Returns a new object containing only this object’s unique entries.

Unless overridden, this method returns the numerically unique entries. Also removes zero entries which are assumed to be degenerate.

Parameters
• return_index (bool, optional) – If True, will also return the indices of the (flattened) data where the unique entries were found.

• return_inverse (bool, optional) – If True, will also return the indices to reconstruct the (flattened) data from the unique data.

Returns

• dat (Object3d) – The numerically unique entries.

• idx (numpy.ndarray, optional) – The indices of the unique data in the (flattened) array.

• inv (numpy.ndarray, optional) – The indices of the (flattened) data in the unique array.

## crystal_map¶

Crystallographic map of rotations, crystal phases and key properties associated with every spatial coordinate in a 1D, 2D or 3D space.

All map properties with a value in each data point are stored as 1D arrays.

 CrystalMap(rotations[, phase_id, x, y, z, ...]) Crystallographic map of rotations, crystal phases and key properties associated with every spatial coordinate in a 1D, 2D or 3D space. CrystalMapProperties(dictionary, id[, ...]) A class to store properties with in a CrystalMap instance. Phase([name, space_group, point_group, ...]) Name, symmetry, and color of a phase in a crystallographic map. PhaseList([phases, names, space_groups, ...]) A list of phases in a crystallographic map. create_coordinate_arrays([shape, step_sizes]) Create flattened coordinate arrays from a given map shape and step sizes, suitable for initializing a orix.crystal_map.CrystalMap.

### Phase¶

 Return a deep copy using deepcopy() function.
class orix.crystal_map.Phase(name=None, space_group=None, point_group=None, structure=None, color=None)

Name, symmetry, and color of a phase in a crystallographic map.

__init__(name=None, space_group=None, point_group=None, structure=None, color=None)
Parameters
• name (str, optional) – Phase name. Overwrites the name in the structure object.

• space_group (int or diffpy.structure.spacegroups.SpaceGroup, optional) – Space group describing the symmetry operations resulting from associating the point group with a Bravais lattice, according to the International Tables of Crystallography. If None is passed (default), it is set to None.

• point_group (str or orix.quaternion.symmetry.Symmetry, optional) – Point group describing the symmetry operations of the phase’s crystal structure, according to the International Tables of Crystallography. If None is passed (default) and space_group is None, it set to None. If None is passed but space_group is not None, it is derived from the space group. If both point_group and space_group is not None, the space group needs to be derived from the point group.

• structure (diffpy.structure.Structure, optional) – Unit cell with atoms and a lattice. If None is passed (default), a default diffpy.structure.Structure object is created.

• color (str, optional) – Phase color. If None is passed (default), it is set to ‘tab:blue’ (first among the default Matplotlib colors).

Examples

>>> from diffpy.structure import Atom, Lattice, Structure
>>> from orix.crystal_map import Phase
>>> p = Phase(
...     name="al",
...     space_group=225,
...     structure=Structure(
...         atoms=[Atom("al", [0, 0, 0])],
...         lattice=Lattice(0.405, 0.405, 0.405, 90, 90, 90)
...     )
... )
>>> p
<name: al. space group: Fm-3m. point group: m-3m. proper point         ... group: 432. color: tab:blue>
>>> p.structure
[al   0.000000 0.000000 0.000000 1.0000]
>>> p.structure.lattice
Lattice(a=0.405, b=0.405, c=0.405, alpha=90, beta=90, gamma=90)

property color

Name of phase color.

property color_rgb

Phase color as RGB tuple.

deepcopy()

Return a deep copy using deepcopy() function.

property is_hexagonal

Whether the crystal structure is hexagonal/trigonal or not.

property name

Phase name.

property point_group

Point group of phase.

property space_group

Space group of phase.

property structure

Phase unit cell.

### PhaseList¶

 add(value) Add phases to the end of a phase list, incrementing the phase IDs. Return a deep copy using copy.deepcopy() function. id_from_name(name) Get phase ID from phase name. Sort list according to phase ID.
class orix.crystal_map.PhaseList(phases=None, names=None, space_groups=None, point_groups=None, colors=None, ids=None, structures=None)

A list of phases in a crystallographic map.

Each phase in the list must have a unique phase id and name.

__init__(phases=None, names=None, space_groups=None, point_groups=None, colors=None, ids=None, structures=None)
Parameters
• phases (orix.crystal_map.Phase, a list of orix.crystal_map.Phase or a dictionary of orix.crystal_map.Phase, optional) – A list or dict of phases or a single phase. The other arguments are ignored if this is passed.

• names (str or list of str, optional) – Phase names. Overwrites the names in the structure objects.

• space_groups (int, diffpy.structure.spacegroups.SpaceGroup or list of int or diffpy.structure.spacegroups.SpaceGroup, optional) – Space groups.

• point_groups (str, int, orix.quaternion.symmetry.Symmetry or list of str, int or orix.quaternion.symmetry.Symmetry, optional) – Point groups.

• colors (str or list of str, optional) – Phase colors.

• ids (int, list of int or numpy.ndarray of int, optional) – Phase IDs.

• structures (diffpy.structure.Structure or list of diffpy.structure.Structure, optional) – Unit cells with atoms and a lattice of each phase. If None is passed (default), a default diffpy.structure.Structure object is created for each phase.

Examples

>>> from diffpy.structure import Atom, Lattice, Structure
>>> from orix.crystal_map import Phase, PhaseList
>>> pl = PhaseList(
...     names=["al", "cu"],
...     space_groups=[225] * 2,
...     structures=[
...         Structure(
...             atoms=[Atom("al", [0] * 3)],
...             lattice=Lattice(0.405, 0.405, 0.405, 90, 90, 90)
...         ),
...         Structure(
...             atoms=[Atom("cu", [0] * 3)],
...             lattice=Lattice(0.361, 0.361, 0.361, 90, 90, 90)
...         ),
...     ]
... )
>>> pl
Id  Name  Space group  Point group  Proper point group     Color
0    al        Fm-3m         m-3m                 432  tab:blue
1    cu        Fm-3m         m-3m                 432  tab:blue
>>> pl["al"].structure
[al   0.000000 0.000000 0.000000 1.0000]


Add phases to the end of a phase list, incrementing the phase IDs.

Parameters

value (Phase, list of Phase or another PhaseList) – Phase(s) to add. If a PhaseList is added, the phase IDs in the old list are lost.

Examples

>>> from orix.crystal_map import Phase, PhaseList
>>> pl = PhaseList(names=["a", "b"], space_groups=[10, 20])
>>> pl
Id  Name  Space group  Point group  Proper point group       Color
0     a         P2/m          2/m                 112    tab:blue
1     b        C2221          222                 222  tab:orange
2     c         Pnc2          mm2                 211   tab:green
3     d         Ama2          mm2                 211     tab:red
4     e         None         None                None  tab:purple
5     f         Pbcn          mmm                 222   tab:brown
6     g         Fddd          mmm                 222    tab:pink


Add a dummy phase to assign to not indexed data points.

The phase, named “not_indexed”, has a point_group equal to None, and a white color when plotted.

property colors

List of phase color names in the list.

property colors_rgb

List of phase color RGB values in the list.

deepcopy()

Return a deep copy using copy.deepcopy() function.

id_from_name(name)

Get phase ID from phase name.

Parameters

name (str) – Phase name.

property ids

Unique phase IDs in the list of phases.

property names

List of phase names in the list.

property point_groups

List of point groups of phases in the list.

property size

Number of phases in the list.

sort_by_id()

Sort list according to phase ID.

property space_groups

List of space groups of phases in the list.

property structures

List of phase structures.

### CrystalMap¶

 Return a deep copy using copy.deepcopy() function. empty([shape, step_sizes]) Create a crystal map of a given shape and step sizes with identity rotations. get_map_data(item[, decimals, fill_value]) Return an array of a class instance attribute, with values equal to False in self.is_in_data set to fill_value, of map data shape. plot([value, overlay, scalebar, ...]) Plot a 2D map with any crystallographic map property as map values.
class orix.crystal_map.CrystalMap(rotations, phase_id=None, x=None, y=None, z=None, phase_list=None, prop=None, scan_unit=None, is_in_data=None)

Crystallographic map of rotations, crystal phases and key properties associated with every spatial coordinate in a 1D, 2D or 3D space.

All properties are stored as 1D arrays, and reshaped when necessary.

__init__(rotations, phase_id=None, x=None, y=None, z=None, phase_list=None, prop=None, scan_unit=None, is_in_data=None)
Parameters
• rotations (orix.quaternion.Rotation) – Rotation of each data point. Must be passed with all spatial dimensions in the first array axis (flattened). May contain multiple rotations per point, included in the second array axes. Crystal map data size is set equal to the first array axis’ size.

• phase_id (numpy.ndarray, optional) – Phase ID of each pixel. IDs equal to -1 are considered not indexed. If None is passed (default), all points are considered to belong to one phase with ID 0.

• x (numpy.ndarray, optional) – Map x coordinate of each data point. If None is passed, the map is assumed to be 1D, and it is set to an array of increasing integers from 0 to the length of the phase_id array.

• y (numpy.ndarray, optional) – Map y coordinate of each data point. If None is passed, the map is assumed to be 1D, and it is set to None.

• z (numpy.ndarray, optional) – Map z coordinate of each data point. If None is passed, the map is assumed to be 2D or 1D, and it is set to None.

• phase_list (PhaseList, optional) – A list of phases in the data with their with names, space groups, point groups, and structures. The order in which the phases appear in the list is important, as it is this, and not the phases’ IDs, that is used to link the phases to the input phase_id if the IDs aren’t exactly the same as in phase_id. If None (default), a phase list with as many phases as there are unique phase IDs in phase_id is created.

• prop (dict of numpy.ndarray, optional) – Dictionary of properties of each data point.

• scan_unit (str, optional) – Length unit of the data. If None (default), “px” is used.

• is_in_data (np.ndarray, optional) – Array of booleans signifying whether a point is in the data.

Examples

>>> from diffpy.structure import Atom, Lattice, Structure
>>> import numpy as np
>>> from orix.crystal_map import CrystalMap
>>> from orix.quaternion.rotation import Rotation
>>> euler1, euler2, euler3, x, y, iq, dp, phase_id = np.loadtxt(
...     "/some/file.ang", unpack=True)
>>> euler_angles = np.column_stack((euler1, euler2, euler3))
>>> rotations = Rotation.from_euler(euler_angles)
>>> properties = {"iq": iq, "dp": dp}
>>> structures = [
...     Structure(
...         title="austenite",
...         atoms=[Atom("fe", [0] * 3)],
...         lattice=Lattice(0.360, 0.360, 0.360, 90, 90, 90)
...     ),
...     Structure(
...         title="ferrite",
...         atoms=[Atom("fe", [0] * 3)],
...         lattice=Lattice(0.287, 0.287, 0.287, 90, 90, 90)
...     )
... ]
>>> pl = PhaseList(space_groups=[225, 229], structures=structures)
>>> xmap = CrystalMap(
...     rotations=rotations,
...     phase_id=phase_id,
...     x=x,
...     y=y,
...     phase_list=pl,
...     prop=properties,
... )

property all_indexed

Whether all points in data are indexed.

deepcopy()

Return a deep copy using copy.deepcopy() function.

property dx
property dy
property dz
classmethod empty(shape=None, step_sizes=None)

Create a crystal map of a given shape and step sizes with identity rotations.

Parameters
• shape (tuple of int, optional) – Map shape. Default is a 2D map of shape (5, 10), i.e. with five rows and ten columns.

• step_sizes (tuple, optional) – Map step sizes. If None (default), it is set to 1 px in each map direction given by shape.

Return type

CrystalMap

Examples

>>> from orix.crystal_map import CrystalMap
>>> xmap = CrystalMap.empty((5, 10))
>>> xmap
Phase  Orientations  Name  Space group  Point group  Proper point group     Color
0   50 (100.0%)  None         None         None                None  tab:blue
Properties:
Scan unit: px
>>> xmap.plot("x")  # Increasing towards the right

get_map_data(item, decimals=None, fill_value=None)

Return an array of a class instance attribute, with values equal to False in self.is_in_data set to fill_value, of map data shape.

If item is “orientations”/”rotations” and there are multiple rotations per point, only the first rotation is used. Rotations are returned as Euler angles.

Parameters
• item (str or numpy.ndarray) – Name of the class instance attribute or a numpy.ndarray.

• decimals (int, optional) – Number of decimals to round data point values to. If not given, no rounding is done.

• fill_value (None, optional) – Value to fill points not in the data with. If None (default), np.nan is used.

Returns

output_array – Array of the class instance attribute with points not in data set to fill_value, of float data type.

Return type

numpy.ndarray

property id

ID of points in data.

property is_indexed

Whether points in data are indexed.

property ndim

Number of data dimensions of points in data.

property orientations

Rotations, respecting symmetry, in data.

property phase_id

Phase IDs of points in data.

property phases_in_data

List of phases in data.

Needed because it can be useful to have phases not in data but in self.phases.

plot(value=None, overlay=None, scalebar=True, scalebar_properties=None, legend=True, legend_properties=None, colorbar=False, colorbar_label=None, colorbar_properties={}, remove_padding=False, return_figure=False, figure_kwargs={}, **kwargs)

Plot a 2D map with any crystallographic map property as map values.

Wraps matplotlib.axes.Axes.imshow(), see that method for relevant keyword arguments.

Parameters
• value (numpy.ndarray, optional) – Attribute array to plot. If None (default), a phase map is plotted.

• overlay (str or numpy.ndarray, optional) – Name of map property or a property array to use in the alpha (RGBA) channel. The property range is adjusted for maximum contrast. Default is None.

• scalebar (bool, optional) – Whether to add a scalebar (default is True) along the horizontal map dimension.

• scalebar_properties (dict, optional) – Keyword arguments passed to matplotlib_scalebar.scalebar.ScaleBar.

• legend (bool, optional) – Whether to add a legend to the plot. This is only implemented for a phase plot (in which case default is True).

• legend_properties (dict, optional) – Keyword arguments passed to matplotlib.axes.legend().

• colorbar (bool, optional) – Whether to add an opinionated colorbar (default is False).

• colorbar_label (str, optional) – Label/title of colorbar.

• colorbar_properties (dict, optional) – Keyword arguments passed to orix.plot.CrystalMapPlot.add_colorbar().

• axes (tuple of ints, optional) – Which data axes to plot if data has more than two dimensions. The index of data to plot in the final dimension is determined by depth. If None (default), data along the two last axes is plotted.

• depth (int, optional) – Which layer along the third axis to plot if data has more than two dimensions. If None (default), data in the first index (layer) is plotted.

• return_figure (bool, optional) – Whether to return the figure (default is False).

• figure_kwargs (dict, optional) – Keyword arguments passed to matplotlib.pyplot.subplots().

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.imshow().

Returns

fig – The created figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

property prop

CrystalMapProperties dictionary with data properties in each data point.

property rotations

Rotations in data.

property rotations_per_point

Number of rotations per data point in data.

property rotations_shape

Shape of rotation object.

Map shape and possible multiple rotations per point are accounted for. 1-dimensions are squeezed out.

property shape

Shape of points in data.

property size

Total number of points in data.

property x

X coordinates of points in data.

property y

Y coordinates of points in data.

property z

Z coordinates of points in data.

### CrystalMapProperties¶

class orix.crystal_map.CrystalMapProperties(dictionary, id, is_in_data=None)

Bases: dict

A class to store properties with in a CrystalMap instance.

This class is a thin wrapper around dict. It overrides setting and getting property arrays in the dict to handle a data mask correctly, i.e. whether data points are considered to be in the data.

id

1D integer array with the id of each point in the data.

Type

numpy.ndarray

is_in_data

1D boolean array with True for points in the data, of the same size as the data.

Type

numpy.ndarray

### Other functions¶

orix.crystal_map.create_coordinate_arrays(shape=None, step_sizes=None)

Create flattened coordinate arrays from a given map shape and step sizes, suitable for initializing a orix.crystal_map.CrystalMap. Arrays for 1D, 2D, or 3D maps can be returned.

Parameters
• shape (tuple of int, optional) – Map shape. Default is a 2D map of shape (5, 10) with five rows and ten columns. Can be up to 3D.

• step_sizes (tuple, optional) – Map step sizes. If None (default), it is set to 1 px in each map direction given by shape.

Returns

• d (dict of numpy.ndarray) – Dictionary with keys “z”, “y”, and “x”, depending on the length of shape, with coordinate arrays.

• map_size (int) – Number of map points.

## io¶

 load(filename, **kwargs) Load data from a supported file. loadang(file_string) Load .ang files. loadctf(file_string) Load .ang files. plugins save(filename, object2write[, overwrite]) Write data to a supported file format.

Load data from a supported file.

Parameters
• filename (str) – Name of file to load.

• kwargs – Keyword arguments passed to the corresponding orix reader. See their individual docstrings for available arguments.

Returns

data – Crystal map read from the file.

Return type

CrystalMap

Load .ang files.

Parameters

file_string (str) – Path to the .ang file. This file is assumed to list the Euler angles in the Bunge convention in the first three columns.

Return type

Rotation

Load .ang files.

Parameters

file_string (str) – Path to the .ctf file. This file is assumed to list the Euler angles in the Bunge convention in the columns 5, 6, and 7.

Return type

Rotation

orix.io.save(filename, object2write, overwrite=None, **kwargs)

Write data to a supported file format.

Parameters
• filename (str) – Name of file to write to.

• object2write (CrystalMap) – Object to write to file.

• overwrite (bool, optional) – If None and the file exists, the user is queried. If True (False) the file is (not) overwritten if it exists.

• kwargs – Keyword arguments passed to the corresponding orix writer. See their individual docstrings for available arguments.

### plugins¶

 ang Reader of a crystal map from an .ang text file in formats produced by EDAX TSL, NanoMegas ASTAR Index, or EMsoft's EMdpmerge program. bruker_h5ebsd Reader of a crystal map from Bruker's h5ebsd file format. emsoft_h5ebsd Reader of a crystal map from EMsoft's dictionary indexing dot product file. orix_hdf5 Reader and writer of a crystal map to and from orix' own HDF5 file format.

#### ang¶

Reader of a crystal map from an .ang text file in formats produced by EDAX TSL, NanoMegas ASTAR Index, or EMsoft’s EMdpmerge program.

Return a CrystalMap object from a file in EDAX TLS’s .ang format. The map in the input is assumed to be 2D.

Many vendors produce an .ang file. Supported vendors are * EDAX TSL

• NanoMegas ASTAR Index

• EMsoft (from program EMdpmerge)

• orix

All points satisfying the following criteria are classified as not indexed:

• EDAX TSL: confidence index == -1

Parameters

filename (str) – Path and file name.

Return type

CrystalMap

orix.io.plugins.ang.file_writer(filename, xmap, index=None, image_quality_prop=None, confidence_index_prop=None, detector_signal_prop=None, pattern_fit_prop=None, extra_prop=None)

Write a CrystalMap to an .ang file readable (at least) by MTEX and EDAX TSL OIM Analysis v7.

The columns are phi1, Phi, phi2, x, y, image_quality, confidence_index, phase_id, detector_signal, and pattern_fit.

Parameters in masked out or non-indexed points are set to

• euler angles = 4 * pi

• image quality = 0

• confidence index = -1

• phase ID = 0 if single phase or -1 if multi phase

• pattern fit = 180

• detector signal = 0

• extra properties = 0

Parameters
• filename (str) – File name with an “.ang” file extension to write to.

• xmap (CrystalMap) – Crystal map to write to file.

• index (int, optional) – If the crystal map has more than one rotation/match and phase ID per point, this index can be set to write that “layer” of data to the file. For properties to be written as well, these must also have multiple values per point. To get the best match at every point, use None (default).

• image_quality_prop (str, optional) – Which map property to use as the image quality. If None (default), “iq” or “imagequality”, if present, is used, or just zeros. If the property has more than one value per point, only the first value is used.

• confidence_index_prop (str, optional) – Which map property to use as the confidence index. If None (default), “ci” or “confidenceindex”, if present, is used, or just zeros. If the property has more than one value per point, only the first value is used.

• detector_signal_prop (str, optional) – Which map property to use as the detector signal. If None (default), “ds”, or “detectorsignal”, if present, is used, or just zeros. If the property has more than one value per point, only the first value is used.

• pattern_fit_prop (str, optional) – Which map property to use as the pattern fit. If None (default), “fit” or “patternfit”, if present, is used, or just zeros. If the property has more than one value per point, only the first value is used.

• extra_prop (str or list of str, optional) – One or multiple properties to add as extra columns in the .ang file, as a string or a list of strings. If None (default), no extra properties are added.

#### bruker_h5ebsd¶

Reader of a crystal map from Bruker’s h5ebsd file format.

Return a CrystalMap from a file in Bruker Nano’s dot product file format.

Parameters
• filename (str) – Path and file name.

• kwargs – Keyword arguments passed to h5py.File().

Return type

CrystalMap

#### emsoft_h5ebsd¶

Reader of a crystal map from EMsoft’s dictionary indexing dot product file.

Return a CrystalMap from a file in EMsoft’s dictionary indexing dot product file format.

Parameters
• filename (str) – Path and file name.

• refined (bool, optional) – Whether to return refined orientations. Default is False.

• kwargs – Keyword arguments passed to h5py.File().

Return type

CrystalMap

#### orix_hdf5¶

Reader and writer of a crystal map to and from orix’ own HDF5 file format.

Return a CrystalMap object from a file in orix’ HDF5 file format.

Parameters
• filename (str) – Path and file name.

• kwargs – Keyword arguments passed to h5py.File().

Return type

CrystalMap

orix.io.plugins.orix_hdf5.file_writer(filename, crystal_map, **kwargs)

Write a CrystalMap object to an HDF5 file.

Parameters
• filename (str) – Name of file to write to.

• crystal_map (CrystalMap) – Object to write to file.

• kwargs – Keyword arguments passed to h5py:Group.require_dataset().

## plot¶

Extensions of Matplotlib’s projections framework for plotting Vector3d, Rotation, Orientation, Misorientation, and CrystalMap.

Example of usage:

>>> import matplotlib.pyplot as plt
>>> from orix import plot, vector
>>> fig, ax = plt.subplots(subplot_kw=dict(projections="stereographic"))
>>> ax.scatter(vector.Vector3d([[0, 0, 1], [1, 0, 1]]))

 AxAnglePlot(fig[, rect, azim, elev, sharez, ...]) Plot rotations in an Axes-Angle projection. CrystalMapPlot(fig, rect, *[, facecolor, ...]) 2D plotting of CrystalMap objects. DirectionColorKeyTSL(symmetry) Assign colors to (crystal) directions rotated by crystal orientations and projected into an inverse pole figure, according to the Laue symmetry of the crystal. EulerColorKey(symmetry) Assign colors to crystal orientations from their Euler angle triplet $$(\phi_1, \Phi, \phi_2)$$ in the fundamental Euler region of the orientations' proper subgroup. InversePoleFigurePlot(*args[, symmetry, ...]) Inverse pole figure plot of Vector3d, which is a stereographic plot for showing sample directions with respect to a crystal reference frame. IPFColorKeyTSL(symmetry[, direction]) Assign colors to crystal directions rotated by crystal orientations and projected into an inverse pole figure, according to the Laue symmetry of the crystal. RodriguesPlot(fig[, rect, azim, elev, ...]) Plot rotations in a Rodrigues-Frank projection. RotationPlot(fig[, rect, azim, elev, ...]) StereographicPlot(*args[, hemisphere, ...]) Stereographic plot for plotting Vector3d.

### AxAnglePlot¶

class orix.plot.AxAnglePlot(fig, rect=None, *args, azim=- 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, computed_zorder=True, **kwargs)

Plot rotations in an Axes-Angle projection.

### CrystalMapPlot¶

 add_colorbar([label]) Add an opinionated colorbar to the figure and return it. add_overlay(crystal_map, item) Use a crystal map property as gray scale values of a phase map. add_scalebar(crystal_map, **kwargs) Add a scalebar to the axes instance and return it. plot_map(crystal_map[, value, scalebar, ...]) Plot a 2D map with any CrystalMap attribute as map values. Remove all white padding outside of the figure.
class orix.plot.CrystalMapPlot(fig, rect, *, facecolor=None, frameon=True, sharex=None, sharey=None, label='', xscale=None, yscale=None, box_aspect=None, **kwargs)

2D plotting of CrystalMap objects.

Add an opinionated colorbar to the figure and return it.

The colorbar is also available as an attribute colorbar.

Parameters
• label (str, optional) – Colorbar title, default is None.

• kwargs – Keyword arguments passed to mpl_toolkits.axes_grid1.make_axes_locatable.append_axes().

Returns

cbar – Colorbar.

Return type

matplotlib.colorbar

Examples

>>> xmap
Phase  Orientations   Name       Symmetry  Color
1      5657 (48.4%)   austenite  432       tab:blue
2      6043 (51.6%)   ferrite    432       tab:orange
Properties: iq, dp
Scan unit: um


Plot a map property and add a colorbar

>>> fig = plt.figure()
>>> im = ax.plot_map(xmap, xmap.dp, cmap="inferno")


If the default options are not satisfactory, the colorbar can be updated

>>> cbar.ax.set_ylabel(ylabel="dp", rotation=90)


Use a crystal map property as gray scale values of a phase map.

The property’s range is adjusted to [0, 1] for maximum contrast.

Parameters
• crystal_map (orix.crystal_map.CrystalMap) – Crystal map object to obtain necessary data from.

• item (str) – Name of map property to scale phase array with. The property range is adjusted for maximum contrast.

Examples

>>> xmap
Phase  Orientations   Name       Symmetry  Color
1      5657 (48.4%)   austenite  432       tab:blue
2      6043 (51.6%)   ferrite    432       tab:orange
Properties: iq, dp
Scan unit: um


Plot a phase map with a map property as overlay

>>> fig = plt.figure()
>>> im = ax.plot_map(xmap)


Add a scalebar to the axes instance and return it.

The scalebar is also available as an attribute scalebar.

Parameters
• crystal_map (orix.crystal_map.CrystalMap) – Crystal map instance to obtain necessary data from.

• kwargs – Keyword arguments passed to matplotlib_scalebar.scalebar.ScaleBar.

Returns

bar – Scalebar.

Return type

matplotlib_scalebar.scalebar.ScaleBar

Examples

>>> xmap
Phase  Orientations   Name       Symmetry  Color
1      5657 (48.4%)   austenite  432       tab:blue
2      6043 (51.6%)   ferrite    432       tab:orange
Properties: iq, dp
Scan unit: um


Create a phase map without a scale bar and add it afterwards

>>> fig = plt.figure()
>>> im = ax.plot_map(xmap, scalebar=False)
>>> sbar = ax.add_scalebar(xmap, location=4, frameon=False)

colorbar = None
name = 'plot_map'
plot_map(crystal_map, value=None, scalebar=True, scalebar_properties=None, legend=True, legend_properties=None, axes=None, depth=None, override_status_bar=False, **kwargs)

Plot a 2D map with any CrystalMap attribute as map values.

Wraps matplotlib.axes.Axes.imshow(), see that method for relevant keyword arguments.

Parameters
• crystal_map (orix.crystal_map.CrystalMap) – Crystal map object to obtain data to plot from.

• value (numpy.ndarray, optional) – Attribute array to plot. If value is None (default), a phase map is plotted.

• scalebar (bool, optional) – Whether to add a scalebar (default is True) along the horizontal map dimension.

• scalebar_properties (dict) – Dictionary of keyword arguments passed to mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar().

• legend (bool, optional) – Whether to add a legend to the plot. This is only implemented for a phase plot (in which case default is True).

• legend_properties (dict) – Dictionary of keyword arguments passed to matplotlib.axes.legend().

• axes (tuple of ints, optional) – Which data axes to plot if data has more than two dimensions. The index of data to plot in the final dimension is determined by depth. If None (default), data along the two last axes is plotted.

• depth (int, optional) – Which layer along the third axis to plot if data has more than two dimensions. If None (default), data in the first index (layer) is plotted.

• override_status_bar (bool, optional) – Whether to display Euler angles and any overlay values in the status bar when hovering over the map (default is False).

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.imshow().

Returns

im – Image object, to be used further to get data from etc.

Return type

matplotlib.image.AxesImage

Examples

>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> from orix import plot


Import a crystal map

>>> xmap = load("/some/directory/data.ang")


Plot a phase map

>>> fig = plt.figure()  # Get figure
>>> ax = fig.add_subplot(projection="plot_map")  # Get axes
>>> im = ax.plot_map(xmap)  # Get image


>>> ax.add_overlay(xmap, xmap.iq)


Plot an arbitrary map property, also changing scalebar location

>>> ax = plt.subplot(projection="plot_map")
>>> ax.plot_map(
...     xmap, xmap.dp, cmap="cividis", scalebar_properties={"loc": 4}
... )


>>> cbar = ax.add_colorbar("Dot product")  # Get colorbar


Plot orientation angle in degrees of one phase

>>> xmap2 = xmap["austenite"]
>>> austenite_angles = xmap2.orientations.angle.data * 180 / np.pi
>>> fig = plt.figure()
>>> im = ax.plot_map(xmap2, austenite_angles)
>>> ax.add_colorbar("Orientation angle [$^{\circ}$]")


Remove all figure and axes padding

>>> ax.remove_padding()


Write annotated figure to file

>>> fig.savefig(
...     "/some/directory/image.png",
...     bbox_inches="tight"
... )


Write un-annotated image to file

>>> plt.imsave("/some/directory/image2.png", im.get_array())


Remove all white padding outside of the figure.

Examples

>>> xmap
Phase  Orientations   Name       Symmetry  Color
1      5657 (48.4%)   austenite  432       tab:blue
2      6043 (51.6%)   ferrite    432       tab:orange
Properties: iq, dp
Scan unit: um


Remove all figure and axes padding of a phase map

>>> fig = plt.figure()
>>> ax.plot_map(xmap)

scalebar = None
set(*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, facecolor=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:

adjustable: {‘box’, ‘datalim’} agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array alpha: scalar or None anchor: (float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …} animated: bool aspect: {‘auto’, ‘equal’} or float autoscale_on: bool autoscalex_on: bool autoscaley_on: bool axes_locator: Callable[[Axes, Renderer], Bbox] axisbelow: bool or ‘line’ box_aspect: float or None clip_box: .Bbox clip_on: bool clip_path: Patch or (Path, Transform) or None facecolor or fc: color figure: .Figure frame_on: bool gid: str in_layout: bool label: object navigate: bool navigate_mode: unknown path_effects: .AbstractPathEffect picker: None or bool or float or callable position: [left, bottom, width, height] or ~matplotlib.transforms.Bbox prop_cycle: unknown rasterization_zorder: float or None rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None title: str transform: .Transform url: str visible: bool xbound: unknown xlabel: str xlim: (bottom: float, top: float) xmargin: float greater than -0.5 xscale: {“linear”, “log”, “symlog”, “logit”, …} or .ScaleBase xticklabels: unknown xticks: unknown ybound: unknown ylabel: str ylim: (bottom: float, top: float) ymargin: float greater than -0.5 yscale: {“linear”, “log”, “symlog”, “logit”, …} or .ScaleBase yticklabels: unknown yticks: unknown zorder: float

### DirectionColorKeyTSL¶

 direction2color(direction) Return an RGB color per orientation given a Laue symmetry and a sample direction. plot([return_figure]) Plot the inverse pole figure color key.
class orix.plot.DirectionColorKeyTSL(symmetry)

Bases: orix.plot.direction_color_keys.direction_color_key.DirectionColorKey

Assign colors to (crystal) directions rotated by crystal orientations and projected into an inverse pole figure, according to the Laue symmetry of the crystal.

This is based on the TSL color key implemented in MTEX.

__init__(symmetry)

Create an inverse pole figure (IPF) color key to color crystal directions according to a Laue symmetry’s fundamental sector (IPF).

Parameters

symmetry (orix.quaternion.Symmetry) – (Laue) symmetry of the crystal. If a non-Laue symmetry is given, the Laue symmetry of that symmetry will be used.

direction2color(direction)

Return an RGB color per orientation given a Laue symmetry and a sample direction.

Plot the inverse pole figure color key with plot().

Parameters

direction (orix.vector.Vector3d) – Directions to color.

Returns

rgb – Color array of shape direction.shape + (3,).

Return type

numpy.ndarray

plot(return_figure=False)

Plot the inverse pole figure color key.

Parameters

return_figure (bool, optional) – Whether to return the figure. Default is False.

Returns

figure – Color key figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

### EulerColorKey¶

 orientation2color(orientation) Return an RGB color per orientation given a proper point group symmetry. plot([return_figure]) Plot the color key.
class orix.plot.EulerColorKey(symmetry)

Assign colors to crystal orientations from their Euler angle triplet $$(\phi_1, \Phi, \phi_2)$$ in the fundamental Euler region of the orientations’ proper subgroup.

The Euler angle ranges of each proper subgroup are given in euler_fundamental_region. The mapping of orientations’ Euler angles to the fundamental Euler region is done with in_euler_fundamental_region().

__init__(symmetry)

Create a Euler color key to color orientations according their Euler angle triplet in the fundamental Euler region of the proper subgroup.

Parameters

symmetry (orix.quaternion.Symmetry) – Proper point group of the crystal. If an improper point group is given, the proper point group is derived from it if possible.

orientation2color(orientation)

Return an RGB color per orientation given a proper point group symmetry.

Plot the Euler color key with plot().

Parameters

orientation (orix.quaternion.Orientation) – Orientations to color.

Returns

rgb – Color array of shape orientation.shape + (3,).

Return type

numpy.ndarray

plot(return_figure=False)

Plot the color key.

Parameters

return_figure (bool, optional) – Whether to return the figure. Default is False.

Returns

figure – Color key figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

### InversePoleFigurePlot¶

 scatter(*args, **kwargs) A scatter plot of sample directions rotated by orientations, or orientations to rotate sample directions with. show_hemisphere_label(**kwargs) Add a hemisphere label ("upper"/"lower") to the upper left outside the inverse pole figure. text(*args, **kwargs) Add text to the axes.
class orix.plot.InversePoleFigurePlot(*args, symmetry=None, direction=None, hemisphere=None, **kwargs)

Inverse pole figure plot of Vector3d, which is a stereographic plot for showing sample directions with respect to a crystal reference frame.

Inherits from StereographicPlot.

__init__(*args, symmetry=None, direction=None, hemisphere=None, **kwargs)

Create an inverse pole figure axis for plotting Vector3d.

Parameters
• args – Arguments passed to orix.plot.StereographicPlot.__init__().

• symmetry (Symmetry, optional) – Laue group symmetry of crystal to plot directions with. If not given, point group C1 (only identity rotation) is used.

• direction (Vector3d, optional) – Sample direction to plot with respect to crystal directions. If not given, the out of plane direction, sample Z, is used.

• hemisphere (str, optional) – Which hemisphere(s) to plot the vectors in. If not given, “upper” is used. Options are “upper”, “lower”, and “both”, which plots two projections side by side.

• hemisphere – Which hemisphere to plot vectors in, either “upper” (default) or “lower”.

• kwargs – Keyword arguments passed to orix.plot.StereographicPlot.__init__().

property hemisphere

Hemisphere to plot.

Returns

“upper” or “lower” plots the upper or lower hemisphere vectors. pole is derived from this attribute.

Return type

str

name = 'ipf'
scatter(*args, **kwargs)

A scatter plot of sample directions rotated by orientations, or orientations to rotate sample directions with.

Parameters
• args (tuple of numpy.ndarray, Orientation, or Vector3d) – Spherical coordinates (azimuth, polar), orientations, or vectors. If spherical coordinates are given, they are assumed to describe unit vectors. Vectors will be made into unit vectors if they aren’t already. If orientations are passed, the crystal directions returned are the sample direction rotated by the orientations.

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.scatter().

show_hemisphere_label(**kwargs)

Add a hemisphere label (“upper”/”lower”) to the upper left outside the inverse pole figure.

Parameters

kwargs – Keyword arguments passed to matplotlib.axes.Axes.text().

text(*args, **kwargs)

This method overwrites matplotlib.axes.Axes.text(), see that method’s docstring for parameters.

Parameters

### IPFColorKeyTSL¶

 orientation2color(orientation) Return an RGB color per orientation given a Laue symmetry and a sample direction. plot([return_figure]) Plot the inverse pole figure color key.
class orix.plot.IPFColorKeyTSL(symmetry, direction=None)

Bases: orix.plot.orientation_color_keys.ipf_color_key.IPFColorKey

Assign colors to crystal directions rotated by crystal orientations and projected into an inverse pole figure, according to the Laue symmetry of the crystal.

This is based on the TSL color key implemented in MTEX.

__init__(symmetry, direction=None)

Create an inverse pole figure (IPF) color key to color orientations according a sample direction and a Laue symmetry’s fundamental sector (IPF).

Parameters
• symmetry (orix.quaternion.Symmetry) – (Laue) symmetry of the crystal. If a non-Laue symmetry is given, the Laue symmetry of that symmetry will be used.

• direction (orix.vector.Vector3d, optional) – Sample direction. If not given, sample Z direction (out of plane) is used.

property direction_color_key
orientation2color(orientation)

Return an RGB color per orientation given a Laue symmetry and a sample direction.

Plot the inverse pole figure color key with plot().

Parameters

orientation (orix.quaternion.Orientation) – Orientations to color.

Returns

rgb – Color array of shape orientation.shape + (3,).

Return type

numpy.ndarray

plot(return_figure=False)

Plot the inverse pole figure color key.

Parameters

return_figure (bool, optional) – Whether to return the figure. Default is False.

Returns

figure – Color key figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

### RodriguesPlot¶

class orix.plot.RodriguesPlot(fig, rect=None, *args, azim=- 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, computed_zorder=True, **kwargs)

Plot rotations in a Rodrigues-Frank projection.

### RotationPlot¶

class orix.plot.RotationPlot(fig, rect=None, *args, azim=- 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, computed_zorder=True, **kwargs)

### StereographicPlot¶

 draw_circle(*args[, opening_angle, steps]) Draw great or small circles with a given opening_angle to one or multiple vectors. plot(*args, **kwargs) Draw straight lines between vectors. restrict_to_sector(sector) Restrict the stereographic axis to a FundamentalSector, typically obtained from fundamental_sector. scatter(*args, **kwargs) A scatter plot of vectors. show_hemisphere_label(**kwargs) Add a hemisphere label ("upper"/"lower") to the upper left of the plane. set_labels([xlabel, ylabel, zlabel]) Set the reference frame's axes labels. stereographic_grid([show_grid, ...]) Turn a stereographic grid on or off, and set the azimuth and polar grid resolution in degrees. symmetry_marker(v, fold, **kwargs) Plot 2-, 3- 4- or 6-fold symmetry marker(s). text(*args, **kwargs) Add text to the axes.
class orix.plot.StereographicPlot(*args, hemisphere='upper', azimuth_resolution=10, polar_resolution=10, **kwargs)

Stereographic plot for plotting Vector3d.

Inherits from Axes.

__init__(*args, hemisphere='upper', azimuth_resolution=10, polar_resolution=10, **kwargs)

Create an axis for plotting Vector3d.

Parameters
• args – Arguments passed to matplotlib.axes.Axes.__init__().

• hemisphere (str, optional) – Which hemisphere to plot vectors in, either “upper” (default) or “lower”.

• azimuth_resolution (int or float, optional) – Resolution of azimuth grid lines in degrees. Default is 10 degrees.

• polar_resolution (int or float, optional) – Resolution of polar grid lines in degrees. Default is 10 degrees.

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.__init__().

draw_circle(*args, opening_angle=1.5707963267948966, steps=100, **kwargs)

Draw great or small circles with a given opening_angle to one or multiple vectors.

A vector must be present in the current hemisphere for its circle to be drawn.

Parameters
• args (Vector3d or tuple of float or numpy.ndarray) – Vector(s), or azimuth and polar angles defining vectors, the latter two passed as separate arguments (not keyword arguments). Circles are drawn perpendicular to these with a given opening_angle.

• opening_angle (float or numpy.ndarray, optional) – Opening angle(s) around the vector(s). Default is $$\pi/2$$, giving a great circle. If an array is passed, its size must be equal to the number of circles to draw.

• steps (int, optional) – Number of vectors to describe each circle, default is 100.

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.plot() to alter the circles’ appearance.

property hemisphere

Hemisphere to plot.

Returns

“upper” or “lower” plots the upper or lower hemisphere vectors. pole is derived from this attribute.

Return type

str

name = 'stereographic'
plot(*args, **kwargs)

Draw straight lines between vectors.

This method overwrites matplotlib.axes.Axes.plot(), see that method’s docstring for parameters.

Parameters
property pole

Projection pole, either -1 or 1, where -1 (1) means the projection point of the stereographic transform is the south (north) pole [00-1] ([001]), i.e. only vectors with z > 0 (z < 0) are plotted.

Derived from hemisphere.

restrict_to_sector(sector)

Restrict the stereographic axis to a FundamentalSector, typically obtained from fundamental_sector.

Parameters

sector (FundamentalSector) – Fundamental sector with edges delineating a fundamental sector.

scatter(*args, **kwargs)

A scatter plot of vectors.

This method overwrites matplotlib.axes.Axes.scatter(), see that method’s docstring for parameters.

Parameters
set_labels(xlabel='x', ylabel='y', zlabel='z', **kwargs)

Set the reference frame’s axes labels.

Parameters
• xlabel (str, False or None, optional) – X axis label, default is “x”. If False or None, this label is not shown.

• ylabel (str, False or None, optional) – Y axis label, default is “y”. If False or None, this label is not shown.

• zlabel (str, False or None, optional) – Z axis label, default is “z”. If False or None, this label is not shown.

show_hemisphere_label(**kwargs)

Add a hemisphere label (“upper”/”lower”) to the upper left of the plane.

Parameters

kwargs – Keyword arguments passed to matplotlib.axes.Axes.text().

stereographic_grid(show_grid=None, azimuth_resolution=None, polar_resolution=None)

Turn a stereographic grid on or off, and set the azimuth and polar grid resolution in degrees.

Parameters
• show_grid (bool, optional) – Whether to show grid lines. If any keyword arguments are passed, this is set to True. If not given and there are no keyword arguments, the grid lines are toggled.

• azimuth_resolution (float, optional) – Azimuth grid resolution in degrees. Default is 10 degrees. This can also be set upon initialization of the axes by passing azimuth_resolution to subplot_kw.

• polar_resolution (float, optional) – Polar grid resolution in degrees. Default is 10 degrees. This can also be set upon initialization of the axes by passing polar_resolution to subplot_kw.

symmetry_marker(v, fold, **kwargs)

Plot 2-, 3- 4- or 6-fold symmetry marker(s).

Parameters
• v (Vector3d) – Position of the marker(s) to plot.

• fold (int) – Which symmetry element to plot, can be either 2, 3, 4 or 6.

• kwargs – Keyword arguments passed to scatter().

text(*args, **kwargs)

This method overwrites matplotlib.axes.Axes.text(), see that method’s docstring for parameters.

Parameters

## projections¶

Projections of orix.vector.Vector3d to various other representations.

 Get stereographic coordinates (X, Y) from representations of vectors. Get 3D unit vectors or spherical coordinates from stereographic coordinates (X, Y).

### StereographicProjection¶

 inverse Return the corresponding inverse projection, InverseStereographicProjection, with the same projection pole. spherical2xy(azimuth, polar) Return stereographic coordinates (X, Y) from 3D unit vectors created from spherical coordinates, azimuth $$\phi$$ and polar $$\theta$$, defined as in the ISO 31-11 standard [SphericalWolfram]. spherical2xy_split(azimuth, polar) Return two sets of stereographic coordinates (X, Y) from 3D unit vectors created from spherical coordinates, azimuth $$\phi$$ and polar $$\theta$$, defined as in the ISO 31-11 standard [SphericalWolfram]: one set for vectors in the upper hemisphere, and one for the lower. Return stereographic coordinates (X, Y) of 3D unit vectors. Return two sets of stereographic coordinates (X, Y) from 3D unit vectors: one set for vectors in the upper hemisphere, and one for the lower.
class orix.projections.StereographicProjection(pole=- 1)

Get stereographic coordinates (X, Y) from representations of vectors.

__init__(pole=- 1)

Initialize projection by setting whether the south pole (-1) or north pole (1) is the projection point.

Parameters

pole (int, optional) – -1 or 1, where -1 (1) means the projection point is the south (north) pole [00-1] ([001]), i.e. only vectors with z > 0 (z < 0) are returned.

property inverse

Return the corresponding inverse projection, InverseStereographicProjection, with the same projection pole.

spherical2xy(azimuth, polar)

Return stereographic coordinates (X, Y) from 3D unit vectors created from spherical coordinates, azimuth $$\phi$$ and polar $$\theta$$, defined as in the ISO 31-11 standard [SphericalWolfram].

Parameters
Returns

• x (numpy.ndarray) – Stereographic coordinate X of shape same shape as the input vector shape. Only the vectors with $$z$$ coordinate positive (pole = -1) or negative (pole = 1) are returned.

• y (numpy.ndarray) – Stereographic coordinate Y of shape same shape as the input vector shape. Only the vectors with $$z$$ coordinate positive (pole = -1) or negative (pole = 1) are returned.

spherical2xy_split(azimuth, polar)

Return two sets of stereographic coordinates (X, Y) from 3D unit vectors created from spherical coordinates, azimuth $$\phi$$ and polar $$\theta$$, defined as in the ISO 31-11 standard [SphericalWolfram]: one set for vectors in the upper hemisphere, and one for the lower.

Parameters
Returns

• x_upper (numpy.ndarray) – Stereographic coordinate X of upper hemisphere vectors, of shape same shape as the input vector shape.

• y_upper (numpy.ndarray) – Stereographic coordinate Y of upper hemisphere vectors, of shape same shape as the input vector shape.

• x_lower (numpy.ndarray) – Stereographic coordinate X of lower hemisphere vectors, of shape same shape as the input vector shape.

• y_lower (numpy.ndarray) – Stereographic coordinate Y of lower hemisphere vectors, of shape same shape as the input vector shape.

vector2xy(v)

Return stereographic coordinates (X, Y) of 3D unit vectors.

Parameters

v (Vector3d) – If it’s not a unit vector, it will be made into one.

Returns

• x (numpy.ndarray) – Stereographic coordinate X of shape same shape as the input vector shape. Only the vectors with $$z$$ coordinate positive (pole = -1) or negative (pole = 1) are returned.

• y (numpy.ndarray) – Stereographic coordinate Y of shape same shape as the input vector shape. Only the vectors with $$z$$ coordinate positive (pole = -1) or negative (pole = 1) are returned.

Notes

The stereographic coordinates $$(X, Y)$$ are calculated from the unit vectors’ cartesian coordinates $$(x, y, z)$$ as

$(X, Y) = \left(\frac{-px}{z - p}, \frac{-py}{z - p}\right),$

where $$p$$ is either 1 (north pole as projection point) or -1 (south pole as projection point).

static vector2xy_split(v)

Return two sets of stereographic coordinates (X, Y) from 3D unit vectors: one set for vectors in the upper hemisphere, and one for the lower.

Parameters

v (Vector3d) – If it’s not a unit vector, it will be made into one.

Returns

• x_upper (numpy.ndarray) – Stereographic coordinate X of upper hemisphere vectors, of shape same shape as the input vector shape.

• y_upper (numpy.ndarray) – Stereographic coordinate Y of upper hemisphere vectors, of shape same shape as the input vector shape.

• x_lower (numpy.ndarray) – Stereographic coordinate X of lower hemisphere vectors, of shape same shape as the input vector shape.

• y_lower (numpy.ndarray) – Stereographic coordinate Y of lower hemisphere vectors, of shape same shape as the input vector shape.

### InverseStereographicProjection¶

 xy2spherical(x, y) Return spherical coordinates, azimuth $$phi$$ and polar $$theta$$, defined as in the ISO 31-11 standard [SphericalWolfram], from stereographic coordinates (X, Y). xy2vector(x, y) Return 3D unit vectors from stereographic coordinates (X, Y).
class orix.projections.InverseStereographicProjection(pole=- 1)

Get 3D unit vectors or spherical coordinates from stereographic coordinates (X, Y).

__init__(pole=- 1)

Initialize inverse projection by setting whether the south pole (-1) or north pole (1) is the projection point.

Parameters

pole (int, optional) – -1 or 1, where -1 (1) means the projection point is the south (north) pole [00-1] ([001]), i.e. only vectors with z > 0 (z < 0) are returned.

xy2spherical(x, y)

Return spherical coordinates, azimuth $$phi$$ and polar $$theta$$, defined as in the ISO 31-11 standard [SphericalWolfram], from stereographic coordinates (X, Y).

Parameters
Returns

• azimuth (numpy.ndarray) – Azimuth spherical coordinate corresponding to (X, Y). Whether the coordinates for the upper or lower hemisphere points are returned is controlled by pole (-1 = upper, 1 = lower).

• theta (numpy.ndarray) – Polar spherical coordinate corresponding to (X, Y). Whether the coordinates for the upper or lower hemisphere points are returned is controlled by pole (-1 = upper, 1 = lower).

xy2vector(x, y)

Return 3D unit vectors from stereographic coordinates (X, Y).

Parameters
Returns

Unit vectors corresponding to the stereographic coordinates. Whether the upper or lower hemisphere points are returned is controlled by pole (-1 = upper, 1 = lower).

Return type

Vector3d

Notes

The 3D unit vectors $$(x, y, z)$$ are calculated from the stereographic coordinates $$(X, Y)$$ as

$(x, y, z) = \left( \frac{2x}{1 + x^2 + y^2}, \frac{2y}{1 + x^2 + y^2}, \frac{-p(1 - x^2 - y^2)}{1 + x^2 + y^2} \right),$

where $$p$$ is either 1 (north pole as projection point) or -1 (south pole as projection point).

## quaternion¶

Four-dimensional objects.

In a simplified sense, quaternions are an extension of the concept of complex numbers, represented by $$a + bi + cj + dk$$ where $$i$$, $$j$$, and $$k$$ are quaternion units and $$i^2 = j^2 = k^2 = ijk = -1$$. For further reference see the Wikipedia article.

Unit quaternions are efficient objects for representing rotations, and hence orientations.

 Orientation(data[, symmetry]) Orientations represent misorientations away from a reference of identity and have only one associated symmetry. A set of Rotation which are the normals of an orientation region. Misorientation(data[, symmetry]) Misorientation object. Quaternion([data]) Basic quaternion object. Rotation(data) Rotation object. Symmetry(data) The set of rotations comprising a point group.

### Orientation and Misorientation¶

Rotations respecting symmetry.

An orientation is simply a rotation with respect to some reference frame. In this respect, an orientation is in fact a misorientation - a change of orientation - with respect to a reference of the identity rotation.

In orix, orientations and misorientations are distinguished from rotations only by the inclusion of a notion of symmetry. Consider the following example:

Both objects have undergone the same rotations with respect to the reference. However, because the square has fourfold symmetry, it is indistinguishable in both cases, and hence has the same orientation.

#### Orientation¶

 angle_with(other) The smallest symmetry reduced angle of rotation transforming this orientation to the other. distance([verbose, split_size]) [Deprecated] dot(other) Symmetry reduced dot product of orientations in this instance to orientations in another instance, returned as Scalar. dot_outer(other) Symmetry reduced dot product of every orientation in this instance to every orientation in another instance, returned as Scalar. from_axes_angles(axes, angles[, symmetry]) Creates orientation(s) from axis-angle pair(s). from_euler(euler[, symmetry, convention, ...]) Creates orientation(s) from an array of Euler angles. from_matrix(matrix[, symmetry]) Creates orientation(s) from orientation matrices [RRR+15]. from_neo_euler(neo_euler[, symmetry]) Creates orientation(s) from a neo-euler (vector) representation. get_distance_matrix([lazy, chunk_size, ...]) The symmetry reduced smallest angle of rotation transforming each orientation in this instance to every other orientation. Euler angles in the fundamental Euler region of the proper subgroup. scatter([projection, figure, position, ...]) Plot orientations in axis-angle space, the Rodrigues fundamental zone, or an inverse pole figure (IPF) given a sample direction. set_symmetry(symmetry) [Deprecated] Assign a symmetry to this orientation. transpose(*axes) Returns a new object containing the same data transposed.
class orix.quaternion.Orientation(data, symmetry=None)

Orientations represent misorientations away from a reference of identity and have only one associated symmetry.

Orientations support binary subtraction, producing a misorientation. That is, to compute the misorientation from $$o_1$$ to $$o_2$$, call o_2 - o_1.

angle_with(other)

The smallest symmetry reduced angle of rotation transforming this orientation to the other.

Parameters

other (orix.quaternion.Orientation) –

Return type

Scalar

distance(verbose=False, split_size=100)

[Deprecated]

Notes

Deprecated since version 0.7: Function distance() is deprecated and will be removed in version 0.8. Use orix.quaternion.Orientation.get_distance_matrix() instead.

dot(other)

Symmetry reduced dot product of orientations in this instance to orientations in another instance, returned as Scalar.

dot_outer(other)

Symmetry reduced dot product of every orientation in this instance to every orientation in another instance, returned as Scalar.

classmethod from_axes_angles(axes, angles, symmetry=None)

Creates orientation(s) from axis-angle pair(s).

Parameters
• axes (Vector3d or array_like) – The axis of rotation.

• angles (array_like) – The angle of rotation, in radians.

• symmetry (Symmetry, optional) – Symmetry of orientation(s). If None (default), no symmetry is set.

Return type

Orientation

Examples

>>> import numpy as np
>>> from orix.quaternion import Orientation, symmetry
>>> ori = Orientation.from_axes_angles((0, 0, -1), np.pi / 2, symmetry.Oh)
>>> ori
Orientation (1,) m-3m
[[ 0.7071  0.      0.     -0.7071]]

classmethod from_euler(euler, symmetry=None, convention='bunge', direction='crystal2lab')

Creates orientation(s) from an array of Euler angles.

Parameters
• euler (array-like) – Euler angles in the Bunge convention.

• symmetry (Symmetry, optional) – Symmetry of orientation(s). If None (default), no symmetry is set.

• convention (str) – Only ‘bunge’ is currently supported for new data

• direction (str) – ‘lab2crystal’ or ‘crystal2lab’

classmethod from_matrix(matrix, symmetry=None)

Creates orientation(s) from orientation matrices [RRR+15].

Parameters
• matrix (array_like) – Array of orientation matrices.

• symmetry (Symmetry, optional) – Symmetry of orientation(s). If None (default), no symmetry is set.

classmethod from_neo_euler(neo_euler, symmetry=None)

Creates orientation(s) from a neo-euler (vector) representation.

Parameters
• neo_euler (NeoEuler) – Vector parametrization of orientation(s).

• symmetry (Symmetry, optional) – Symmetry of orientation(s). If None (default), no symmetry is set.

get_distance_matrix(lazy=False, chunk_size=20, progressbar=True)

The symmetry reduced smallest angle of rotation transforming each orientation in this instance to every other orientation.

This is an alternative implementation of distance() for a single Orientation instance, using dask.

Parameters
• lazy (bool, optional) – Whether to perform the computation lazily with Dask. Default is False.

• chunk_size (int, optional) – Number of orientations per axis to include in each iteration of the computation. Default is 20. Only applies when lazy is True.

• progressbar (bool, optional) – Whether to show a progressbar during computation if lazy is True. Default is True.

Return type

Scalar

Notes

Given two orientations $$g_i$$ and $$g_j$$, the smallest angle is considered as the geodesic distance

$d(g_i, g_j) = \arccos(2(g_i \cdot g_j)^2 - 1),$

where $$(g_i \cdot g_j)$$ is the highest dot product between symmetrically equivalent orientations to $$g_{i,j}$$.

in_euler_fundamental_region()

Euler angles in the fundamental Euler region of the proper subgroup.

The Euler angle ranges of each proper subgroup are given in euler_fundamental_region.

From the procedure in MTEX’ quaternion.project2EulerFR.

Returns

euler_in_region – Euler angles in radians.

Return type

numpy.ndarray

plot_unit_cell(c='tab:blue', return_figure=False, axes_length=0.5, structure=None, crystal_axes_loc='origin', **arrow_kwargs)

Plot the unit cell orientation, showing the sample and crystal reference frames.

Parameters
• c (str, optional) – Unit cell edge color.

• return_figure (bool, optional) – Return the plotted figure.

• axes_length (float, optional) – Length of the reference axes in Angstroms, by default 0.5.

• structure (diffpy.structure.Structure or None, optional) – Structure of the unit cell, only orthorhombic lattices are currently supported. If not given, a cubic unit cell with a lattice parameter of 2 Angstroms will be plotted.

• crystal_axes_loc (str, optional) – Plot the crystal reference frame axes at the “origin” (default) or “center” of the plotted cell.

• arrow_kwargs (dict, optional) – Keyword arguments passed to matplotlib.patches.FancyArrowPatch, for example “arrowstyle”.

Returns

fig – The plotted figure.

Return type

matplotlib.figure.Figure

Raises

ValueError – If self.size > 1.

scatter(projection='axangle', figure=None, position=None, return_figure=False, wireframe_kwargs=None, size=None, direction=None, **kwargs)

Plot orientations in axis-angle space, the Rodrigues fundamental zone, or an inverse pole figure (IPF) given a sample direction.

Parameters
• projection (str, optional) – Which orientation space to plot orientations in, either “axangle” (default), “rodrigues” or “ipf” (inverse pole figure).

• figure (matplotlib.figure.Figure) – If given, a new plot axis AxAnglePlot or RodriguesPlot is added to the figure in the position specified by position. If not given, a new figure is created.

• position (int, tuple of int, matplotlib.gridspec.SubplotSpec,) – optional Where to add the new plot axis. 121 or (1, 2, 1) places it in the first of two positions in a grid of 1 row and 2 columns. See add_subplot() for further details. Default is (1, 1, 1).

• return_figure (bool, optional) – Whether to return the figure. Default is False.

• wireframe_kwargs (dict, optional) – Keyword arguments passed to orix.plot.AxAnglePlot.plot_wireframe() or orix.plot.RodriguesPlot.plot_wireframe().

• size (int, optional) – If not given, all orientations are plotted. If given, a random sample of this size of the orientations is plotted.

• direction (Vector3d, optional) – Sample direction to plot with respect to crystal directions. If not given, the out of plane direction, sample Z, is used. Only used when plotting IPF(s).

• kwargs – Keyword arguments passed to orix.plot.AxAnglePlot.scatter(), orix.plot.RodriguesPlot.scatter(), or orix.plot.InversePoleFigurePlot.scatter().

Returns

figure – Figure with the added plot axis, if return_figure is True.

Return type

matplotlib.figure.Figure

set_symmetry(symmetry)

[Deprecated] Assign a symmetry to this orientation.

Computes equivalent transformations which have the smallest angle of rotation and assigns these in-place.

Parameters

symmetry (Symmetry) –

Returns

The instance itself, with equivalent values.

Return type

Orientation

Examples

>>> from orix.quaternion.symmetry import C4
>>> data = np.array([[0.5, 0.5, 0.5, 0.5], [0, 1, 0, 0]])
>>> o = Orientation(data).set_symmetry(C4)
>>> o
Orientation (2,) 4
[[-0.7071  0.     -0.7071  0.    ]
[ 0.      1.      0.      0.    ]]


Notes

Deprecated since version 0.8: Function set_symmetry() is deprecated and will be removed in version 0.9. Use orix.quaternion.Orientation.map_into_symmetry_reduced_zone() instead.

property symmetry

Symmetry.

property unit

Unit orientations.

#### Misorientation¶

 distance([verbose, split_size]) Symmetry reduced distance. equivalent([grain_exchange]) Equivalent misorientations. set_symmetry(Gl, Gr[, verbose]) [Deprecated] Assign symmetries to this misorientation. transpose(*axes) Returns a new object containing the same data transposed.
class orix.quaternion.Misorientation(data, symmetry=None)

Misorientation object.

Misorientations represent transformations from one orientation, $$o_1$$ to another, $$o_2$$: $$o_2 \cdot o_1^{-1}$$.

They have symmetries associated with each of the starting orientations.

distance(verbose=False, split_size=100)

Symmetry reduced distance.

Compute the shortest distance between all orientations considering symmetries.

Parameters
• verbose (bool) – Output progress bar while computing. Default is False.

• split_size (int) – Size of block to compute at a time. Default is 100.

Returns

distance – 2D matrix containing the angular distance between every orientation, considering symmetries.

Return type

numpy.ndarray

Examples

>>> import numpy as np
>>> from orix.quaternion import Misorientation, symmetry
>>> data = np.array([[0.5, 0.5, 0.5, 0.5], [0, 1, 0, 0]])
>>> m = Misorientation(data)
>>> m.symmetry = (symmetry.C4, symmetry.C2)
>>> m = m.map_into_symmetry_reduced_zone()
>>> m.distance()
array([[3.14159265, 1.57079633],
[1.57079633, 0.        ]])

equivalent(grain_exchange=False)

Equivalent misorientations.

grain_exchangebool

If True the rotation $g$ and $g^{-1}$ are considered to be identical. Default is False.

Return type

Misorientation

flatten()

A new object with the same data in a single column.

map_into_symmetry_reduced_zone(verbose=False)

Computes equivalent transformations which have the smallest angle of rotation and return these as a new Misorientation object.

Returns

A new misorientation object with the assigned symmetry.

Return type

Misorientation

Examples

>>> from orix.quaternion.symmetry import C4, C2
>>> data = np.array([[0.5, 0.5, 0.5, 0.5], [0, 1, 0, 0]])
>>> m = Misorientation(data)
>>> m.symmetry = (C4, C2)
>>> m.map_into_symmetry_reduced_zone()
Misorientation (2,) 4, 2
[[-0.7071  0.7071  0.      0.    ]
[ 0.      1.      0.      0.    ]]

reshape(*shape)

Returns a new object containing the same data with a new shape.

scatter(projection='axangle', figure=None, position=None, return_figure=False, wireframe_kwargs=None, size=None, **kwargs)

Plot misorientations in axis-angle space or the Rodrigues fundamental zone.

Parameters
• projection (str, optional) – Which misorientation space to plot misorientations in, either “axangle” (default) or “rodrigues”.

• figure (matplotlib.figure.Figure) – If given, a new plot axis AxAnglePlot or RodriguesPlot is added to the figure in the position specified by position. If not given, a new figure is created.

• position (int, tuple of int, matplotlib.gridspec.SubplotSpec,) – optional Where to add the new plot axis. 121 or (1, 2, 1) places it in the first of two positions in a grid of 1 row and 2 columns. See add_subplot() for further details. Default is (1, 1, 1).

• return_figure (bool, optional) – Whether to return the figure. Default is False.

• wireframe_kwargs (dict, optional) – Keyword arguments passed to orix.plot.AxAnglePlot.plot_wireframe() or orix.plot.RodriguesPlot.plot_wireframe().

• size (int, optional) – If not given, all misorientations are plotted. If given, a random sample of this size of the misorientations is plotted.

• kwargs – Keyword arguments passed to orix.plot.AxAnglePlot.scatter() or orix.plot.RodriguesPlot.scatter().

Returns

figure – Figure with the added plot axis, if return_figure is True.

Return type

matplotlib.figure.Figure

set_symmetry(Gl, Gr, verbose=False)

[Deprecated] Assign symmetries to this misorientation.

Computes equivalent transformations which have the smallest angle of rotation and assigns these in-place.

Parameters
Returns

A new misorientation object with the assigned symmetry.

Return type

Misorientation

Examples

>>> from orix.quaternion.symmetry import C4, C2
>>> data = np.array([[0.5, 0.5, 0.5, 0.5], [0, 1, 0, 0]])
>>> m = Misorientation(data).set_symmetry(C4, C2)
>>> m
Misorientation (2,) 4, 2
[[-0.7071  0.7071  0.      0.    ]
[ 0.      1.      0.      0.    ]]


Notes

Deprecated since version 0.8: Function set_symmetry() is deprecated and will be removed in version 0.9. Use orix.quaternion.Misorientation.map_into_symmetry_reduced_zone() instead.

squeeze()

Returns a new object with length one dimensions removed.

property symmetry

Tuple of Symmetry.

transpose(*axes)

Returns a new object containing the same data transposed.

If ndim is originally 2, then order may be undefined. In this case the first two dimensions will be transposed.

Parameters

axes (int, optional) – The transposed axes order. Only navigation axes need to be defined. May be undefined if self only contains two navigation dimensions.

Returns

A transposed instance of the object.

Return type

obj

### OrientationRegion¶

A set of Rotation which are the normals of an orientation region.

 from_symmetry(s1[, s2]) The set of unique (mis)orientations of a symmetrical object. Suitable Rotations for the construction of a wireframe. The vertices of the asymmetric domain.
class orix.quaternion.OrientationRegion(data)

A set of Rotation which are the normals of an orientation region.

faces()
classmethod from_symmetry(s1, s2=Symmetry (1,) 1 [[1. 0. 0. 0.]])

The set of unique (mis)orientations of a symmetrical object.

Parameters
get_plot_data()

Suitable Rotations for the construction of a wireframe.

vertices()

The vertices of the asymmetric domain.

Return type

Rotation

### Quaternion¶

class orix.quaternion.Quaternion(data=None)

Basic quaternion object.

Quaternions support the following mathematical operations:

• Unary negation.

• Inversion.

• Multiplication with other quaternions and vectors.

data

The numpy array containing the quaternion data.

Type

numpy.ndarray

a, b, c, d

The individual elements of each vector.

Type

Scalar

conj

The conjugate of this quaternion $$q^* = a - bi - cj - dk$$.

Type

Quaternion

dot(other)

Dot product of this quaternion and the other as a Scalar.

dot_outer(other)

Outer dot product of this quaternion and the other as a Scalar.

mean()

Calculates the mean quaternion with unitary weights.

Notes

The method used here corresponds to Equation (13) in https://arc.aiaa.org/doi/pdf/10.2514/1.28949.

outer(other)

Compute the outer product of this quaternion and the other quaternion or vector.

Parameters
Return type
classmethod triple_cross(q1, q2, q3)

Pointwise cross product of three quaternions.

Parameters
Returns

q

Return type

orix.quaternion.Quaternion

### Rotation¶

Point transformations of objects.

Rotations are transformations of three-dimensional space leaving the origin in place. Rotations can be parametrized numerous ways, but in orix are handled as unit quaternions. Rotations can act on vectors, or other rotations, but not scalars. They are often most easily visualised as being a turn of a certain angle about a certain axis.

Rotations can also be improper. An improper rotation in orix operates on vectors as a rotation by the unit quaternion, followed by inversion. Hence, a mirroring through the x-y plane can be considered an improper rotation of 180° about the z-axis, illustrated in the figure below.

 angle_with(other) The angle of rotation transforming this rotation to the other. dot_outer(other) Scalar : the outer dot product of this rotation and the other. A new object with the same data in a single column. from_axes_angles(axes, angles) Creates rotation(s) from axis-angle pair(s). from_euler(euler[, convention, direction]) Creates a rotation from an array of Euler angles in radians. from_matrix(matrix) Creates rotations from orientation matrices [RRR+15]. from_neo_euler(neo_euler) Creates a rotation from a neo-euler (vector) representation. identity([shape]) Create identity rotations. outer(other) Compute the outer product of this rotation and the other rotation or vector. random([shape]) Uniformly distributed rotations. random_vonmises([shape, alpha, reference]) Random rotations with a simplified Von Mises-Fisher distribution. to_euler([convention]) Rotations as Euler angles [RRR+15]. Rotations as orientation matrices [RRR+15]. transpose(*axes) Returns a new object containing the same data transposed. unique([return_index, return_inverse, antipodal]) Returns a new object containing only this object's unique entries.
class orix.quaternion.Rotation(data)

Rotation object.

Rotations support the following mathematical operations:

• Unary negation.

• Inversion.

• Multiplication with other rotations and vectors.

Rotations inherit all methods from Quaternion although behaviour is different in some cases.

Rotations can be converted to other parametrizations, notably the neo-Euler representations. See NeoEuler.

property angle

The angle of rotation as a Scalar.

angle_with(other)

The angle of rotation transforming this rotation to the other.

Return type

Scalar

property antipodal

this and antipodally equivalent rotations.

Type

Rotation

property axis

The axis of rotation as a Vector3d.

dot_outer(other)

Scalar : the outer dot product of this rotation and the other.

flatten()

A new object with the same data in a single column.

classmethod from_axes_angles(axes, angles)

Creates rotation(s) from axis-angle pair(s).

Parameters
• axes (Vector3d or array_like) – The axis of rotation.

• angles (array_like) – The angle of rotation, in radians.

Return type

Rotation

Examples

>>> import numpy as np
>>> from orix.quaternion import Rotation
>>> rot = Rotation.from_axes_angles((0, 0, -1), np.pi / 2)
>>> rot
Rotation (1,)
[[ 0.7071  0.      0.     -0.7071]]

classmethod from_euler(euler, convention='bunge', direction='crystal2lab')

Creates a rotation from an array of Euler angles in radians.

Parameters
• euler (array-like) – Euler angles in radians in the Bunge convention.

• convention (str) – “bunge” or “MTEX”

• direction (str) – “lab2crystal” or “crystal2lab”, ignored if “MTEX” convention is in use

classmethod from_matrix(matrix)

Creates rotations from orientation matrices [RRR+15].

Parameters

matrix (array_like) – Array of orientation matrices.

Examples

>>> import numpy as np
>>> from orix.quaternion import Rotation
>>> r = Rotation.from_matrix(np.eye(3))
>>> np.allclose(r.data, [1, 0, 0, 0])
True
>>> r = Rotation.from_matrix(np.diag([1, -1, -1]))
>>> np.allclose(r.data, [0, 1, 0, 0])
True

classmethod from_neo_euler(neo_euler)

Creates a rotation from a neo-euler (vector) representation.

Parameters

neo_euler (NeoEuler) – Vector parametrization of a rotation.

classmethod identity(shape=(1,))

Create identity rotations.

Parameters

shape (tuple) – The shape out of which to construct identity quaternions.

property improper

True for improper rotations and False otherwise.

Type

ndarray

outer(other)

Compute the outer product of this rotation and the other rotation or vector.

Parameters

other (Rotation or Vector3d) –

Return type
classmethod random(shape=(1,))

Uniformly distributed rotations.

Parameters

shape (int or tuple of int, optional) – The shape of the required object.

classmethod random_vonmises(shape=(1,), alpha=1.0, reference=(1, 0, 0, 0))

Random rotations with a simplified Von Mises-Fisher distribution.

Parameters
• shape (int or tuple of int, optional) – The shape of the required object.

• alpha (float) – Parameter for the VM-F distribution. Lower values lead to “looser” distributions.

• reference (Rotation) – The center of the distribution.

to_euler(convention='bunge')

Rotations as Euler angles [RRR+15].

Parameters

convention (str, optional) – The Euler angle convention used. Only “bunge” is supported.

Returns

Array of Euler angles in radians, in the ranges $$\phi_1 \in [0, 2\pi]$$, $$\Phi \in [0, \pi]$$, and $$\phi_1 \in [0, 2\pi]$$.

Return type

ndarray

to_matrix()

Rotations as orientation matrices [RRR+15].

Returns

Array of orientation matrices.

Return type

ndarray

Examples

>>> import numpy as np
>>> from orix.quaternion.rotation import Rotation
>>> r = Rotation([1, 0, 0, 0])
>>> np.allclose(r.to_matrix(), np.eye(3))
True
>>> r = Rotation([0, 1, 0, 0])
>>> np.allclose(r.to_matrix(), np.diag([1, -1, -1]))
True

unique(return_index=False, return_inverse=False, antipodal=True)

Returns a new object containing only this object’s unique entries.

Two rotations are not unique if they have the same propriety AND:

• they have the same numerical value OR

• the numerical value of one is the negative of the other

Parameters
• return_index (bool, optional) – If True, will also return the indices of the (flattened) data where the unique entries were found.

• return_inverse (bool, optional) – If True, will also return the indices to reconstruct the (flattened) data from the unique data.

• antipodal (bool, optional) – If False, rotations representing the same transformation whose values are numerically different (negative) will not be considered unique.

### Symmetry¶

Collections of transformations representing a symmetry group.

An object’s symmetry can be characterized by the transformations relating symmetrically-equivalent views on that object. Consider the following shape.

This obviously has three-fold symmetry. If we rotated it by $$\frac{2}{3}\pi$$ or $$\frac{4}{3}\pi$$, the image would be unchanged. These angles, as well as $$0$$, or the identity, expressed as quaternions, form a group. Applying any operation in the group to any other results in another member of the group.

Symmetries can consist of rotations or inversions, expressed as improper rotations. A mirror symmetry is equivalent to a 2-fold rotation combined with inversion.

 from_generators(*generators) Create a Symmetry from a minimum list of generating transformations.
class orix.quaternion.Symmetry(data)

The set of rotations comprising a point group.

property contains_inversion

Whether this group contains inversion as a bool.

Diads of this symmetry as a set of Vector3d.

property euler_fundamental_region

Fundamental Euler angle region of the proper subgroup.

Returns

region – Maximum Euler angles $$(\phi_{1, max}, \Phi_{max}, \phi_{2, max})$$ in degrees. No symmetry is assumed if the proper subgroup name is not recognized.

Return type

tuple

classmethod from_generators(*generators)

Create a Symmetry from a minimum list of generating transformations.

Parameters

generators (Rotation) – An arbitrary list of constituent transformations.

Return type

Symmetry

Examples

Combining a 180° rotation about [1, -1, 0] with a 4-fold rotoinversion axis along [0, 0, 1]

>>> myC2 = Symmetry([(1, 0, 0, 0), (0, 0.75**0.5, -0.75**0.5, 0)])
>>> myS4 = Symmetry([(1, 0, 0, 0), (0.5**0.5, 0, 0, 0.5**0.5)])
>>> myS4.improper = [0, 1]
>>> mySymmetry = Symmetry.from_generators(myC2, myS4)
>>> mySymmetry
Symmetry (8,)
[[ 1.      0.      0.      0.    ]
[ 0.      0.7071 -0.7071  0.    ]
[ 0.7071  0.      0.      0.7071]
[ 0.      0.     -1.      0.    ]
[ 0.      1.      0.      0.    ]
[-0.7071  0.      0.      0.7071]
[ 0.      0.      0.      1.    ]
[ 0.     -0.7071 -0.7071  0.    ]]

property fundamental_sector

FundamentalSector describing the inverse pole figure given by the point group name.

These sectors are taken from MTEX’ crystalSymmetry.fundamentalSector.

fundamental_zone()
get_axis_orders()
get_highest_order_axis()
property is_proper

Whether this group contains only proper rotations as bool.

property laue

This group plus inversion as a Symmetry.

property laue_proper_subgroup

The proper subgroup of this group plus inversion as a Symmetry.

name = ''
property order

Number of elements of the group as int.

property proper_subgroup

The largest proper group of this subgroup as a Symmetry.

property proper_subgroups

List of proper groups that are subgroups of this group as a list of Symmetry.

property subgroups

List groups that are subgroups of this group as a list of Symmetry.

property system

Which of the seven crystal systems this symmetry belongs to.

Returns

None is returned if the symmetry name is not recognized.

Return type

str or None

Other functions

orix.quaternion.symmetry.get_distinguished_points(s1, s2=Symmetry (1,) 1 [[1. 0. 0. 0.]])

Points symmetrically equivalent to identity with respect to s1 and s2.

Parameters
Return type

Rotation

orix.quaternion.symmetry.get_point_group(space_group_number, proper=False)

Maps a space group number to its (proper) point group.

Parameters
• space_group_number (int) – Between 1 and 231.

• proper (bool, optional) – Whether to return the point group with proper rotations only (True), or just the point group (False). Default is False.

Returns

point_group – One of the 11 proper or 32 point groups.

Return type

orix.quaternion.symmetry.Symmetry

Examples

>>> from orix.quaternion.symmetry import get_point_group
>>> pgOh = get_point_group(225)
>>> pgOh.name
'm-3m'
>>> pgO = get_point_group(225, proper=True)
>>> pgO.name
'432'


## sampling¶

 get_sample_fundamental([resolution, ...]) Generates an equispaced grid of rotations within a fundamental zone. get_sample_local([resolution, center, ...]) Generates a grid of rotations about a given rotation. uniform_SO3_sample(resolution[, method, unique]) Uniform sampling of SO(3) by a number of methods. sample_S2_uv_mesh(resolution) Vectors of a UV mesh on a unit sphere S2.

Generation of grids on S2 or SO(3) (rotation space).

orix.sampling.get_sample_fundamental(resolution=2, point_group=None, space_group=None, method='cubochoric', **kwargs)

Generates an equispaced grid of rotations within a fundamental zone.

Parameters
• resolution (float, optional) – The characteristic distance between a rotation and its neighbour in degrees.

• point_group (orix.quaternion.Symmetry, optional) – One of the 11 proper point groups. If not given, space_group must be.

• space_group (int, optional) – Between 1 and 231. Must be given if point_group is not.

• method (str, optional) – “cubochoric” (default), “haar_euler”, or, “quaternion”. See uniform_SO3_sample() for details.

• kwargs – Keyword arguments passed on to the sampling method.

Returns

rot – Grid of rotations lying within the specified fundamental zone.

Return type

Rotation

Examples

>>> from orix.quaternion.symmetry import C2
>>> from orix.sampling import get_sample_fundamental
>>> rot = get_sample_fundamental(1, point_group=C2)

orix.sampling.get_sample_local(resolution=2, center=None, grid_width=10, method='cubochoric', **kwargs)

Generates a grid of rotations about a given rotation.

Parameters
• resolution (float, optional) – The characteristic distance between a rotation and its neighbour in degrees.

• center (Rotation, optional) – The rotation at which the grid is centered. The identity is used if not given.

• grid_width (float, optional) – The largest angle of rotation in degrees away from center that is acceptable.

• method (str, optional) – “cubochoric”, “haar_euler”, or “quaternion”. See uniform_SO3_sample() for details.

• kwargs – Keyword arguments passed on to the sampling method.

Returns

r – Grid of rotations lying within grid_width of center.

Return type

Rotation

orix.sampling.sample_S2_cube_mesh(resolution, grid_type='spherified_corner')

Vectors of a cube mesh on a unit sphere S2.

Taken from diffsims.

Parameters
• resolution (float) – Maximum angle between neighbour grid points, in degrees.

• grid_type (str) – Type of cube grid: “normalized”, “spherified_edge” or “spherified_corner” (default).

Return type

Vector3d

orix.sampling.sample_S2_uv_mesh(resolution)

Vectors of a UV mesh on a unit sphere S2.

The mesh vertices are defined by the parametrization

$\begin{split}x &= \sin(u)\cos(v), \\ y &= \sin(u)\sin(v), \\ z &= \cos(u).\end{split}$

Taken from diffsims.

Parameters

resolution (float) – Maximum angle between nearest neighbour grid points, in degrees. The resolution of $$u$$ and $$v$$ are rounded up to get an integer number of equispaced polar and azimuthal grid lines.

Return type

Vector3d

orix.sampling.uniform_SO3_sample(resolution, method='cubochoric', unique=True, **kwargs)

Uniform sampling of SO(3) by a number of methods.

Parameters
• resolution (float) – Desired characteristic distance between a rotation and its neighbour in degrees.

• method (str) – Sampling method, among “cubochoric” (default), “haar_euler”, or “quaternion”. See Notes for details on each method.

• unique (bool) – Whether only unique rotations are returned, default is True.

• kwargs – Keyword arguments passed on to the sampling method.

Returns

q – Grid containing appropriate rotations.

Return type

Rotation

Notes

The “cubochoric” algorithm is presented in and . It is used in both EMsoft and Dream3D to sample SO(3). The method accepts the parameter semi_edge_steps (N in EMsoft) as an alternative to resolution, which is the number of grid points N along the semi-edge of the cubochoric cube.

The sample from the “haar_euler” algorithm is proportional to $$\cos(\beta) d\alpha \: d\beta \: d\gamma$$. See for example: https://math.stackexchange.com/questions/3316481/.

The “quaternion” algorithm has a fairly light footprint on the internet, it’s implemented as described in [LaV06], the ‘gem’ on which it is based can be found at [Kir95] and has a reference [Sho92].

## scalar¶

Dimensionless quantities.

As well as themselves representing physical quantities, Scalars may represent elements of higher-dimensional quantities, such as the x-component of a vector or the rotation angle of a quaternion.

class orix.scalar.Scalar(data)

Scalar base class.

Scalars currently support the following mathematical operations:

• Unary negation.

• Addition to other scalars, numerical types, and array_like objects.

• Subtraction to the above.

• Multiplication to the above.

• Element-wise boolean comparisons (==, < etc).

• Unary exponentiation.

flatten()

Scalar : A new object with the same data in a single column.

reshape(*args)

Returns a new Scalar containing the same data with a new shape.

property shape

Tuple of the shape of the Scalar.

Return type

tuple

## vector¶

Three-dimensional quantities.

Vectors can represent positions in three-dimensional space and are also commonly associated with motion, possessing both a magnitude and a direction. In orix they are often encountered as derived objects such as the rotation axis of a quaternion or the normal to the bounding planes of a spherical region.

 AxAngle([data]) The simplest neo-Eulerian representation. FundamentalSector([data]) Fundamental sector for a symmetry in the inverse pole figure, defined by a set of sector normals. Homochoric([data]) Equal-volume mapping of the unit quaternion hemisphere. Miller([xyz, uvw, UVTW, hkl, hkil, phase]) Direct crystal lattice vectors (uvw or UVTW) and reciprocal crystal lattice vectors (hkl or hkil), the latter known as Miller indices, describing directions with respect to the crystal reference frame defined by a phase's crystal lattice and symmetry. Rodrigues([data]) In Rodrigues space, straight lines map to rotations about a fixed axis. SphericalRegion([data]) A set of vectors representing normals segmenting a sphere. Vector3d([data]) Vector base class.

### AxAngle¶

 from_axes_angles(axes, angles) Create new AxAngle object explicitly from the given axes and angles.
class orix.vector.AxAngle(data=None)

Bases: orix.vector.neo_euler.NeoEuler

The simplest neo-Eulerian representation.

The Axis-Angle vector representing a rotation with rotation angle $$\theta$$ has magnitude $$\theta$$

property angle

the angle of rotation.

Type

Scalar

classmethod from_axes_angles(axes, angles)

Create new AxAngle object explicitly from the given axes and angles.

Parameters
• axes (Vector3d or array_like) – The axis of rotation.

• angles (array_like) – The angle of rotation, in radians.

Return type

AxAngle

classmethod from_rotation(rotation)

NeoEuler : Create a new vector from the given rotation.

### FundamentalSector¶

class orix.vector.FundamentalSector(data=None)

Fundamental sector for a symmetry in the inverse pole figure, defined by a set of sector normals.

property center

Center vector of the fundamental sector.

Taken from MTEX’ sphericalRegion.center.

property edges

Unit vectors which delineates the region in the stereographic projection.

They are sorted in the counter-clockwise direction around the sector center in the stereographic projection.

The first edge is repeated at the end. This is done so that orix.plot.StereographicPlot.plot() draws bounding lines without gaps.

property vertices

### Homochoric¶

class orix.vector.Homochoric(data=None)

Bases: orix.vector.neo_euler.NeoEuler

Equal-volume mapping of the unit quaternion hemisphere.

The homochoric vector representing a rotation with rotation angle $$\theta$$ has magnitude $$\left[\frac{3}{4}(\theta - \sin\theta)\right]^{\frac{1}{3}}$$.

Notes

The homochoric transformation has no analytical inverse.

property angle

the angle of rotation.

Type

Scalar

classmethod from_rotation(rotation)

NeoEuler : Create a new vector from the given rotation.

### Miller¶

 angle_with(other[, use_symmetry]) Calculate angles between vectors in self and other, possibly using symmetrically equivalent vectors to find the smallest angle under symmetry. cross(other) Cross product of a direct or reciprocal lattice vector with another vector, which is considered the zone axis between the vectors. dot(other) Dot product of a vector with another vector. dot_outer(other) Outer dot product of a vector with another vector. Return a deepcopy of the instance. draw_circle([projection, figure, ...]) Draw great or small circles with a given opening_angle to to the vectors in the stereographic projection. Returns a new object with the same data in a single column. from_highest_indices(phase[, uvw, hkl]) Create a set of unique direct or reciprocal lattice vectors from three highest indices and a phase (crystal lattice and symmetry). from_min_dspacing(phase[, min_dspacing]) Create a set of unique reciprocal lattice vectors with a a direct space interplanar spacing greater than a lower threshold. get_circle([opening_angle, steps]) Get vectors delineating great or small circle(s) with a given opening_angle about each vector. mean([use_symmetry]) Mean vector of the set of vectors. reshape(*shape) Returns a new object containing the same data with a new shape. round([max_index]) Round a set of index triplet (Miller) or quartet (Miller-Bravais/Weber) to the closest smallest integers. rotate([axis, angle]) Convenience function for rotating this vector. scatter([projection, figure, axes_labels, ...]) Plot vectors in the stereographic projection. symmetrise([unique, return_multiplicity, ...]) Vectors symmetrically equivalent to the ones in self. transpose(*axes) Returns a new Miller object containing the same data transposed. unique([use_symmetry, return_index]) Unique vectors in self.
class orix.vector.Miller(xyz=None, uvw=None, UVTW=None, hkl=None, hkil=None, phase=None)

Direct crystal lattice vectors (uvw or UVTW) and reciprocal crystal lattice vectors (hkl or hkil), the latter known as Miller indices, describing directions with respect to the crystal reference frame defined by a phase’s crystal lattice and symmetry.

__init__(xyz=None, uvw=None, UVTW=None, hkl=None, hkil=None, phase=None)

Create a set of direct lattice vectors (uvw or UVTW) or reciprocal lattice vectors (hkl or hkil) describing directions with respect to a crystal reference frame defined by a phase’s crystal lattice and symmetry.

Exactly one of xyz, uvw, UVTW, hkl, or hkil must be passed.

The vectors are stored internally as cartesian coordinates in the data attribute.

Parameters
• xyz (numpy.ndarray, list, or tuple, optional) – Vector(s) given in cartesian coordinates. Default is None.

• uvw (numpy.ndarray, list, or tuple, optional) – Indices of direct lattice vector(s). Default is None.

• UVTW (numpy.ndarray, list, or tuple, optional) – Indices of direct lattice vector(s), often preferred over uvw in trigonal and hexagonal lattices. Default is None.

• hkl (numpy.ndarray, list, or tuple, optional) – Indices of reciprocal lattice vector(s). Default is None.

• hkil (numpy.ndarray, list, or tuple, optional) – Indices of reciprocal lattice vector(s), often preferred over hkl in trigonal and hexagonal lattices. Default is None.

• phase (orix.crystal_map.Phase, optional) – A phase with a crystal lattice and symmetry. Must be passed whenever direct or reciprocal lattice vectors are created.

Notes

The Miller-Bravais indices $$UVTW$$ are defined as

$\begin{split}U &= \frac{2u - v}{3}, \\ V &= \frac{2v - u}{3}, \\ T &= -\frac{u + v}{3}, \\ W &= w.\end{split}$
property T

Third direct lattice vector index in 4-index Weber symbols, equal to $$-(u + v)/3$$.

property U

First direct lattice vector index in 4-index Weber symbols, equal to $$(2u - v)/(3)$$.

property UVTW

Direct lattice vectors expressed as 4-index Weber symbols. They are defined as

$\begin{split}U &= \frac{2u - v}{3}, \\ V &= \frac{2v - u}{3}, \\ T &= -\frac{u + v}{3}, \\ W &= w.\end{split}$
property V

Second direct lattice vector index in 4-index Weber symbols, equal to $$(2v - u)/3$$.

property W

Fourth direct lattice vector index in 4-index Weber symbols, equal to $$w$$.

angle_with(other, use_symmetry=False)

Calculate angles between vectors in self and other, possibly using symmetrically equivalent vectors to find the smallest angle under symmetry.

Vectors must have compatible shapes, and be in the same space (direct or recprocal) and crystal reference frames.

Parameters
• other (Vector3d or Miller) –

• use_symmetry (bool, optional) – Whether to consider equivalent vectors to find the smallest angle under symmetry. Default is False.

Returns

The angle between the vectors, in radians.

Return type

Scalar

property coordinate_format

Vector coordinate format, either “xyz”, “uvw”, “UVTW”, “hkl”, or “hkil”.

property coordinates

Vector coordinates.

cross(other)

Cross product of a direct or reciprocal lattice vector with another vector, which is considered the zone axis between the vectors.

Vectors must have compatible shapes, and be in the same space (direct or recprocal) and crystal reference frames.

Returns

Vectors in reciprocal (direct) space if direct (reciprocal) vectors are crossed.

Return type

Miller

deepcopy()

Return a deepcopy of the instance.

dot(other)

Dot product of a vector with another vector.

Vectors must have compatible shapes, and be in the same space (direct or recprocal) and crystal reference frames.

Return type

Scalar

dot_outer(other)

Outer dot product of a vector with another vector.

Vectors must be in the same space (direct or recprocal) and crystal reference frames.

The dot product for every combination of vectors in self and other is computed.

Return type

Scalar

flatten()

Returns a new object with the same data in a single column.

classmethod from_highest_indices(phase, uvw=None, hkl=None)

Create a set of unique direct or reciprocal lattice vectors from three highest indices and a phase (crystal lattice and symmetry).

Parameters
classmethod from_min_dspacing(phase, min_dspacing=0.05)

Create a set of unique reciprocal lattice vectors with a a direct space interplanar spacing greater than a lower threshold.

Parameters
• phase (orix.crystal_map.Phase) – A phase with a crystal lattice and symmetry.

• min_dspacing (float, optional) – Smallest interplanar spacing to consider. Default is 0.05, in the unit used to define the lattice parameters in phase.

get_nearest()

NotImplemented.

property h

First reciprocal lattice vector index.

property hkil

Reciprocal lattice vectors expressed as 4-index Miller-Bravais indices.

property hkl

Reciprocal lattice vectors.

property i

Third reciprocal lattice vector index in 4-index Miller-Bravais indices, equal to $$-(h + k)$$.

property is_hexagonal

Whether the crystal reference frame is hexagonal/trigonal or not.

property k

Second reciprocal lattice vector index.

property l

Third reciprocal lattice vector index, or fourth index in 4-index Miller Bravais indices.

property length

Length of each vector given in lattice parameter units if the coordinate_format attribute equals “uvw” or “UVTW”, and inverse lattice parameter units if the attribute equals “hkl” or “hkil”. If the attribute equals “xyz”, the norms of the vectors in data are returned.

mean(use_symmetry=False)

Mean vector of the set of vectors.

property multiplicity

Number of symmetrically equivalent directions per vector.

reshape(*shape)

Returns a new object containing the same data with a new shape.

round(max_index=20)

Round a set of index triplet (Miller) or quartet (Miller-Bravais/Weber) to the closest smallest integers.

Parameters

max_index (int) – Maximum integer index to round to, by default 20.

Returns

Rounded set of index triplet(s) or quartet(s).

Return type

Miller

property space

Whether the vector is in “direct” or “reciprocal” space.

symmetrise(unique=False, return_multiplicity=False, return_index=False)

Vectors symmetrically equivalent to the ones in self.

Parameters
• unique (bool, optional) – Whether to return only unique vectors. Default is False.

• return_multiplicity (bool, optional) – Whether to return the multiplicity of each vector. Default is False.

• return_index (bool, optional) – Whether to return the index into self for the returned symmetrically equivalent vectors. Default is False.

Returns

• Miller – Flattened symmetrically equivalent vectors.

• multiplicity (numpy.ndarray) – Multiplicity of each vector. Returned if return_multiplicity is True.

• idx (numpy.ndarray) – Index into self for the symmetrically equivalent vectors. Returned if return_index is True.

transpose(*axes)

Returns a new Miller object containing the same data transposed.

If ndim is originally 2, then order may be undefined. In this case the first two dimensions will be transposed.

Parameters

axes (int, optional) – The transposed axes order. Only navigation axes need to be defined. May be undefined if self only contains two navigation dimensions.

Returns

A transposed Miller instance of the object.

Return type

Miller

property u

First direct lattice vector index.

unique(use_symmetry=False, return_index=False)

Unique vectors in self.

Parameters
• use_symmetry (bool, optional) – Whether to consider equivalent vectors to compute the unique vectors. Default is False.

• return_index (bool, optional) – Whether to return the indices of the (flattened) data where the unique entries were found. Default is False.

Returns

• Miller – Flattened unique vectors.

• idx (numpy.ndarray) – Indices of the unique data in the (flattened) array.

property unit

Unit vectors.

property uvw

Direct lattice vectors.

property v

Second direct lattice vector index.

property w

Third direct lattice vector index.

### Rodrigues¶

class orix.vector.Rodrigues(data=None)

Bases: orix.vector.neo_euler.NeoEuler

In Rodrigues space, straight lines map to rotations about a fixed axis.

The Rodrigues vector representing a rotation with rotation angle $$\theta$$ has magnitude $$\tan\frac{\theta}{2}$$.

property angle

the angle of rotation.

Type

Scalar

classmethod from_rotation(rotation)

NeoEuler : Create a new vector from the given rotation.

### SphericalRegion¶

Vectors describing a segment of a sphere.

Each entry represents a plane normal in 3-d. Vectors can lie in, on, or outside the spherical region.

Examples

>>> sr = SphericalRegion([0, 0, 1])  # Region above the x-y plane
>>> v = Vector3d([(0, 0, 1), (0, 0, -1), (1, 0, 0)])
>>> v < sr
array([ True, False, False], dtype=bool)
>>> v <= sr
array([ True, False,  True], dtype=bool)

class orix.vector.SphericalRegion(data=None)

A set of vectors representing normals segmenting a sphere.

### Vector3d¶

 angle_with(other) Calculate the angles between these vectors in other vectors. cross(other) The cross product of a vector with another vector. dot(other) The dot product of a vector with another vector. dot_outer(other) The outer dot product of a vector with another vector. draw_circle([projection, figure, ...]) Draw great or small circles with a given opening_angle to to the vectors in the stereographic projection. from_polar(azimuth, polar[, radial]) Create a Vector3d from spherical coordinates according to the ISO 31-11 standard [SphericalWolfram]. get_circle([opening_angle, steps]) Get vectors delineating great or small circle(s) with a given opening_angle about each vector. get_nearest(x[, inclusive, tiebreak]) The vector among x with the smallest angle to this one. in_fundamental_sector(symmetry) Project vectors to a symmetry's fundamental sector (inverse pole figure). rotate([axis, angle]) Convenience function for rotating this vector. scatter([projection, figure, axes_labels, ...]) Plot vectors in the stereographic projection. Return the azimuth $$\phi$$, polar $$\theta$$, and radial $$r$$ spherical coordinates, the angles in radians. transpose(*axes) Returns a new object containing the same data transposed. Vector3d : a single unit vector parallel to the x-direction. Vector3d : a single unit vector parallel to the y-direction. Vector3d : a single unit vector parallel to the z-direction. zero([shape]) Returns zero vectors in the specified shape.
class orix.vector.Vector3d(data=None)

Vector base class.

Vectors support the following mathematical operations:

• Unary negation.

• Addition to other vectors, scalars, numbers, and compatible array-like objects.

• Subtraction to and from the above.

• Multiplication to scalars, numbers, and compatible array-like objects.

• Division by the same as multiplication. Division by a vector is not defined in general.

Examples

>>> import numpy as np
>>> from orix.vector import Vector3d
>>> v = Vector3d((1, 2, 3))
>>> w = Vector3d(np.array([[1, 0, 0], [0, 1, 1]]))
>>> w.x
Scalar (2,)
[1 0]
>>> v.unit
Vector3d (1,)
[[ 0.2673  0.5345  0.8018]]
>>> -v
Vector3d (1,)
[[-1 -2 -3]]
>>> v + w
Vector3d (2,)
[[2 2 3]
[1 3 4]]
>>> w - (2, -3)
Vector3d (2,)
[[-1 -2 -2]
[ 3  4  4]]
>>> 3 * v
Vector3d (1,)
[[3 6 9]]
>>> v / 2
Vector3d (1,)
[[0.5 1.0 1.5]]
>>> v / (2, -2)
Vector3d (1,)
[[0.5 1.0 1.5]
[-0.5 -1.0 -1.5]]

angle_with(other)

Calculate the angles between these vectors in other vectors.

Vectors must have compatible shapes for broadcasting to work.

Returns

The angle between the vectors, in radians.

Return type

Scalar

property azimuth

Azimuth spherical coordinate, i.e. the angle $$\phi \in [0, 2\pi]$$ from the positive z-axis to a point on the sphere, according to the ISO 31-11 standard [SphericalWolfram].

Return type

Scalar

cross(other)

The cross product of a vector with another vector.

Vectors must have compatible shape for broadcasting to work.

Returns

The class of ‘other’ is preserved.

Return type

Vector3d

Examples

>>> v = Vector3d(((1, 0, 0), (-1, 0, 0)))
>>> w = Vector3d((0, 1, 0))
>>> v.cross(w)
Vector3d (2,)
[[ 0  0  1]
[ 0  0 -1]]

dim = 3

The number of dimensions for this object.

Type

int

dot(other)

The dot product of a vector with another vector.

Vectors must have compatible shape.

Return type

Scalar

Examples

>>> v = Vector3d((0, 0, 1.0))
>>> w = Vector3d(((0, 0, 0.5), (0.4, 0.6, 0)))
>>> v.dot(w)
Scalar (2,)
[ 0.5  0. ]
>>> w.dot(v)
Scalar (2,)
[ 0.5  0. ]

dot_outer(other)

The outer dot product of a vector with another vector.

The dot product for every combination of vectors in self and other is computed.

Return type

Scalar

Examples

>>> v = Vector3d(((0.0, 0.0, 1.0), (1.0, 0.0, 0.0)))  # shape = (2, )
>>> w = Vector3d(((0.0, 0.0, 0.5), (0.4, 0.6, 0.0), (0.5, 0.5, 0.5)))  # shape = (3, )
>>> v.dot_outer(w)
Scalar (2, 3)
[[ 0.5  0.   0.5]
[ 0.   0.4  0.5]]
>>> w.dot_outer(v)  # shape = (3, 2)
Scalar (3, 2)
[[ 0.5  0. ]
[ 0.   0.4]
[ 0.5  0.5]]

draw_circle(projection='stereographic', figure=None, opening_angle=1.5707963267948966, steps=100, axes_labels=None, hemisphere=None, show_hemisphere_label=None, grid=None, grid_resolution=None, figure_kwargs=None, return_figure=False, **kwargs)

Draw great or small circles with a given opening_angle to to the vectors in the stereographic projection.

A vector must be present in the current hemisphere for its circle to be drawn.

Parameters
• projection (str, optional) – Which projection to use. The default is “stereographic”, the only current option.

• figure (matplotlib.figure.Figure, optional) – Which figure to plot onto. Default is None, which creates a new figure.

• opening_angle (float or numpy.ndarray, optional) – Opening angle(s) around the vector(s). Default is $$\pi/2$$, giving a great circle. If an array is passed, its size must be equal to the number of vectors.

• steps (int, optional) – Number of vectors to describe each circle, default is 100.

• axes_labels (list of str, optional) – Reference frame axes labels, defaults to [None, None, None].

• hemisphere (str, optional) – Which hemisphere(s) to plot the vectors in, defaults to “None”, which means “upper” if a new figure is created, otherwise adds to the current figure’s hemispheres. Options are “upper”, “lower”, and “both”, which plots two projections side by side.

• show_hemisphere_label (bool, optional) – Whether to show hemisphere labels “upper” or “lower”. Default is True if hemisphere is “both”, otherwise False.

• grid (bool, optional) – Whether to show the azimuth and polar grid. Default is whatever axes.grid is set to in matplotlib.rcParams.

• grid_resolution (tuple, optional) – Azimuth and polar grid resolution in degrees, as a tuple. Default is whatever is default in stereographic_grid.

• figure_kwargs (dict, optional) – Dictionary of keyword arguments passed to matplotlib.pyplot.subplots().

• return_figure (bool, optional) – Whether to return the figure (default is False).

• kwargs – Keyword arguments passed to matplotlib.axes.Axes.plot() to alter the circles’ appearance.

Returns

fig – The created figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

Notes

This is a somewhat customizable convenience method which creates a figure with axes using StereographicPlot, however, it is meant for quick plotting and prototyping. This figure and the axes can also be created using Matplotlib directly, which is more customizable.

Create a Vector3d from spherical coordinates according to the ISO 31-11 standard [SphericalWolfram].

Parameters
• azimuth (array_like) – The azimuth angle, in radians.

• polar (array_like) – The polar angle, in radians.

• radial (array_like) – The radial distance. Defaults to 1 to produce unit vectors.

Return type

Vector3d

References

SphericalWolfram(1,2,3,4,5,6,7,8,9,10,11,12)

Weisstein, Eric W. “Spherical Coordinates,” From MathWorld–A Wolfram Web Resource, url: https://mathworld.wolfram.com/SphericalCoordinates.html

get_circle(opening_angle=1.5707963267948966, steps=100)

Get vectors delineating great or small circle(s) with a given opening_angle about each vector.

Used for plotting plane traces in stereographic projections.

Parameters
• opening_angle (float or numpy.ndarray, optional) – Opening angle(s) around the vector(s). Default is $$\pi/2$$, giving a great circle. If an array is passed, its size must be equal to the number of vectors.

• steps (int, optional) – Number of vectors to describe each circle, default is 100.

Returns

circles – Vectors delineating circles with the opening_angle about the vectors.

Return type

Vector3d

Notes

A set of steps number of vectors equal to each vector is rotated twice to obtain a circle: (1) About a perpendicular vector to the current vector at opening_angle and (2) about the current vector in a full circle.

get_nearest(x, inclusive=False, tiebreak=None)

The vector among x with the smallest angle to this one.

Parameters
• x (Vector3d) –

• inclusive (bool) – if False (default) vectors exactly parallel to this will not be considered.

• tiebreak (Vector3d) – If multiple vectors are equally close to this one, tiebreak will be used as a secondary comparison. By default equal to (0, 0, 1).

Return type

Vector3d

in_fundamental_sector(symmetry)

Project vectors to a symmetry’s fundamental sector (inverse pole figure).

This projection is taken from MTEX’ project2fundamentalRegion.

Parameters

symmetry (Symmetry) – Symmetry with a fundamental sector.

Return type

Vector3d

mean()
property perpendicular
property polar

Polar spherical coordinate, i.e. the angle $$\theta \in [0, \pi]$$ from the positive z-axis to a point on the sphere, according to the ISO 31-11 standard [SphericalWolfram].

Return type

Scalar

Radial spherical coordinate, i.e. the distance from a point on the sphere to the origin, according to the ISO 31-11 standard [SphericalWolfram].

Return type

Scalar

rotate(axis=None, angle=0)

Convenience function for rotating this vector.

Shapes of ‘axis’ and ‘angle’ must be compatible with shape of this vector for broadcasting.

Parameters
• axis (Vector3d or array_like, optional) – The axis of rotation. Defaults to the z-vector.

• angle (array_like, optional) – The angle of rotation, in radians.

Returns

A new vector with entries rotated.

Return type

Vector3d

Examples

>>> from math import pi
>>> v = Vector3d((0, 1, 0))
>>> axis = Vector3d((0, 0, 1))
>>> angles = [0, pi/4, pi/2, 3*pi/4, pi]
>>> v.rotate(axis=axis, angle=angles)

scatter(projection='stereographic', figure=None, axes_labels=None, vector_labels=None, hemisphere=None, show_hemisphere_label=None, grid=None, grid_resolution=None, figure_kwargs=None, text_kwargs=None, return_figure=False, **kwargs)

Plot vectors in the stereographic projection.

Parameters
• projection (str, optional) – Which projection to use. The default is “stereographic”, the only current option.

• figure (matplotlib.figure.Figure, optional) – Which figure to plot onto. Default is None, which creates a new figure.

• axes_labels (list of str, optional) – Reference frame axes labels, defaults to [None, None, None].

• vector_labels (list of str, optional) – Vector text labels, which by default aren’t added.

• hemisphere (str, optional) – Which hemisphere(s) to plot the vectors in, defaults to “None”, which means “upper” if a new figure is created, otherwise adds to the current figure’s hemispheres. Options are “upper”, “lower”, and “both”, which plots two projections side by side.

• show_hemisphere_label (bool, optional) – Whether to show hemisphere labels “upper” or “lower”. Default is True if hemisphere is “both”, otherwise False.

• grid (bool, optional) – Whether to show the azimuth and polar grid. Default is whatever axes.grid is set to in matplotlib.rcParams.

• grid_resolution (tuple, optional) – Azimuth and polar grid resolution in degrees, as a tuple. Default is whatever is default in stereographic_grid.

• figure_kwargs (dict, optional) – Dictionary of keyword arguments passed to matplotlib.pyplot.subplots().

• text_kwargs (dict, optional) – Dictionary of keyword arguments passed to text(), which passes these on to matplotlib.axes.Axes.text().

• return_figure (bool, optional) – Whether to return the figure (default is False).

• kwargs (dict, optional) – Keyword arguments passed to scatter(), which passes these on to matplotlib.axes.Axes.scatter().

Returns

fig – The created figure, returned if return_figure is True.

Return type

matplotlib.figure.Figure

Notes

This is a somewhat customizable convenience method which creates a figure with axes using StereographicPlot, however, it is meant for quick plotting and prototyping. This figure and the axes can also be created using Matplotlib directly, which is more customizable.

to_polar()

Return the azimuth $$\phi$$, polar $$\theta$$, and radial $$r$$ spherical coordinates, the angles in radians. The coordinates are defined as in the ISO 31-11 standard [SphericalWolfram].

Returns

Return type

Scalar

property x

This vector’s x data.

Type

Scalar

classmethod xvector()

Vector3d : a single unit vector parallel to the x-direction.

property xyz

This vector’s components, useful for plotting.

Type

tuple of ndarray

property y

This vector’s y data.

Type

Scalar

classmethod yvector()

Vector3d : a single unit vector parallel to the y-direction.

property z

This vector’s z data.

Type

Scalar

classmethod zero(shape=(1,))

Returns zero vectors in the specified shape.

Parameters

shape (tuple) –

Return type

Vector3d

classmethod zvector()

Vector3d : a single unit vector parallel to the z-direction.