Torus Knot + Update (add new features and reorganize code and UI) #46885

New Issue

Dolphin Dream · 2015-11-28T08:37:52+01:00

Dolphin Dream commented

2015-11-28 08:37:52 +01:00

SUMMARY:

reorganize the code and regroup the UI elements into categories
add comments to code, descriptions to props and add more appropriate naming for some of the UI elements
recode to allow multiple TK link generation when (p,q) are not co-prime and also to avoid self overlapping curve.
add curve type selection: POLY, NURB, BEZIER (default)
add major/minor vs interior/exterior radii settings to define the torus geometry (typical torus formula is based on [p,q,r,R] set)
add adaptive curve resolution (off by default) using an approximate TK curve length based on [p,q,r,R] values.
make plus setting be used ONLY when the plus settings are enabled
restrict curve generation to only OBJECT mode (avoid error while adding TK curve in edit mode)
add colors for the TK links (with additional color settings as plus options) and option to toggle colors (off by default)
add multi-link generation toggle (useful for cases when (p,q) are not co-prime)
add option to flip directions for revolution (p) and spin (q)
add option to adjust phasing (revolution and spin) (plus option)
add matrix alignment to allow placement at 3D cursor and add absolute location toggle option to allow the location prop to be applied relative to the 3D cursor or relative to the world origin.

Here is my git repo for the TK script developing which includes some of the incremental updates relative to the version of the add-on included in blender 2.76:
https://github.com/DolphinDream/blenderAddons

Also, here is the resource I used for TK curve length approximation formula (used with the adaptive curve resolution) based on my inquiry on "Mathematics Stack Exchange":
http://math.stackexchange.com/questions/1523388/tight-approximation-of-a-torus-knot-length

DETAILS:

General Approach/Philosophy

The intention was to revamp the TK add-on to better organize its UI but also to add some missing features, while preserving most of the original settings and everything that the previous version was able to do, whether through its main settings or its extended ("plus") options. In addition, the code was also reorganized and better documented.

Plus-Option settings (update)

On top of adding new "plus" option, the code was updated so that the "plus" settings are ONLY used when the "plus option" is enabled. E.g. it may be confusing to have the user toggle the plus option ON, change some plus option settings altering the curve, then toggle the plus option OFF and have the generated curve still use the "plus option". The new implementation makes sure that turning "plus option" on/off applies to both the UI visibility and the functionality of the plus options.

Also, my approach with the plus option was to keep everything that does not generate an actual TK curve out of the main settings. For example, the "height" property distorts the TK along Z making it not a regular torus and for this reason I migrated the "height" property into the "plus option" section.

NOTE: the old "scale" property was also made a "plus" options, but not because it alters the torus-ness of the curve, but because the effect the old "scale" had is currently achievable via direct manipulation of the torus radii (which were missing in the previous implementation). In the new implementation the "scale" property is redefined and is actually just a convenience property used for scaling proportionally both torus radii, which is essentially equivalent to scaling the R and r directly.

When the "plus option" is enabled each category will list their corresponding plus options. Also the plus options are boxed to better distinguished between the main settings and the plus settings within each category.

Categories (UI grouping)

Aside from the previous "Torus Parameters" and "Geometry Options" categories, new categories were introduced to group together various old and new properties. The current categories are:

Torus Knot Parameters (p,q + multi link, flip)
Torus Dimensions (radii, scale/height)
Curve Options (resolutions, curve type, adaptive resolution)
Color Options (link colors)
Geometry Options (surface, extrusion)
Transform Options (location, rotation)

Torus Knot Parameters

This category hosts the main p & q parameters defining the knot.
Also, with the newly added "multi-link" feature, a toggle option is added here and a and to allow the curve direction to be reversed.

NOTE: flipping both p and q is equivalent to no flip.

plus options *
With the "plus" options enabled this category also includes:

The p/q multipliers are exactly that: they scale the number of revolutions (p) and spins (q) the curve makes. This is typically used in conjunction with a fix curve resolution to create under-sampled artifact curves that generate "Wicker Basket" curve and other interestingly shaped curves.

The revolution/spin phase allow the user to define the starting point of the curve along the revolution and the spin rotations. The effects of these parameters are more noticeable at low curve resolutions and especially for POLY curve type. At high resolution their effect is visually equivalent to a rotation along the local Z axis.

Multi-Links (NEW feature)

Based on the definition of the torus knot (https://en.wikipedia.org/wiki/Torus_knot) I noticed that the current TK add-on implementation was not generating a correct TK curve for cases where (p,q) are not co-prime. These degenerate cases correspond to a TK formed by decoupled TK links of lower order (e.g. a 4x8 TK is formed by 4 separate 1x2 TK curves).

NOTE: You can check out the old TK add-on to verify that indeed a p/q = 4/8 generates the same curve as p/q = 1/2 (although the curve winds 4 times over itself).

The greatest common denominator of p and q: n=gcd(p,q) determines the degree of degeneracy of the TK curve, which is the number of decoupled TK links of lower order. Each of the n lower order TK is defined by the pair (p/n, q/n).

A multi-link toggle option was added (ON by default) to allow the user to generate all links of the TK or just one link (when p and q are not co-prime). This option obviously does nothing whenever p,q are co-prime since in this case there is only ONE link forming the TK. Also, by turning the multi-link option off makes the new add-on generates the same curve as the old add-on (albeit without any self overlapping curve).

NOTE: multiple (decoupled) TK links are particularly interesting to generate in conjunction with link coloring to allow to visually distinguish the decoupled links.

Torus Dimensions (NEW feature)

The previous implementation had no options to alter the torus radii other that through the "scale" parameter, which was in essence scaling the Major radius of the torus. The new implementation adds the option to allow the user to directly manipulate both torus radii directly. Typically these radii are the Major (R) and the Minor (r) radii, but for convenience the equivalent set of radii (Interior/Exterior) was also added. The user can toggle between the (R,r) and (iR,eR) radii sets to alter in order to change the torus geometry.

plus options *
With "plus" options the "Torus Dimensions" category also includes the and properties. The scales both the minor and the major radii proportionally being equivalent to a proportional scaling of the whole curve (in edit mode). The property scales the curve along Z axis (just like before).

Curve Options (NEW features)

Add the option to select the curve type (POLY, NURB, BEZIER) and relocated the curve resolution and the segment resolution properties into this category.

NOTE: the previous "curve resolution" property was ambiguously called "Resolution" while the segment resolution was called "resolution". In current implementation these are "Curve Resolution" and "Segment Resolution" and they represent the number of control points per curve and the number of points per segment respectively.

Adaptive Resolution

To this section was also added an "adaptive resolution" toggle option (OFF by default) to allow the resolution to be automatically set based on the (p,q,r,R) values in accordance to a tight approximation of the TK length. The adaptive resolution aims to keep the resolution at an optimal value to ensure that the generated TK curve is not under-sampled or over-sampled.

NOTE: if you want the generated TK curve to stay a TK while changing (p,q,r,R) values and not degenerate into some under-sampled artifact make sure to keep this option enabled. Alternatively if you don't want to keep the adaptive resolution ON all the time, it can be toggled ON temporarily and back OFF, which will update the resolution to the optimal sampling value.

NOTE: the adaptive resolution takes into account only (p,q,r,R) parameters and is not affected by the other plus options like "p/q multipliers". This is actually necessary/desirable since the p/q multipliers are useful only due to the under-sampling artifacts they introduce.

NOTE: the adaptive resolution is OFF by default since it may be computantilanly intensive (and less interactive) for certain (p,q,r,R) values. This slowness is primarily due to the mesh generation/display (when surface is enabled) and it does not seem to be slow when the surface is off.

Geometry Options

This is pretty much the same as the old category except that the surface "offset" property was reintroduced.

Color Options

This new category and options were added to aid with the multi-link generation to make it easier to distinguish between the decoupled links (when p/q are not co-primes). The link coloring is OFF by default but once it is turned off, each decoupled link in the TK will take one of the predefined colors. If this option is on the material slots are added with predefined colors, one for each link.

NOTE: the addon will only add link material once and reused them if they were previously created, thus avoiding poluting with new materials every time a new TK is generated.

plus options *
There are color sets defined: One is RGBish (blue, green, red, yellow etc) more contrasting colors, and the other is a Rainbow set containing gradual changing colors from blue to red. With plus option enabled the user can select between the two sets.

A randomize colors option also lets the color be randomly generated.
The color saturation can also be adjusted.

Transform Options

This category hosts the previous location and rotation properties. In addition the location property was redefined to be relative to either the 3D cursor location or relative to the WORLD origin. An toggle allows the user to switch between 3D cursor and World origin.

In the new implementation the curve can be created at the 3D cursor location.

NOTE: changing the 3D cursor location during the TK operator will regenerate the curve at the new 3D cursor location every time the user changes the parameters and a new curve is re-generated.

Presets

I also added a few presets to sample different settings (not necessarily different p/q combination).

{F259678}curve.torus_knot_plus-presets.zip

SUMMARY: - reorganize the code and regroup the UI elements into categories - add comments to code, descriptions to props and add more appropriate naming for some of the UI elements - recode to allow multiple TK link generation when (p,q) are not co-prime and also to avoid self overlapping curve. - add curve type selection: POLY, NURB, BEZIER (default) - add major/minor vs interior/exterior radii settings to define the torus geometry (typical torus formula is based on [p,q,r,R] set) - add adaptive curve resolution (off by default) using an approximate TK curve length based on [p,q,r,R] values. - make plus setting be used ONLY when the plus settings are enabled - restrict curve generation to only OBJECT mode (avoid error while adding TK curve in edit mode) - add colors for the TK links (with additional color settings as plus options) and option to toggle colors (off by default) - add multi-link generation toggle (useful for cases when (p,q) are not co-prime) - add option to flip directions for revolution (p) and spin (q) - add option to adjust phasing (revolution and spin) (plus option) - add matrix alignment to allow placement at 3D cursor and add absolute location toggle option to allow the location prop to be applied relative to the 3D cursor or relative to the world origin. Here is my git repo for the TK script developing which includes some of the incremental updates relative to the version of the add-on included in blender 2.76: https://github.com/DolphinDream/blenderAddons Also, here is the resource I used for TK curve length approximation formula (used with the adaptive curve resolution) based on my inquiry on "Mathematics Stack Exchange": http://math.stackexchange.com/questions/1523388/tight-approximation-of-a-torus-knot-length DETAILS: General Approach/Philosophy **** The intention was to revamp the TK add-on to better organize its UI but also to add some missing features, while preserving most of the original settings and everything that the previous version was able to do, whether through its main settings or its extended ("plus") options. In addition, the code was also reorganized and better documented. Plus-Option settings (update) **** On top of adding new "plus" option, the code was updated so that the "plus" settings are ONLY used when the "plus option" is enabled. E.g. it may be confusing to have the user toggle the plus option ON, change some plus option settings altering the curve, then toggle the plus option OFF and have the generated curve still use the "plus option". The new implementation makes sure that turning "plus option" on/off applies to both the UI visibility and the functionality of the plus options. Also, my approach with the plus option was to keep everything that does not generate an actual TK curve out of the main settings. For example, the "height" property distorts the TK along Z making it not a regular torus and for this reason I migrated the "height" property into the "plus option" section. NOTE: the old "scale" property was also made a "plus" options, but not because it alters the torus-ness of the curve, but because the effect the old "scale" had is currently achievable via direct manipulation of the torus radii (which were missing in the previous implementation). In the new implementation the "scale" property is redefined and is actually just a convenience property used for scaling proportionally both torus radii, which is essentially equivalent to scaling the R and r directly. When the "plus option" is enabled each category will list their corresponding plus options. Also the plus options are boxed to better distinguished between the main settings and the plus settings within each category. Categories (UI grouping) **** Aside from the previous "Torus Parameters" and "Geometry Options" categories, new categories were introduced to group together various old and new properties. The current categories are: - Torus Knot Parameters (p,q + multi link, flip) - Torus Dimensions (radii, scale/height) - Curve Options (resolutions, curve type, adaptive resolution) - Color Options (link colors) - Geometry Options (surface, extrusion) - Transform Options (location, rotation) Torus Knot Parameters **** This category hosts the main p & q parameters defining the knot. Also, with the newly added "multi-link" feature, a <Multiple Links> toggle option is added here and a <Flip p> and <Flip q> to allow the curve direction to be reversed. NOTE: flipping both p and q is equivalent to no flip. * plus options * With the "plus" options enabled this category also includes: <p multiplier> <q multiplier> <Revolution phase> <Spin phase> The p/q multipliers are exactly that: they scale the number of revolutions (p) and spins (q) the curve makes. This is typically used in conjunction with a fix curve resolution to create under-sampled artifact curves that generate "Wicker Basket" curve and other interestingly shaped curves. The revolution/spin phase allow the user to define the starting point of the curve along the revolution and the spin rotations. The effects of these parameters are more noticeable at low curve resolutions and especially for POLY curve type. At high resolution their effect is visually equivalent to a rotation along the local Z axis. Multi-Links (NEW feature) **** Based on the definition of the torus knot (https://en.wikipedia.org/wiki/Torus_knot) I noticed that the current TK add-on implementation was not generating a correct TK curve for cases where (p,q) are not co-prime. These degenerate cases correspond to a TK formed by decoupled TK links of lower order (e.g. a 4x8 TK is formed by 4 separate 1x2 TK curves). NOTE: You can check out the old TK add-on to verify that indeed a p/q = 4/8 generates the same curve as p/q = 1/2 (although the curve winds 4 times over itself). The greatest common denominator of p and q: n=gcd(p,q) determines the degree of degeneracy of the TK curve, which is the number of decoupled TK links of lower order. Each of the n lower order TK is defined by the pair (p/n, q/n). A multi-link toggle option was added (ON by default) to allow the user to generate all links of the TK or just one link (when p and q are not co-prime). This option obviously does nothing whenever p,q are co-prime since in this case there is only ONE link forming the TK. Also, by turning the multi-link option off makes the new add-on generates the same curve as the old add-on (albeit without any self overlapping curve). NOTE: multiple (decoupled) TK links are particularly interesting to generate in conjunction with link coloring to allow to visually distinguish the decoupled links. Torus Dimensions (NEW feature) **** The previous implementation had no options to alter the torus radii other that through the "scale" parameter, which was in essence scaling the Major radius of the torus. The new implementation adds the option to allow the user to directly manipulate both torus radii directly. Typically these radii are the Major (R) and the Minor (r) radii, but for convenience the equivalent set of radii (Interior/Exterior) was also added. The user can toggle between the (R,r) and (iR,eR) radii sets to alter in order to change the torus geometry. * plus options * With "plus" options the "Torus Dimensions" category also includes the <scale> and <height> properties. The <Scale> scales both the minor and the major radii proportionally being equivalent to a proportional scaling of the whole curve (in edit mode). The <height> property scales the curve along Z axis (just like before). Curve Options (NEW features) **** Add the option to select the curve type (POLY, NURB, BEZIER) and relocated the curve resolution and the segment resolution properties into this category. NOTE: the previous "curve resolution" property was ambiguously called "Resolution" while the segment resolution was called "resolution". In current implementation these are "Curve Resolution" and "Segment Resolution" and they represent the number of control points per curve and the number of points per segment respectively. Adaptive Resolution ------------------- To this section was also added an "adaptive resolution" toggle option (OFF by default) to allow the resolution to be automatically set based on the (p,q,r,R) values in accordance to a tight approximation of the TK length. The adaptive resolution aims to keep the resolution at an optimal value to ensure that the generated TK curve is not under-sampled or over-sampled. NOTE: if you want the generated TK curve to stay a TK while changing (p,q,r,R) values and not degenerate into some under-sampled artifact make sure to keep this option enabled. Alternatively if you don't want to keep the adaptive resolution ON all the time, it can be toggled ON temporarily and back OFF, which will update the resolution to the optimal sampling value. NOTE: the adaptive resolution takes into account only (p,q,r,R) parameters and is not affected by the other plus options like "p/q multipliers". This is actually necessary/desirable since the p/q multipliers are useful only due to the under-sampling artifacts they introduce. NOTE: the adaptive resolution is OFF by default since it may be computantilanly intensive (and less interactive) for certain (p,q,r,R) values. This slowness is primarily due to the mesh generation/display (when surface is enabled) and it does not seem to be slow when the surface is off. Geometry Options **** This is pretty much the same as the old category except that the surface "offset" property was reintroduced. Color Options **** This new category and options were added to aid with the multi-link generation to make it easier to distinguish between the decoupled links (when p/q are not co-primes). The link coloring is OFF by default but once it is turned off, each decoupled link in the TK will take one of the predefined colors. If this option is on the material slots are added with predefined colors, one for each link. NOTE: the addon will only add link material once and reused them if they were previously created, thus avoiding poluting with new materials every time a new TK is generated. * plus options * There are color sets defined: One is RGBish (blue, green, red, yellow etc) more contrasting colors, and the other is a Rainbow set containing gradual changing colors from blue to red. With plus option enabled the user can select between the two sets. A randomize colors option also lets the color be randomly generated. The color saturation can also be adjusted. Transform Options **** This category hosts the previous location and rotation properties. In addition the location property was redefined to be relative to either the 3D cursor location or relative to the WORLD origin. An <Absolute Location> toggle allows the user to switch between 3D cursor and World origin. In the new implementation the curve can be created at the 3D cursor location. NOTE: changing the 3D cursor location during the TK operator will regenerate the curve at the new 3D cursor location every time the user changes the parameters and a new curve is re-generated. Presets **** I also added a few presets to sample different settings (not necessarily different p/q combination). {[F259678](https://archive.blender.org/developer/F259678/add_curve_torus_knots.py)}[curve.torus_knot_plus-presets.zip](https://archive.blender.org/developer/F259679/curve.torus_knot_plus-presets.zip)

Dolphin Dream commented

2015-11-28 08:37:53 +01:00

Changed status to: 'Open'

Dolphin Dream commented

2015-11-28 08:37:53 +01:00

Added subscriber: @MariusGiurgi

Dolphin Dream commented

2015-11-28 08:40:35 +01:00

Here is also a screen capture collage illustrating the UI props remapping between the old and the new implementation. The colors indicate where each property was relocated. The white marks indicate the newly added properties.

Here is also a screen capture collage illustrating the UI props remapping between the old and the new implementation. The colors indicate where each property was relocated. The white marks indicate the newly added properties. ![TorusKnot-UpdateOverview.jpg](https://archive.blender.org/developer/F259680/TorusKnot-UpdateOverview.jpg)

Brendon Murphy self-assigned this 2015-11-28 09:29:24 +01:00

Bastien Montagne commented

2015-11-28 09:31:34 +01:00

Added subscriber: @mont29

Brendon Murphy commented

2015-11-28 09:50:50 +01:00

hi, thanks for the great update, I'll look at merging in to add_curve _extra_objects soon.

Brendon Murphy commented

2015-12-04 08:11:03 +01:00

Added subscriber: @florianfelix

Brendon Murphy commented

2015-12-04 08:11:04 +01:00

@florianfelix
looks great to me.

@florianfelix looks great to me.

Brendon Murphy commented

2015-12-05 01:26:42 +01:00

Added subscriber: @ideasman42

Brendon Murphy commented

2015-12-05 01:26:42 +01:00

@MariusGiurgi I;ve tested the addon, looked at the code & it works well. thanks again.
I did notice the use of from bpy.props import *
it's better to list the props your using, could you fix that section please.
It's important that @ideasman42 gives you access to our git repo, I know your very familiar with git which is great.

As I'm the current maintainer of Add_Curve: Extra_Objects & the addons contained within, I'm very happy you wish to maintain part of this addon.

Thanks

@MariusGiurgi I;ve tested the addon, looked at the code & it works well. thanks again. I did notice the use of from bpy.props import * it's better to list the props your using, could you fix that section please. It's important that @ideasman42 gives you access to our git repo, I know your very familiar with git which is great. As I'm the current maintainer of Add_Curve: Extra_Objects & the addons contained within, I'm very happy you wish to maintain part of this addon. Thanks

Campbell Barton commented

2015-12-05 02:04:34 +01:00

@MariusGiurgi, I've added you to the addons project,
See: http://wiki.blender.org/index.php/Dev:Doc/Tools/Git#Commit_Access
for details on uploading ssh keys & committing.

@MariusGiurgi, I've added you to the addons project, See: http://wiki.blender.org/index.php/Dev:Doc/Tools/Git#Commit_Access for details on uploading ssh keys & committing.

Dolphin Dream commented

2015-12-07 03:26:24 +01:00

Great. Thanks for the flowers.. and the commit access :) I made the requested changes (e.g. import specific properties instead of import *) and here’s the updated version (plus other minor cleanup edits) of the add-on and the presets.

Note: for what his worth.. you can check the history of the incremental changes on my github repo: 0c3f07ffcb)

add_curve_torus_knots.py presets_torus_knot_plus.zip

Great. Thanks for the flowers.. and the commit access :) I made the requested changes (e.g. import specific properties instead of import *) and here’s the updated version (plus other minor cleanup edits) of the add-on and the presets. Note: for what his worth.. you can check the history of the incremental changes on my github repo: https://github.com/DolphinDream/blenderAddons/commit/0c3f07ffcb21c5272b7e04bca115e3794d582baf) [add_curve_torus_knots.py](https://archive.blender.org/developer/F263649/add_curve_torus_knots.py) [presets_torus_knot_plus.zip](https://archive.blender.org/developer/F263714/presets_torus_knot_plus.zip)

blender-admin commented

2015-12-07 04:33:06 +01:00

This issue was referenced by 80853daea9

This issue was referenced by 80853daea9394b9135bef342eefa0150a1c1a5f8

Dolphin Dream commented

2015-12-07 06:21:09 +01:00

Changed status from 'Open' to: 'Resolved'

Dolphin Dream closed this issue

2015-12-07 06:21:09 +01:00

Sign in to join this conversation.