Add linkDirectionalParticleCanvasObject, linkDirectionalParticleThreeObject and linkDirectionalParticleOffset props

Author: vasturiano

README.md

@@ -155,7 +155,7 @@ Note that not all props listed below apply to all 4 components. The last 4 colum
 | <b>linkCurvature</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Link object accessor function, attribute or a numeric constant for the curvature radius of the link line. A value of `0` renders a straight line. `1` indicates a radius equal to half of the line length, causing the curve to approximate a semi-circle. For self-referencing links (`source` equal to `target`) the curve is represented as a loop around the node, with length proportional to the curvature value. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkCurveRotation</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Link object accessor function, attribute or a numeric constant for the rotation along the line axis to apply to the curve. Has no effect on straight lines. At `0` rotation, the curve is oriented in the direction of the intersection with the `XY` plane. The rotation angle (in radians) will rotate the curved line clockwise around the "start-to-end" axis from this reference orientation. |  | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkMaterial</b> | <i>Material</i>, <i>string</i> or <i>func</i> | *default link material is [MeshLambertMaterial](https://threejs.org/docs/#api/materials/MeshLambertMaterial) styled according to `color` and `opacity`.* | Link object accessor function or attribute for specifying a custom material to style the graph links with. Should return an instance of [ThreeJS Material](https://threejs.org/docs/#api/materials/Material). If a <i>falsy</i> value is returned, the default material will be used instead for that link. | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| <b>linkCanvasObject</b> | <i>func</i> | *default 2D link object is a line, styled according to `width` and `color`.* | Callback function for painting a custom canvas object to represent graph links. Should use the provided canvas context attribute to perform drawing operations for each link. The callback function will be called for each link at every frame, and has the signature: `.linkCanvasObject(<link>, <canvas context>, <current global scale>)`. | :heavy_check_mark: | | | |
+| <b>linkCanvasObject</b> | <i>func</i> | *default 2D link object is a line, styled according to `width` and `color`.* | Callback function for painting a custom canvas object to represent graph links. Should use the provided canvas context attribute to perform drawing operations for each link. The callback function will be called for each link at every frame, and has the signature: `linkCanvasObject(<link>, <canvas context>, <current global scale>)`. | :heavy_check_mark: | | | |
 | <b>linkCanvasObjectMode</b> | <i>string</i> or <i>func</i> | `() => 'replace'` | Link object accessor function or attribute for the custom drawing mode. Use in combination with `linkCanvasObject` to specify how to customize links painting. Possible values are: <ul><li>`replace`: the link is rendered using just `linkCanvasObject`.</li><li>`before`: the link is rendered by invoking `linkCanvasObject` and then proceeding with the default link painting.</li><li>`after`: `linkCanvasObject` is applied after the default link painting takes place.</li></ul>Any other value will be ignored and the default drawing will be applied. | :heavy_check_mark: | | | |
 | <b>linkThreeObject</b> | <i>Object3d</i>, <i>string</i> or <i>func</i> | *default 3D link object is a line or cylinder, sized according to `width` and styled according to `material`.* | Link object accessor function or attribute for generating a custom 3d object to render as graph links. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). If a <i>falsy</i> value is returned, the default 3d object type will be used instead for that link. | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkThreeObjectExtend</b> | <i>bool</i>, <i>string</i> or <i>func</i> | `false` | Link object accessor function, attribute or a boolean value for whether to replace the default link when using a custom `linkThreeObject` (`false`) or to extend it (`true`). | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
@@ -166,13 +166,16 @@ Note that not all props listed below apply to all 4 components. The last 4 colum
 | <b>linkDirectionalArrowResolution</b> | <i>number</i> | 8 | Geometric resolution of the arrow head, expressed in how many slice segments to divide the cone base circumference. Higher values yield smoother arrows. | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticles</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Link object accessor function, attribute or a numeric constant for the number of particles (small spheres) to display over the link line. The particles are distributed equi-spaced along the line, travel in the direction `source` > `target`, and can be used to indicate link directionality. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticleSpeed</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.01 | Link object accessor function, attribute or a numeric constant for the directional particles speed, expressed as the ratio of the link length to travel per frame. Values above `0.5` are discouraged. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| <b>linkDirectionalParticleOffset</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0 | Link object accessor function, attribute or a numeric constant for the offset of the directional particles initial position, expressed as a value between 0 and 1, relative to a full position cycle. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticleWidth</b> | <i>number</i>, <i>string</i> or <i>func</i> | 0.5 | Link object accessor function, attribute or a numeric constant for the directional particles width. Values are rounded to the nearest decimal for indexing purposes. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticleColor</b> | <i>string</i> or <i>func</i> | `color` | Link object accessor function or attribute for the directional particles color. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticleResolution</b> | <i>number</i> | 4 | Geometric resolution of each 3D directional particle, expressed in how many slice segments to divide the circumference. Higher values yield smoother particles. | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| <b>linkDirectionalParticleCanvasObject</b> | <i>func</i> | | Callback function for painting custom link particles. Should use the provided canvas context attribute to perform drawing operations for each particle. The callback function will be called for each particle in each link at every frame, and has the signature: `linkDirectionalParticleCanvasObject(<x>, <y>, <link>, <canvas context>, <current global scale>)`. | :heavy_check_mark: | | | |
+| <b>linkDirectionalParticleThreeObject</b> | <i>Object3d</i>, <i>string</i> or <i>func</i> || Link object accessor function or attribute for a custom 3d object to use in the directional particles. Should return an instance of [ThreeJS Object3d](https://threejs.org/docs/index.html#api/core/Object3D). Activating this will ignore the set values for the particle's width, color and resolution. | | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 
 | Method | Arguments | Description | 2D | 3D | VR | AR |
 | --- | :--: | --- | :--: | :--: | :--: | :--: |
-| <b>emitParticle</b> | (<i>link</i>) | An alternative mechanism for generating particles, this method emits a non-cyclical single particle within a specific link. The emitted particle shares the styling (speed, width, color) of the regular particle props. A valid `link` object that is included in `graphData` should be passed as a single parameter. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| <b>emitParticle</b> | (<i>link</i>) | An alternative mechanism for generating particles, this method emits a non-cyclical single particle within a specific link. The emitted particle shares the styling (speed, shape, color) of the regular particle props. A valid `link` object that is included in `graphData` should be passed as a single parameter. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 
 ### Render control
 

src/forcegraph-proptypes.js

@@ -30,6 +30,7 @@ const commonPropTypes = {
   linkDirectionalArrowRelPos: PropTypes.oneOfType([PropTypes.number, PropTypes.string, PropTypes.func]),
   linkDirectionalParticles: PropTypes.oneOfType([PropTypes.number, PropTypes.string, PropTypes.func]),
   linkDirectionalParticleSpeed: PropTypes.oneOfType([PropTypes.number, PropTypes.string, PropTypes.func]),
+  linkDirectionalParticleOffset: PropTypes.oneOfType([PropTypes.number, PropTypes.string, PropTypes.func]),
   linkDirectionalParticleWidth: PropTypes.oneOfType([PropTypes.number, PropTypes.string, PropTypes.func]),
   linkDirectionalParticleColor: PropTypes.oneOfType([PropTypes.string, PropTypes.func]),
   onLinkHover: PropTypes.func,
@@ -78,6 +79,7 @@ const threeBasedPropTypes = {
   linkPositionUpdate: PropTypes.func,
   linkDirectionalArrowResolution: PropTypes.number,
   linkDirectionalParticleResolution: PropTypes.number,
+  linkDirectionalParticleThreeObject: PropTypes.oneOfType([PropTypes.object, PropTypes.string, PropTypes.func]),
   forceEngine: PropTypes.oneOf(['d3', 'ngraph']),
   ngraphPhysics: PropTypes.object,
   numDimensions: PropTypes.oneOf([1, 2, 3])
@@ -94,6 +96,7 @@ export const ForceGraph2DPropTypes = Object.assign({},
     linkCanvasObjectMode: PropTypes.oneOfType([PropTypes.string, PropTypes.func]),
     linkCanvasObject: PropTypes.func,
     linkPointerAreaPaint: PropTypes.func,
+    linkDirectionalParticleCanvasObject: PropTypes.func,
     autoPauseRedraw: PropTypes.bool,
     minZoom: PropTypes.number,
     maxZoom: PropTypes.number,

src/packages/react-force-graph-2d/index.d.ts

@@ -82,8 +82,10 @@ export interface ForceGraphProps<
   linkDirectionalArrowRelPos?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticles?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleSpeed?: LinkAccessor<NodeType, LinkType, number>;
+  linkDirectionalParticleOffset?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleWidth?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleColor?: LinkAccessor<NodeType, LinkType, string>;
+  linkDirectionalParticleCanvasObject?: (x: number, y: number, link: LinkType, canvasContext: CanvasRenderingContext2D, globalScale: number) => void;
   linkPointerAreaPaint?: CanvasPointerAreaPaintFn<LinkObject<NodeType, LinkType>>;
 
   // Render control

src/packages/react-force-graph-3d/index.d.ts

@@ -98,9 +98,11 @@ export interface ForceGraphProps<
   linkDirectionalArrowResolution?: number;
   linkDirectionalParticles?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleSpeed?: LinkAccessor<NodeType, LinkType, number>;
+  linkDirectionalParticleOffset?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleWidth?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleColor?: LinkAccessor<NodeType, LinkType, string>;
   linkDirectionalParticleResolution?: number;
+  linkDirectionalParticleThreeObject?: LinkAccessor<NodeType, LinkType, Object3D>;
 
   // Force engine (d3-force) configuration
   forceEngine?: ForceEngine;

src/packages/react-force-graph-ar/index.d.ts

@@ -91,9 +91,11 @@ export interface ForceGraphProps<
   linkDirectionalArrowResolution?: number;
   linkDirectionalParticles?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleSpeed?: LinkAccessor<NodeType, LinkType, number>;
+  linkDirectionalParticleOffset?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleWidth?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleColor?: LinkAccessor<NodeType, LinkType, string>;
   linkDirectionalParticleResolution?: number;
+  linkDirectionalParticleThreeObject?: LinkAccessor<NodeType, LinkType, Object3D>;
 
   // Force engine (d3-force) configuration
   forceEngine?: ForceEngine;

src/packages/react-force-graph-vr/index.d.ts

@@ -95,9 +95,11 @@ export interface ForceGraphProps<
   linkDirectionalArrowResolution?: number;
   linkDirectionalParticles?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleSpeed?: LinkAccessor<NodeType, LinkType, number>;
+  linkDirectionalParticleOffset?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleWidth?: LinkAccessor<NodeType, LinkType, number>;
   linkDirectionalParticleColor?: LinkAccessor<NodeType, LinkType, string>;
   linkDirectionalParticleResolution?: number;
+  linkDirectionalParticleThreeObject?: LinkAccessor<NodeType, LinkType, Object3D>;
 
   // Force engine (d3-force) configuration
   forceEngine?: ForceEngine;