Reproject hidden part of circle about vector to current hemisphere

[hakonanes]

Description of the change

Inspired by #307, this PR adds the option to draw part of great/small circle only visible on the other hemisphere on the current hemisphere. This is mostly useful for visualization purposes, as far as I know. It is accomplished by temporarily setting the current axis hemisphere to the other hemisphere within StereographicPlot.draw_circle().

Progress of the PR

• Docstrings for all functions
• Unit tests with pytest for all lines
• Clean code style by running black via pre-commit

Minimal example of the bug fix or new feature

>>> from orix.vector import Vector3d
>>> v = Vector3d(((1, 1, 1), (-1, 1, 1)))
>>> fig = v.scatter(axes_labels=["X", "Y"], return_figure=True, c=["C0", "C1"])
>>> v.draw_circle(reproject=True, figure=fig, color=["C0", "C1"], opening_angle=np.deg2rad([90, 45]), reproject_plot_kwargs=dict(linestyle=":"))

For reviewers

• The PR title is short, concise, and will make sense 1 year later.
• New functions are imported in corresponding __init__.py.
• New features, API changes, and deprecations are mentioned in the
  unreleased section in CHANGELOG.rst.

[harripj]

This PR is a great addition which helps to visualise circles (planes) in the stereographic projection. I have just a couple of comments, I think we should keep the reproject syntax similar between scatter() (#307) and draw_circle() (this PR).

[harripj]

Just a comment on the interpretation of this PR. Perhaps the notion of reproject to a circle should apply to the same circle, ie. to show the reproduction of the same circle on one hemisphere.

At the moment we are showing two different circles in the example (one from the original vector and one from the antipodal vector). But perhaps we should change this behaviour so that one entire circle is shown, and if the user wants the other circle they can do the same with the other vector. The updated example (notebook v8 and example here) of what I am suggesting:

fig, ax = plt.subplots(ncols=1, subplot_kw=dict(projection='stereographic'))
ax = [ax]
ax[0].scatter(v8, c=["C0", "C1"])
circ = v8.get_circle(opening_angle=np.deg2rad([90, 45]))
ax[0].plot(circ[0], color='C0')
ax[0].plot(circ[0].__class__(circ[0].data * (1, 1, -1)), linestyle='--', color='C0')

ax[0].plot(circ[1], color='C1')
ax[0].plot(circ[1].__class__(circ[1].data * (1, 1, -1)), linestyle='--', color='C1')

This is achieved like in #307, where the hidden parts of the circle are reflected in the projection plane and shown on the same hemisphere. In this case we see complete circles (planes) in the stereographic projection.

For the 90 degree opening_angle case this leads to the same result, but away from this the behaviour is different.

What do you think?

[hakonanes]

I agree that your solution is better and more in line with reproject, and will do the suggest change.

To be honest, I only saw myself using this visualization for opening angles of 90 degrees, and thus didn't spend time on getting your result for other opening angles, and changed the scope and docstrings accordingly. Thank you for taking the time to make the comment!

[harripj]

To be honest, I only saw myself using this visualization for opening angles of 90 degrees

Yes, definitely makes most sense for 90 degrees!

I like the examples with the antipodal vectors, I suggest to keep them in the notebook. Perhaps you can update the current example to show the completion of the planes in the stereographic projection (ie. what we have just discussed), but also add another to show the circle of the antipodal vector on the same plot? There is a nice symmetry to this figure which I think would be quite informative to the reader.

[harripj]

I was thinking something like this:

For the 90 degree opening_angle this example isn't really possible as they overlap.

[hakonanes]

I've now updated the code according to our discussion. Your latest example is not possible though since the antipodal vector is located on the lower hemisphere.

[hakonanes]

We can reflect vectors about the equator (projection plane) by simply negating their z coordinate, since the Vector3d.z property has a setter. This simplifies the creation of the reflected vectors already merged in #307 to:

v_reprojected = deepcopy(self)
v_reprojected.z = -v_reprojected.z

We also don't need to check for visibility, since vectors previously not visible are now visible, and vice versa, and this is handled by StereographicPlot.

That this simplification wasn't caught in review of #307 is on me. If you're OK with it @harripj, I'll make the suggested changes in this PR.

[harripj]

Good idea, no problem for me, fire away.

[harripj]

I will wait until you have made these changes to finish my review.

[hakonanes]

Note that I force-pushed due to a rebase on master to get changes in #307.

[harripj]

Looks good to me apart from one thing below. I think this PR is very beneficial to visualising planes in the stereographic projection, nice work!

Of note, I can see here that in the docstrings it explicitly states that linestyle="--", but in the docs there is only one hyphen? See under reproject_plot_kwargs:
https://orix--308.org.readthedocs.build/en/308/reference.html#orix.vector.Vector3d.draw_circle
https://orix--308.org.readthedocs.build/en/308/reference.html#orix.plot.StereographicPlot.draw_circle

Perhaps sphinx is escaping the double hyphen? Worth fixing in any case as a single hyphen to me means a solid line, which is not the behaviour. One possible solution is to say "dashed" in the docstrings.

[hakonanes]

Thanks for checking the docstrings, I've rephrased to say "dashed" instead of "--" being misinterpreted as "–" by Sphinx.

[pc494]

Easy to read code as always @hakonanes, merging.

[hakonanes]

Thanks @pc494 :) And to @harripj for a thorough review making the initial functionality better and more clear.