Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 Annulus3D

Source Notebook

Represent a 3D annulus

Contributed by: Jaroslav Kysela

ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{rinner,router}]

represents a 3D annulus around the line from {x1,y1,z1} to {x2,y2,z2} with inner radius rinner and outer radius router.

ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{rinner,router},{θ1,θ2}]

represents a 3D annulus from angle θ1 to θ2.

ResourceFunction["Annulus3D"][{x,y,z},{rinner,router}]

represents a planar annulus at {x,y,z} normal to the z-axis with inner radius rinner and outer radius router.

ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{rinner,router}]

represents a planar annulus with its normal given by {nx,ny,nz}.

ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{rinner,router},{θ1,θ2}]

represents a planar annulus from angle θ1 to θ2.

Details

ResourceFunction["Annulus3D"] can be used in Graphics3D.
Graphics rendering is affected by directives such as FaceForm, EdgeForm, Specularity, Opacity, and color.
ResourceFunction["Annulus3D"] allows 0<rinner<router.
ResourceFunction["Annulus3D"][] is equivalent to ResourceFunction["Annulus3D"][{{0,0,-1},{0,0,1}},{1/2,1}].
ResourceFunction["Annulus3D"][r] is equivalent to ResourceFunction["Annulus3D"][{{0,0,-1},{0,0,1}},{r/2,r}].
ResourceFunction["Annulus3D"][{rinner,router}] is equivalent to ResourceFunction["Annulus3D"][{{0,0,-1},{0,0,1}},{rinner,router}].
ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}}] is equivalent to ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{1/2,1}].
ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},r] is equivalent to ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{r/2,r}].
ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{rinner,router}] is equivalent to ResourceFunction["Annulus3D"][{{x1,y1,z1},{x2,y2,z2}},{rinner,router},{0,2π}].
ResourceFunction["Annulus3D"][{x,y,z}] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{1/2,1}].
ResourceFunction["Annulus3D"][{x,y,z},r] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{r/2,r}].
ResourceFunction["Annulus3D"][{x,y,z},{rinner,router}] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{0,0,1},{rinner,router}].
ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz}] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{1/2,1}].
ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},r] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{r/2,r}].
ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{rinner,router}] is equivalent to ResourceFunction["Annulus3D"][{x,y,z},{nx,ny,nz},{rinner,router},{0,2π}].

Examples

Basic Examples (5) 

A unit radius and two units height 3D annulus:

In[1]:=
Graphics3D[ResourceFunction["Annulus3D"][]]
Out[1]=

Plane annulus embedded in 3D:

In[2]:=
Graphics3D[ResourceFunction["Annulus3D"][{0, 0, 0}]]
Out[2]=

A 3D annulus from the origin to {1,-1,1} with inner radius 1/2:

In[3]:=
Graphics3D[ ResourceFunction["Annulus3D"][{{0, 0, 0}, {1, -1, 1}}, {1/2, 1}]]
Out[3]=

Annulus sectors:

In[4]:=
{Graphics3D[ ResourceFunction[ "Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {1/2, 1}, {0, \[Pi]}]], Graphics3D[ ResourceFunction[ "Annulus3D"][{0, 0, 0}, {0, 0, 1}, {1/2, 1}, {0, \[Pi]}]]}
Out[4]=

Differently styled annuli:

In[5]:=
{Graphics3D[{Blue, ResourceFunction["Annulus3D"][]}], Graphics3D[{Opacity[.5], EdgeForm[], ResourceFunction["Annulus3D"][]}], Graphics3D[{Specularity[5], ResourceFunction["Annulus3D"][]}]}
Out[5]=

Scope (16) 

Center Specification (2) 

Specify centers of 3D annuli:

In[6]:=
Graphics3D[{ Red, With[{x = 0, y = 0}, ResourceFunction["Annulus3D"][{{x, y, -1}, {x, y, 1}}]], Green, With[{x = 1, y = 1}, ResourceFunction["Annulus3D"][{{x, y, -1}, {x, y, 1.03}}]], Blue, With[{x = 2, y = 2}, ResourceFunction["Annulus3D"][{{x, y, -1}, {x, y, 1.06}}]] }]
Out[6]=

Specify centers of planar annuli:

In[7]:=
Graphics3D[{ Red, With[{x = 0, y = 0}, ResourceFunction["Annulus3D"][{x, y, -1.06}]], Green, With[{x = 1, y = 1}, ResourceFunction["Annulus3D"][{x, y, -1.03}]], Blue, With[{x = 2, y = 2}, ResourceFunction["Annulus3D"][{x, y, -1}]] }]
Out[7]=

Direction Specification (3) 

3D annuli with different directions:

In[8]:=
Graphics3D[{ResourceFunction["Annulus3D"][{{0, 0, 0}, {1, 0, 0}}], ResourceFunction["Annulus3D"][{{1, 1, 1}, {2, 3, 1}}]}]
Out[8]=

Equivalent scene with plane annuli:

In[9]:=
Graphics3D[{ResourceFunction["Annulus3D"][{0, 0, 0}, {1, 0, 0}], ResourceFunction["Annulus3D"][{1, 1, 1}, {2, 3, 1} - {1, 1, 1}]}]
Out[9]=

A plane annulus at the origin with normal vector {1,-1,1} and inner radius 1/2:

In[10]:=
Graphics3D[ ResourceFunction["Annulus3D"][{0, 0, 0}, {1, -1, 1}, {1/2, 1}]]
Out[10]=

Radius Specification (3) 

Specify radii of 3D annuli:

In[11]:=
Graphics3D[{Red, ResourceFunction["Annulus3D"][1], Green, ResourceFunction["Annulus3D"][3], Blue, ResourceFunction["Annulus3D"][7]}]
Out[11]=

Specify radii of plane annuli:

In[12]:=
Graphics3D[{Red, ResourceFunction["Annulus3D"][{0, 0, 0}, 1], Green, ResourceFunction["Annulus3D"][{0, 0, 0}, 3], Blue, ResourceFunction["Annulus3D"][{0, 0, 0}, 7]}]
Out[12]=

Specify position, direction, as well as inner and outer radii:

In[13]:=
Graphics3D[{ResourceFunction[ "Annulus3D"][{{-1, -2, 0}, {1, -1, 3}}, {0.5, 0.8}]}]
Out[13]=

Short form for a 3D annulus centered at the origin with a radius 1:

In[14]:=
Graphics3D[ResourceFunction["Annulus3D"][], Axes -> True]
Out[14]=

Angle Specification (2) 

Specify the initial and final angle for the annulus sector:

In[15]:=
Graphics3D[ ResourceFunction[ "Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {0.5, 1}, {\[Pi]/2, 2 \[Pi]}]]
Out[15]=

Equivalent scene for the plane annulus:

In[16]:=
Graphics3D[ ResourceFunction[ "Annulus3D"][{0, 0, 0}, {0, 0, 1}, {0.5, 1}, {\[Pi]/2, 2 \[Pi]}]]
Out[16]=

Styling (6) 

Color directives specify the face color of each annulus:

In[17]:=
Table[Graphics3D[{c, ResourceFunction["Annulus3D"][]}], {c, {Red, Green, Blue, Yellow}}]
Out[17]=

Different properties can be specified for the front and back faces using FaceForm:

In[18]:=
{Graphics3D[{FaceForm[Yellow, Blue], ResourceFunction["Annulus3D"][{0, 0, 0}, {1, 0, 0}]}], Graphics3D[{FaceForm[Yellow, Blue], ResourceFunction["Annulus3D"][{0, 0, 0}, {-1, 0, 0}]}]}
Out[18]=

For 3D annuli the FaceForm corresponds to the outer and inner faces:

In[19]:=
Graphics3D[{FaceForm[Yellow, Blue], ResourceFunction["Annulus3D"][]}, PlotRange -> {{-1, 1}, {-.8, 1}, {-1, 1}}]
Out[19]=

Opacity specifies the face opacity:

In[20]:=
Table[Graphics3D[{Opacity[o], ResourceFunction["Annulus3D"][]}], {o, {0.3, 0.5, 0.9}}]
Out[20]=

Decompose the annulus into its components and apply different styling to each:

In[21]:=
{baseL, baseH, circumIn, circumOut} = ResourceFunction["Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {0.5, 1.1}];
In[22]:=
Graphics3D[{EdgeForm[], {Opacity[.7, Orange], baseL, baseH}, Purple, circumOut, Green, circumIn}]
Out[22]=

For planar annuli, only one component is returned, for which different EdgeForm and FaceForm can be given:

In[23]:=
Graphics3D[{EdgeForm[{Thickness[0.02], Blue}], Orange, ResourceFunction["Annulus3D"][{0, 0, 0}, {0.5, 1.1}]}]
Out[23]=

Applications (2) 

A simple 3D bar chart:

In[24]:=
data = RandomReal[{1, 10}, {5, 4}];
In[25]:=
Graphics3D[ MapIndexed[{Hue[(Last[#2] - 1)/4], ResourceFunction[ "Annulus3D"][{Append[{1, 2} #2, 0], Append[{1, 2} #2, #1]}, .5]} &, data, {2}], Axes -> {False, False, True}, Lighting -> "Neutral"]
Out[25]=

A simple 3D pie chart:

In[26]:=
data = RandomReal[{0, 1}, 5];
In[27]:=
data = Partition[ Accumulate[2 \[Pi] Normalize[Prepend[data, 0], Total]], 2, 1];
In[28]:=
Graphics3D[ MapIndexed[{Hue[(Last[#2] - 1)/5], ResourceFunction[ "Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {1, 2}, #1]} &, data, {1}], Boxed -> False, Lighting -> "Neutral"]
Out[28]=

Properties and Relations (4) 

Annulus3D is a 3D generalization of Annulus in 2D:

In[29]:=
Graphics[Annulus[]]
Out[29]=

For very small inner radii, Annulus3D reduces to Cylinder:

In[30]:=
{Graphics3D[{EdgeForm[], Cylinder[{{0, 0, 0}, {0, 0, 1}}]}], Graphics3D[{EdgeForm[], ResourceFunction[ "Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {0.00001, 1}]}]}
Out[30]=

PieChart3D can be used to create 3D annuli:

In[31]:=
PieChart3D[{1}, ChartElementFunction -> ChartElementDataFunction["CylindricalSector3D"], SectorOrigin -> {{0, 1}, 0.7}]
Out[31]=

Get the graphical primitive from PieChart3D:

In[32]:=
ann3D[{rIn_, rOut_}, {zLow_, zHigh_}] := ChartElementData[ "CylindricalSector3D"][{{0, 2 \[Pi]}, {rIn, rOut}, {zLow, zHigh}}, 1];
In[33]:=
Graphics3D[ann3D[{.7, 1.5}, {0, 1}], Axes -> True]
Out[33]=

Despite being seemingly the same as the object returned by Annulus3D, the latter has no “seam”:

In[34]:=
{ Graphics3D[{EdgeForm[Thick], ann3D[{.7, 1.5}, {0, 1}]}, Axes -> True, ImageSize -> Medium], Graphics3D[{EdgeForm[Thick], ResourceFunction["Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {0.7, 1.5}]}, Axes -> True, ImageSize -> Medium] }
Out[34]=

Possible Issues (4) 

When the two endpoints coincide, no 3D annulus is created:

In[35]:=
Graphics3D[ResourceFunction["Annulus3D"][{{0, 0, 0}, {0, 0, 0}}]]
Out[35]=

Use the planar specification instead:

In[36]:=
Graphics3D[ResourceFunction["Annulus3D"][{0, 0, 0}, {0, 0, 1}]]
Out[36]=

Radii are assumed to be positive real numbers:

In[37]:=
Graphics3D[ ResourceFunction["Annulus3D"][{{0, 0, 0}, {1, 0, 0}}, {0, 1}]]
Out[37]=

When the inner radius exceeds the outer one, a warning is issued:

In[38]:=
Graphics3D[ ResourceFunction["Annulus3D"][{{0, 0, 0}, {1, 0, 0}}, {.2, .1}]]
Out[38]=

When the normal vector in the specification of a planar annulus is zero, the default setting is used:

In[39]:=
Graphics3D[ResourceFunction["Annulus3D"][{1, 2, 0}, {0, 0, 0}]]
Out[39]=

Neat Examples (3) 

Random annuli:

In[40]:=
Graphics3D[ Table[{EdgeForm[Opacity[.3]], Hue[RandomReal[]], ResourceFunction["Annulus3D"][ RandomReal[10, {2, 3}], {1/2, 1}]}, {20}]]
Out[40]=

Interlaced annuli:

In[41]:=
d = 0.1; Graphics3D[{Lighter[Blue, 0.8], Table[Rotate[ ResourceFunction[ "Annulus3D"][{{1, 0, -d}, {1, 0, d}}, {0.2, 0.3}], ang, {0, 0, 1}], {ang, 0, 2 \[Pi], \[Pi]/5}], Table[Rotate[ ResourceFunction[ "Annulus3D"][{{1 - d, 0, 0}, {1 + d, 0, 0}}, {0.2, 0.3}], ang + \[Pi]/10, {0, 0, 1}], {ang, 0, 2 \[Pi], \[Pi]/5}] }, ImageSize -> Large, Boxed -> False]
Out[41]=

An annulus sector and its shadow:

In[42]:=
Manipulate[ Graphics3D[{Yellow, ResourceFunction[ "Annulus3D"][{{0, 0, 0}, {0, 0, 1}}, {0.8, 1}, {ang1, ang2}], Black, ResourceFunction[ "Annulus3D"][{0, 0, -0.99}, {0, 0, 1}, {0.8, 1}, {ang1, ang2}]}, PlotRange -> 1], {{ang1, 0}, -2 \[Pi], 2 \[Pi]}, {{ang2, 5}, -2 \[Pi], 2 \[Pi]}]
Out[42]=

Publisher

Jaroslav Kysela

Version History

  • 1.0.0 – 03 January 2022

Related Resources

License Information