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:
Crystallographic map of rotations, crystal phases and key properties associated with every spatial coordinate in a 1D, 2D or 3D space. 

Load and save utilities. 

Extensions of Matplotlib’s projections framework for plotting 

Projections of 

Fourdimensional objects. 

Module for generating grids in orientation spaces. 

Dimensionless quantities. 

Threedimensional quantities. 
base¶

class
orix.base.
Object3d
(data=None)¶ Bases:
object
Base class for 3d objects.

property
data_dim
¶ The dimensions of the data.
For example, if data has shape (4, 4, 3), data_dim is 3.
 Type

classmethod
empty
()¶ An empty object with the appropriate dimensions.

flatten
()¶ Object3d : A new object with the same data in a single column.

reshape
(*shape)¶ Returns a new object containing the same data with a new shape.

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
 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.

property
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.

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

A class to store properties with in a CrystalMap instance. 

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

A list of phases in a crystallographic map. 
Phase¶

Return a deep copy using 

class
orix.crystal_map.
Phase
(name=None, space_group=None, point_group=None, structure=None, color=None)¶ Bases:
object
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: Fm3m. point group: m3m. 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 phases to the end of a phase list, incrementing the phase IDs. 

Return a deep copy using 

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)¶ Bases:
object
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 Fm3m m3m 432 tab:blue 1 cu Fm3m m3m 432 tab:blue >>> pl["al"].structure [al 0.000000 0.000000 0.000000 1.0000]

add
(value)¶ 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.add(Phase("c", space_group=30)) >>> pl.add([Phase("d", space_group=40), Phase("e")]) >>> pl.add(PhaseList(names=["f", "g"], space_groups=[60, 70])) >>> 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_not_indexed
()¶ 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.

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 

Return an array of a class instance attribute, with values equal to 

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)¶ Bases:
object
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) – 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) >>> cm = 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
¶

get_map_data
(item, decimals=3, fill_value=None)¶ Return an array of a class instance attribute, with values equal to
False
inself.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) – How many decimals to round data point values to (default is 3).
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

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

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. 1dimensions 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

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

io¶

Load data from a supported file. 

Load 

Load 

Write data to a supported file format. 
Load and save utilities.

orix.io.
load
(filename, **kwargs)¶ 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

orix.io.
loadang
(file_string)¶ Load
.ang
files.

orix.io.
loadctf
(file_string)¶ Load
.ang
files.

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¶

orix.io.plugins.ang.
file_reader
(filename)¶ 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.
 Returns
 Return type

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 nonindexed 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.
emsoft_h5ebsd¶

orix.io.plugins.emsoft_h5ebsd.
file_reader
(filename, refined=False, **kwargs)¶ Return a
CrystalMap
object from a file in EMsoft’s dictionary indexing dot product file format. Parameters
 Returns
 Return type
orix_hdf5¶

orix.io.plugins.orix_hdf5.
atom2dict
(atom, dictionary=None)¶ Get a dictionary of one of a structure’s
diffpy.structure.Structure.atoms
content.Only values necessary to initialize an atom object are returned.

orix.io.plugins.orix_hdf5.
crystalmap2dict
(crystal_map, dictionary=None)¶ Get a dictionary from a
CrystalMap
object with data and header keys with values. Parameters
crystal_map (CrystalMap) – Crystal map.
dictionary (dict, optional) – Dictionary to update with crystal map information. If None (default), a new dictionary is created.
 Returns
dictionary – Dictionary with crystal map information.
 Return type

orix.io.plugins.orix_hdf5.
dict2atom
(dictionary)¶ Get a
diffpy.structure.Atom.atom
object from a dictionary. Parameters
dictionary (dict) – Dictionary with atom information.
 Returns
 Return type
Atom

orix.io.plugins.orix_hdf5.
dict2crystalmap
(dictionary)¶ Get a crystal map from necessary items in a dictionary.
 Parameters
dictionary (dict) – Dictionary with crystal map information.
 Returns
 Return type

orix.io.plugins.orix_hdf5.
dict2hdf5group
(dictionary, group, **kwargs)¶ Write a dictionary to datasets in a new group in an opened HDF5 file.
 Parameters
dictionary (dict) – Dataset names as keys with datasets as values.
group (Group) – HDF5 group to write dictionary to.
kwargs – Keyword arguments passed to
Group.require_dataset
.

orix.io.plugins.orix_hdf5.
dict2lattice
(dictionary)¶ Get a
diffpy.structure.Lattice
object from a dictionary. Parameters
dictionary (dict) – Dictionary with lattice information.
 Returns
 Return type
Lattice

orix.io.plugins.orix_hdf5.
dict2phase
(dictionary)¶ Get a
Phase
object from a dictionary.

orix.io.plugins.orix_hdf5.
dict2phaselist
(dictionary)¶ Get a
PhaseList
object from a dictionary.

orix.io.plugins.orix_hdf5.
dict2structure
(dictionary)¶ Get a
diffpy.structure.Structure
object from a dictionary. Parameters
dictionary (dict) – Dictionary with structure information.
 Returns
 Return type
Structure

orix.io.plugins.orix_hdf5.
file_reader
(filename, **kwargs)¶ 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()
.
 Returns
 Return type

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
Group.require_dataset
.

orix.io.plugins.orix_hdf5.
hdf5group2dict
(group, dictionary=None, recursive=False)¶ Return a dictionary with values from datasets in a group in an opened HDF5 file.
 Parameters
 Returns
dictionary – Dataset values in group (and subgroups if recursive=True).
 Return type

orix.io.plugins.orix_hdf5.
lattice2dict
(lattice, dictionary=None)¶ Get a dictionary of a structure’s
diffpy.structure.Structure.lattice
content.Only values necessary to initialize a lattice object are returned.

orix.io.plugins.orix_hdf5.
phase2dict
(phase, dictionary=None)¶ Get a dictionary of a phase.

orix.io.plugins.orix_hdf5.
phaselist2dict
(phases, dictionary=None)¶ Get a dictionary of phases.

orix.io.plugins.orix_hdf5.
structure2dict
(structure, dictionary=None)¶ Get a dictionary of a phase’s
diffpy.structure.Structure
content.Only values necessary to initialize a structure object are returned.
plot¶
Extensions of Matplotlib’s projections framework for plotting
Vector3d
, Rotation
,
and CrystalMap
objects.
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]]))

Plot rotations in an AxesAngle projection. 

2D plotting of 

Plot rotations in a RodriguesFrank projection. 



Stereographic projection plot. 
AxAnglePlot¶

class
orix.plot.
AxAnglePlot
(fig, rect=None, *args, azim= 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, **kwargs)¶ Bases:
orix.plot.rotation_plot.RotationPlot
Plot rotations in an AxesAngle projection.
CrystalMapPlot¶

Add an opinionated colorbar to the figure and return it. 

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

Add a scalebar to the axes instance and return it. 

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)¶ Bases:
matplotlib.axes._axes.Axes
2D plotting of
CrystalMap
objects.
add_colorbar
(label=None, **kwargs)¶ 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
>>> cm 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() >>> ax = fig.add_subplot(projection="plot_map") >>> im = ax.plot_map(cm, cm.dp, cmap="inferno") >>> cbar = ax.add_colorbar("Dot product")
If the default options are not satisfactory, the colorbar can be updated
>>> cbar.ax.set_ylabel(ylabel="dp", rotation=90)

add_overlay
(crystal_map, item)¶ 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
>>> cm 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() >>> ax = fig.add_subplot(projection="plot_map") >>> im = ax.plot_map(cm) >>> ax.add_overlay(cm, cm.dp)

add_scalebar
(crystal_map, **kwargs)¶ 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() >>> ax = fig.add_subplot(projection="plot_map") >>> 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, **kwargs) → matplotlib.image.AxesImage¶ 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.
kwargs – Keyword arguments passed to
matplotlib.axes.Axes.imshow()
.
 Returns
im – Image object, to be used further to get data from etc.
 Return type
See also
matplotlib.axes.Axes.imshow
,orix.plot.CrystalMapPlot.add_scalebar
,orix.plot.CrystalMapPlot.add_overlay
,orix.plot.CrystalMapPlot.add_colorbar
Examples
>>> import matplotlib.pyplot as plt >>> import numpy as np >>> from orix import plot >>> from orix.io import load
Import a crystal map
>>> cm = 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(cm) # Get image
Add an overlay
>>> ax.add_overlay(cm, cm.iq)
Plot an arbitrary map property, also changing scalebar location
>>> ax = plt.subplot(projection="plot_map") >>> ax.plot_map( ... cm, cm.dp, cmap="cividis", scalebar_properties={"loc": 4} ... )
Add a colorbar
>>> cbar = ax.add_colorbar("Dot product") # Get colorbar
Plot orientation angle in degrees of one phase
>>> cm2 = cm["austenite"] >>> austenite_angles = cm2.orientations.angle.data * 180 / np.pi >>> fig = plt.figure() >>> ax = fig.add_subplot(projection="plot_map") >>> im = ax.plot_map(cm2, 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", ... pad_inches=0, ... bbox_inches="tight" ... )
Write unannotated image to file
>>> plt.imsave("/some/directory/image2.png", im.get_array())

remove_padding
()¶ Remove all white padding outside of the figure.
Examples
>>> cm 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 = fig.add_subplot(projection="plot_map") >>> ax.plot_map(cm) >>> ax.remove_padding()

scalebar
= None¶

RodriguesPlot¶

class
orix.plot.
RodriguesPlot
(fig, rect=None, *args, azim= 60, elev=30, sharez=None, proj_type='persp', box_aspect=None, **kwargs)¶ Bases:
orix.plot.rotation_plot.RotationPlot
Plot rotations in a RodriguesFrank projection.
RotationPlot¶

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

Set the azimuth grid resolution in degrees. 

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

Set the polar grid resolution in degrees. 

A scatter plot of vectors. 

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

Set the reference frame’s axes labels. 

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

Add text to the axes. 

class
orix.plot.
StereographicPlot
(*args, azimuth_resolution=10, polar_resolution=10, **kwargs)¶ Bases:
matplotlib.axes._axes.Axes
Stereographic projection plot. The projection is an equal angle projection and is typically used for visualizing 3D vectors in a 2D plane.
https://en.wikipedia.org/wiki/Stereographic_projection
Examples
>>> 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]]))

azimuth_grid
(resolution=None)¶ Set the azimuth grid resolution in degrees.
 Parameters
resolution (float, optional) – Aziumuth grid resolution in degrees. Default is 15 degrees. This can also be set upon initialization of the axes by passing azimuth_resolution to subplot_kw.
See also

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.
See also

property
hemisphere
¶ Hemisphere to plot.

name
= 'stereographic'¶

polar_grid
(resolution=None)¶ Set the polar grid resolution in degrees.
 Parameters
resolution (float, optional) – Polar grid resolution in degrees. Default is 15 degrees. This can also be set upon initialization of the axes by passing polar_resolution to the subplot_kw dictionary.
See also

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

scatter
(*args, **kwargs)¶ A scatter plot of vectors.
This method overwrites
matplotlib.axes.Axes.scatter()
, see that method’s docstring for parameters. Parameters
args (Vector3d or tuple of float or numpy.ndarray) – Vector(s), or azimuth and polar angles, the latter two passed as separate arguments (not keyword arguments).
kwargs – Keyword arguments passed to
matplotlib.axes.Axes.scatter()
.
See also

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()
.
See also

symmetry_marker
(v, fold, **kwargs)¶ Plot 2, 3 4 or 6fold symmetry marker(s).

text
(*args, **kwargs)¶ Add text to the axes.
This method overwrites
matplotlib.axes.Axes.text()
, see that method’s docstring for parameters. Parameters
args (Vector3d or tuple of float or numpy.ndarray) – Vector(s), or azimuth and polar angles, the latter two passed as separate arguments (not keyword arguments).
kwargs – Keyword arguments passed to
matplotlib.axes.Axes.text()
.
See also

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¶
Return the corresponding inverse projection, 


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

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 3111 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 [001] ([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 3111 standard [SphericalWolfram].
 Parameters
azimuth (float or numpy.ndarray) – Spherical azimuth coordinate.
polar (float or numpy.ndarray) – Spherical polar coordinate.
 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.
See also

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 3111 standard [SphericalWolfram]: one set for vectors in the upper hemisphere, and one for the lower.
 Parameters
azimuth (float or numpy.ndarray) – Spherical azimuth coordinate.
polar (float or numpy.ndarray) – Spherical polar coordinate.
 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.
See also

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 coordiantes \((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.
See also

InverseStereographicProjection¶

Return spherical coordinates, azimuth \(phi\) and polar \(theta\), defined as in the ISO 3111 standard [SphericalWolfram], from stereographic coordinates (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 [001] ([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 3111 standard [SphericalWolfram], from stereographic coordinates (X, Y).
 Parameters
x (float or numpy.ndarray) –
y (float or numpy.ndarray) –
 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
x (float or numpy.ndarray) –
y (float or numpy.ndarray) –
 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
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¶
Fourdimensional 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.

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

A set of 

Misorientation object. 

Basic quaternion object. 

Rotation object. 

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¶

Assign a symmetry to this orientation. 

class
orix.quaternion.
Orientation
(data)¶ Bases:
orix.quaternion.orientation.Misorientation
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
.
classmethod
from_euler
(euler, symmetry=None, convention='bunge', direction='crystal2lab')¶ Creates orientation(s) from an array of Euler angles.

classmethod
from_matrix
(matrix, symmetry=None)¶ Creates orientation(s) from orientation matrices [Rowenhorst2015].
 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 neoeuler (vector) representation.

set_symmetry
(symmetry)¶ Assign a symmetry to this orientation.
Computes equivalent transformations which have the smallest angle of rotation and assigns these inplace.
 Parameters
symmetry (Symmetry) –
 Returns
The instance itself, with equivalent values.
 Return type
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. ]]

property
symmetry
¶ Symmetry.

classmethod
Misorientation¶

Symmetry reduced distance 

Equivalent misorientations 

Assign symmetries to this misorientation. 

class
orix.quaternion.
Misorientation
(data)¶ Bases:
orix.quaternion.rotation.Rotation
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
 Returns
distance – 2D matrix containing the angular distance between every orientation, considering symmetries.
 Return type
Examples
>>> import numpy as np >>> from orix.quaternion.symmetry import C4, C2 >>> from orix.quaternion.orientation import Misorientation >>> data = np.array([[0.5, 0.5, 0.5, 0.5], [0, 1, 0, 0]]) >>> m = Misorientation(data).set_symmetry(C4, C2) >>> 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.
 Returns
 Return type

set_symmetry
(Gl, Gr, verbose=False)¶ Assign symmetries to this misorientation.
Computes equivalent transformations which have the smallest angle of rotation and assigns these inplace.
 Parameters
 Returns
A new misorientation object with the assigned symmetry.
 Return type
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. ]]

property
symmetry
¶ Tuple of Symmetry

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

The set of unique (mis)orientations of a symmetrical object. 
Produces suitable Rotations for the construction of a wireframe for self 


The vertices of the asymmetric domain. 

class
orix.quaternion.
OrientationRegion
(data)¶ Bases:
orix.quaternion.rotation.Rotation
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.

get_plot_data
()¶ Produces suitable Rotations for the construction of a wireframe for self

Quaternion¶

class
orix.quaternion.
Quaternion
(data=None)¶ Bases:
orix.base.Object3d
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

a, b, c, d
The individual elements of each vector.
 Type

conj
¶ The conjugate of this quaternion: \(q^* = a  bi  cj  dk\)
 Type

dot
(other)¶ Scalar : the dot product of this quaternion and the other.

dot_outer
(other)¶ Scalar : the outer dot product of this quaternion and the other.

mean
()¶ Calculates the mean quarternion with unitary weights
Notes
The method used here corresponds to the Equation (13) of http://www.acsu.buffalo.edu/~johnc/ave_quat07.pdf

outer
(other)¶ Compute the outer product of this quaternion and the other object.

classmethod
triple_cross
(q1, q2, q3)¶ Pointwise cross product of three quaternions.
 Parameters
q1 (Quaternion) – Three quaternions for which to find the “triple cross”.
q2 (Quaternion) – Three quaternions for which to find the “triple cross”.
q3 (Quaternion) – Three quaternions for which to find the “triple cross”.
 Returns
q
 Return type
Rotation¶
Point transformations of objects.
Rotations are transformations of threedimensional 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 xy plane can be considered an improper rotation of 180° about the zaxis, illustrated in the figure below.

The angle of rotation transforming this rotation to the other. 

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

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

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

Creates rotations from orientation matrices [Rowenhorst2015]. 

Creates a rotation from a neoeuler (vector) representation. 

Create identity rotations. 

Compute the outer product of this rotation and the other object. 

Uniformly distributed rotations. 

Random rotations with a simplified Von MisesFisher distribution. 

Rotations as Euler angles. 
Rotations as orientation matrices [Rowenhorst2015]. 


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

class
orix.quaternion.
Rotation
(data)¶ Bases:
orix.quaternion.quaternion.Quaternion
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 neoEuler representations. See
NeoEuler
.
angle_with
(other)¶ The angle of rotation transforming this rotation to the other.
 Returns
 Return type

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_euler
(euler, convention='bunge', direction='crystal2lab')¶ Creates a rotation from an array of Euler angles in radians.

classmethod
from_matrix
(matrix)¶ Creates rotations from orientation matrices [Rowenhorst2015].
 Parameters
matrix (array_like) – Array of orientation matrices.
Examples
>>> import numpy as np >>> from orix.quaternion.rotation 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 neoeuler (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 object.

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 MisesFisher distribution.

to_euler
(convention='bunge')¶ Rotations as Euler angles.
 Parameters
convention (str, optional) – The Euler angle convention used. Only “bunge” is supported.
 Returns
Array of Euler angles in radians.
 Return type
ndarray

to_matrix
()¶ Rotations as orientation matrices [Rowenhorst2015].
 Returns
Array of orientation matrices.
 Return type
ndarray
References
 Rowenhorst2015(1,2,3,4,5)
D. Rowenhorst, A. D. Rollett, G. S. Rohrer, M. Groeber, M. Jackson, P. J. Konijnenberg, M. De Graef, “Consistent representations of and conversions between 3D rotations,” Modelling and Simulation in Materials Science and Engineering 23 (2015), doi: https://doi.org/10.1088/09650393/23/8/083501
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 symmetricallyequivalent views on that object. Consider the following shape.
This obviously has threefold 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 2fold rotation combined with inversion.

Create a Symmetry from a minimum list of generating transformations. 

class
orix.quaternion.
Symmetry
(data)¶ Bases:
orix.quaternion.rotation.Rotation
The set of rotations comprising a point group.

property
diads
¶

classmethod
from_generators
(*generators)¶ Create a Symmetry from a minimum list of generating transformations.
 Parameters
generators (Rotation) – An arbitrary list of constituent transformations.
 Returns
 Return type
Examples
Combining a 180° rotation about [1, 1, 0] with a 4fold 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. ]]

fundamental_sector
()¶

get_axis_orders
()¶

get_highest_order_axis
()¶

name
= ''¶

property
proper_subgroups
¶ the proper groups that are subgroups of this group.
 Type
list of Symmetry

property
subgroups
¶ the groups that are subgroups of this group.
 Type
list of Symmetry

property
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.

orix.quaternion.symmetry.
get_point_group
(space_group_number, proper=False)¶ Maps a space group number to its (proper) point group.
 Parameters
 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 'm3m' >>> pgO = get_point_group(225, proper=True) >>> pgO.name '432'
sampling¶

Generates an equispaced grid of rotations within a fundamental zone. 

Generates a grid of rotations about a given rotation 

Returns rotations that are evenly spaced according to the Haar measure on SO3 
Module for generating grids in orientation spaces.

orix.sampling.
get_sample_fundamental
(resolution=2, point_group=None, space_group=None)¶ Generates an equispaced grid of rotations within a fundamental zone.
 Parameters
 Returns
q – Grid of rotations lying within the specified fundamental zone
 Return type
orix.quaternion.rotation.Rotation
See also
orix.sampling.utils.uniform_SO3_sample
Examples
>>> from orix.quaternion.symmetry import C2,C4 >>> grid = get_sample_fundamental(1, point_group=C2)

orix.sampling.
get_sample_local
(resolution=2, center=None, grid_width=10)¶ Generates a grid of rotations about a given rotation
 Parameters
resolution (float, optional) – The characteristic distance between a rotation and its neighbour (degrees)
center (orix.quaternion.rotation.Rotation, optional) – The rotation at which the grid is centered. If None (default) uses the identity
grid_width (float, optional) – The largest angle of rotation away from center that is acceptable (degrees)
 Returns
q – Grid of rotations lying within grid_width of center
 Return type
orix.quaternion.rotation.Rotation
See also
orix.sampling_utils.uniform_SO3_sample

orix.sampling.
uniform_SO3_sample
(resolution, max_angle=None, old_method=False)¶ Returns rotations that are evenly spaced according to the Haar measure on SO3
 Parameters
 Returns
q – grid containing appropriate rotations
 Return type
orix.quaternion.rotation.Rotation
See also
orix.sample_generators.get_local_grid
scalar¶
Dimensionless quantities.
As well as themselves representing physical quantities, Scalars may represent elements of higherdimensional quantities, such as the xcomponent of a vector or the rotation angle of a quaternion.

class
orix.scalar.
Scalar
(data)¶ Bases:
orix.base.Object3d
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.
Elementwise 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.
vector¶
Threedimensional quantities.
Vectors can represent positions in threedimensional 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.

The simplest neoEulerian representation. 

Equalvolume mapping of the unit quaternion hemisphere. 

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. 

Base class for neoEulerian vectors. 

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

A set of vectors representing normals segmenting a sphere. 

Vector base class. 
AxAngle¶

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 neoEulerian representation.
The AxisAngle vector representing a rotation with rotation angle \(\theta\) has magnitude \(\theta\)

classmethod
from_axes_angles
(axes, angles)¶ Create new AxAngle object explicitly from the given axes and angles.

classmethod
from_rotation
(rotation)¶ NeoEuler : Create a new vector from the given rotation.

classmethod
Homochoric¶

class
orix.vector.
Homochoric
(data=None)¶ Bases:
orix.vector.neo_euler.NeoEuler
Equalvolume 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.

classmethod
from_rotation
(rotation)¶ NeoEuler : Create a new vector from the given rotation.

classmethod
Miller¶

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

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

Dot product of a vector with another vector. 

Outer dot product of a vector with another vector. 

Return a deepcopy of the instance. 

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

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

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

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

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

Mean vector of the set of vectors. 

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

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

Convenience function for rotating this vector. 

Plot vectors in the stereographic projection. 

Vectors symmetrically equivalent to the ones in self. 

Unique vectors in self. 

class
orix.vector.
Miller
(xyz=None, uvw=None, UVTW=None, hkl=None, hkil=None, phase=None)¶ Bases:
orix.vector.vector3d.Vector3d
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.

property
T
¶ Third direct lattice vector index in 4index Weber symbols, equal to \((u + v)/3\).

property
U
¶ First direct lattice vector index in 4index Weber symbols, equal to \((2u  v)/(3)\).

property
UVTW
¶ Direct lattice vectors expressed as 4index 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 4index Weber symbols, equal to \((2v  u)/3\).

property
W
¶ Fourth direct lattice vector index in 4index 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.

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

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.
 Returns
 Return type

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.
 Returns
 Return type

flatten
()¶ Object3d : 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
phase (orix.crystal_map.Phase) – A phase with a crystal lattice and symmetry.
uvw (numpy.ndarray, list, or tuple, optional) – Three highest direct lattice vector indices.
hkl (numpy.ndarray, list, or tuple, optional) – Three highest reciprocal lattice vector indices.

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 4index MillerBravais indices.

property
hkl
¶ Reciprocal lattice vectors.

property
i
¶ Third reciprocal lattice vector index in 4index MillerBravais 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 4index 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 indata
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 (MillerBravais/Weber) to the closest smallest integers.
Adopted from MTEX’s Miller.round function.

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.

property
u
¶ First direct lattice vector index.

unique
(use_symmetry=False, return_index=False)¶ Unique vectors in self.
 Parameters
 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.

property
NeoEuler¶

NeoEuler : Create a new vector from the given rotation. 
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}\).

classmethod
from_rotation
(rotation)¶ NeoEuler : Create a new vector from the given rotation.

classmethod
SphericalRegion¶
Vectors describing a segment of a sphere.
Each entry represents a plane normal in 3d. Vectors can lie in, on, or outside the spherical region.
Examples
>>> sr = SphericalRegion([0, 0, 1]) # Region above the xy 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)¶ Bases:
orix.vector.vector3d.Vector3d
A set of vectors representing normals segmenting a sphere.
Vector3d¶

Calculate the angles between vectors in ‘self’ and ‘other’ 

The cross product of a vector with another vector. 

The dot product of a vector with another vector. 

The outer dot product of a vector with another vector. 

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

Create a 

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

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



Convenience function for rotating this vector. 

Plot vectors in the stereographic projection. 

Return the azimuth \(\phi\), polar \(\theta\), and radial \(r\) spherical coordinates, the angles in radians. 

Vector3d : a single unit vector parallel to the xdirection. 

Vector3d : a single unit vector parallel to the ydirection. 

Vector3d : a single unit vector parallel to the zdirection. 

Returns zero vectors in the specified shape. 

class
orix.vector.
Vector3d
(data=None)¶ Bases:
orix.base.Object3d
Vector base class.
Vectors support the following mathematical operations:
Unary negation.
Addition to other vectors, scalars, numbers, and compatible arraylike objects.
Subtraction to and from the above.
Multiplication to scalars, numbers, and compatible arraylike 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 vectors in ‘self’ and ‘other’
Vectors must have compatible shapes for broadcasting to work.
 Returns
The angle between the vectors, in radians.
 Return type

property
azimuth
¶ Azimuth spherical coordinate, i.e. the angle \(\phi \in [0, 2\pi]\) from the positive zaxis to a point on the sphere, according to the ISO 3111 standard [SphericalWolfram].
 Returns
 Return type

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
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]]

dot
(other)¶ The dot product of a vector with another vector.
Vectors must have compatible shape.
 Returns
 Return type
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.
 Returns
 Return type
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, None, None], hemisphere=None, show_hemisphere_label=None, grid=None, grid_resolution=None, figure_kwargs={}, 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
azimuth_grid
andpolar_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
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.

classmethod
from_polar
(azimuth, polar, radial=1)¶ Create a
Vector3d
from spherical coordinates according to the ISO 3111 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.
 Returns
 Return type
References

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 delinating circles with the opening_angle about the vectors.
 Return type
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
 Returns
 Return type

mean
()¶

property
perpendicular
¶

property
polar
¶ Polar spherical coordinate, i.e. the angle \(\theta \in [0, \pi]\) from the positive zaxis to a point on the sphere, according to the ISO 3111 standard [SphericalWolfram].
 Returns
 Return type

property
radial
¶ Radial spherical coordinate, i.e. the distance from a point on the sphere to the origin, according to the ISO 3111 standard [SphericalWolfram].
 Returns
 Return type

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 zvector.
angle (array_like, optional) – The angle of rotation, in radians.
 Returns
A new vector with entries rotated.
 Return type
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, None, None], vector_labels=None, hemisphere=None, show_hemisphere_label=None, grid=None, grid_resolution=None, figure_kwargs={}, text_kwargs={}, 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
azimuth_grid
andpolar_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 tomatplotlib.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 tomatplotlib.axes.Axes.scatter()
.
 Returns
fig – The created figure, returned if return_figure is True.
 Return type
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.See also

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 3111 standard [SphericalWolfram].
 Returns
azimuth, polar, radial
 Return type

classmethod
xvector
()¶ Vector3d : a single unit vector parallel to the xdirection.

property
xyz
¶ This vector’s components, useful for plotting.
 Type
tuple of ndarray

classmethod
yvector
()¶ Vector3d : a single unit vector parallel to the ydirection.

classmethod
zero
(shape=(1))¶ Returns zero vectors in the specified shape.

classmethod
zvector
()¶ Vector3d : a single unit vector parallel to the zdirection.