[sixth-3d.git] /

/*
 * Sixth 3D engine. Author: Svjatoslav Agejenko.
 * This project is released under Creative Commons Zero (CC0) license.
 */
package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.wireframe;

import eu.svjatoslav.sixth.e3d.geometry.Point3D;
import eu.svjatoslav.sixth.e3d.math.Matrix3x3;
import eu.svjatoslav.sixth.e3d.math.Quaternion;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.line.LineAppearance;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.base.AbstractCompositeShape;

/**
 * A 3D wireframe arrow shape composed of a cylindrical body and a conical tip.
 *
 * <p>The arrow points from a start point to an end point, with the tip
 * located at the end point. The wireframe consists of:</p>
 * <ul>
 *   <li><b>Body:</b> Two circular rings connected by lines between corresponding vertices</li>
 *   <li><b>Tip:</b> A circular ring at the cone base with lines to the apex</li>
 * </ul>
 *
 * <p><b>Usage example:</b></p>
 * <pre>{@code
 * // Create a red arrow pointing from origin to (100, -50, 200)
 * LineAppearance appearance = new LineAppearance(2, Color.RED);
 * WireframeArrow arrow = new WireframeArrow(
 *     new Point3D(0, 0, 0),      // start point
 *     new Point3D(100, -50, 200), // end point
 *     8,                         // body radius
 *     20,                        // tip radius
 *     40,                        // tip length
 *     16,                        // segments
 *     appearance
 * );
 * shapeCollection.addShape(arrow);
 * }</pre>
 *
 * @see WireframeCone
 * @see WireframeCylinder
 * @see eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.solid.SolidPolygonArrow
 */
public class WireframeArrow extends AbstractCompositeShape {

    /**
     * Constructs a 3D wireframe arrow pointing from start to end.
     *
     * <p>The arrow consists of a cylindrical body extending from the start point
     * towards the end, and a conical tip at the end point. If the distance between
     * start and end is less than or equal to the tip length, only the cone tip
     * is rendered.</p>
     *
     * @param startPoint  the origin point of the arrow (where the body starts)
     * @param endPoint    the destination point of the arrow (where the tip points to)
     * @param bodyRadius  the radius of the cylindrical body
     * @param tipRadius   the radius of the cone base at the tip
     * @param tipLength   the length of the conical tip
     * @param segments    the number of segments for cylinder and cone smoothness.
     *                    Higher values create smoother arrows. Minimum is 3.
     * @param appearance  the line appearance (color, width) used for all lines
     */
    public WireframeArrow(final Point3D startPoint, final Point3D endPoint,
                          final double bodyRadius, final double tipRadius,
                          final double tipLength, final int segments,
                          final LineAppearance appearance) {
        super();

        // Calculate direction and distance
        final double dx = endPoint.x - startPoint.x;
        final double dy = endPoint.y - startPoint.y;
        final double dz = endPoint.z - startPoint.z;
        final double distance = Math.sqrt(dx * dx + dy * dy + dz * dz);

        // Handle degenerate case: start and end are the same point
        if (distance < 0.001) {
            return;
        }

        // Normalize direction vector
        final double nx = dx / distance;
        final double ny = dy / distance;
        final double nz = dz / distance;

        // Calculate rotation to align Y-axis with direction
        // Default arrow points in -Y direction (apex at lower Y)
        // We need to rotate from (0, -1, 0) to (nx, ny, nz)
        final Quaternion rotation = createRotationFromYAxis(nx, ny, nz);
        final Matrix3x3 rotMatrix = rotation.toMatrix();

        // Calculate body length (distance minus tip)
        final double bodyLength = Math.max(0, distance - tipLength);

        // Build the arrow components
        if (bodyLength > 0) {
            addCylinderBody(startPoint, bodyRadius, bodyLength, segments, appearance, rotMatrix, nx, ny, nz);
        }
        addConeTip(endPoint, tipRadius, tipLength, segments, appearance, rotMatrix, nx, ny, nz);
    }

    /**
     * Creates a quaternion that rotates from the -Y axis to the given direction.
     *
     * <p>The arrow by default points in the -Y direction. This method computes
     * the rotation needed to align the arrow with the target direction vector.</p>
     *
     * @param nx normalized direction X component
     * @param ny normalized direction Y component
     * @param nz normalized direction Z component
     * @return quaternion representing the rotation
     */
    private Quaternion createRotationFromYAxis(final double nx, final double ny, final double nz) {
        // Default direction is -Y (0, -1, 0)
        // Target direction is (nx, ny, nz)
        // Dot product: 0*nx + (-1)*ny + 0*nz = -ny
        final double dot = -ny;

        // Check for parallel vectors
        if (dot > 0.9999) {
            // Direction is nearly -Y, no rotation needed
            return Quaternion.identity();
        }
        if (dot < -0.9999) {
            // Direction is nearly +Y, rotate 180° around X axis
            return Quaternion.fromAxisAngle(new Point3D(1, 0, 0), Math.PI);
        }

        // Cross product: (0, -1, 0) x (nx, ny, nz) = (-nz, 0, nx)
        // This gives the rotation axis
        final double axisX = -nz;
        final double axisY = 0;
        final double axisZ = nx;
        final double axisLength = Math.sqrt(axisX * axisX + axisY * axisY + axisZ * axisZ);
        final double normalizedAxisX = axisX / axisLength;
        final double normalizedAxisZ = axisZ / axisLength;

        // Angle from dot product
        final double angle = Math.acos(dot);

        return Quaternion.fromAxisAngle(
                new Point3D(normalizedAxisX, 0, normalizedAxisZ), angle);
    }

    /**
     * Adds the cylindrical body of the arrow.
     *
     * <p><b>Local coordinate system:</b> The arrow points in -Y direction in local space.
     * Therefore, local -Y is toward the tip (front), and local +Y is toward the start (back).</p>
     *
     * @param startPoint the origin of the arrow body
     * @param radius     the radius of the cylinder
     * @param length     the length of the cylinder
     * @param segments   the number of segments around the circumference
     * @param appearance the line appearance
     * @param rotMatrix  the rotation matrix to apply
     * @param dirX       direction X component (for translation calculation)
     * @param dirY       direction Y component
     * @param dirZ       direction Z component
     */
    private void addCylinderBody(final Point3D startPoint, final double radius,
                                 final double length, final int segments,
                                 final LineAppearance appearance, final Matrix3x3 rotMatrix,
                                 final double dirX, final double dirY, final double dirZ) {
        // Cylinder center is at startPoint + (length/2) * direction
        final double centerX = startPoint.x + (length / 2.0) * dirX;
        final double centerY = startPoint.y + (length / 2.0) * dirY;
        final double centerZ = startPoint.z + (length / 2.0) * dirZ;

        // Generate ring vertices in local space, then rotate and translate
        // Arrow points in -Y direction, so:
        //   - tipSideRing is at local -Y (toward arrow tip, front of cylinder)
        //   - startSideRing is at local +Y (toward arrow start, back of cylinder)
        final Point3D[] tipSideRing = new Point3D[segments];
        final Point3D[] startSideRing = new Point3D[segments];

        final double halfLength = length / 2.0;

        for (int i = 0; i < segments; i++) {
            final double angle = 2.0 * Math.PI * i / segments;
            final double localX = radius * Math.cos(angle);
            final double localZ = radius * Math.sin(angle);

            // Tip-side ring (at -halfLength in local Y = toward arrow tip)
            final Point3D tipSideLocal = new Point3D(localX, -halfLength, localZ);
            rotMatrix.transform(tipSideLocal, tipSideLocal);
            tipSideLocal.x += centerX;
            tipSideLocal.y += centerY;
            tipSideLocal.z += centerZ;
            tipSideRing[i] = tipSideLocal;

            // Start-side ring (at +halfLength in local Y = toward arrow start)
            final Point3D startSideLocal = new Point3D(localX, halfLength, localZ);
            rotMatrix.transform(startSideLocal, startSideLocal);
            startSideLocal.x += centerX;
            startSideLocal.y += centerY;
            startSideLocal.z += centerZ;
            startSideRing[i] = startSideLocal;
        }

        // Create the circular rings
        for (int i = 0; i < segments; i++) {
            final int next = (i + 1) % segments;

            // Tip-side ring line segment
            addShape(appearance.getLine(
                    new Point3D(tipSideRing[i].x, tipSideRing[i].y, tipSideRing[i].z),
                    new Point3D(tipSideRing[next].x, tipSideRing[next].y, tipSideRing[next].z)));

            // Start-side ring line segment
            addShape(appearance.getLine(
                    new Point3D(startSideRing[i].x, startSideRing[i].y, startSideRing[i].z),
                    new Point3D(startSideRing[next].x, startSideRing[next].y, startSideRing[next].z)));
        }

        // Create vertical lines connecting the two rings
        for (int i = 0; i < segments; i++) {
            addShape(appearance.getLine(
                    new Point3D(tipSideRing[i].x, tipSideRing[i].y, tipSideRing[i].z),
                    new Point3D(startSideRing[i].x, startSideRing[i].y, startSideRing[i].z)));
        }
    }

    /**
     * Adds the conical tip of the arrow.
     *
     * <p><b>Local coordinate system:</b> In local space, the cone points in -Y direction
     * (apex at lower Y). The base ring is at Y=0, and the apex is at Y=-length.</p>
     *
     * @param endPoint   the position of the arrow tip (cone apex)
     * @param radius     the radius of the cone base
     * @param length     the length of the cone
     * @param segments   the number of segments around the circumference
     * @param appearance the line appearance
     * @param rotMatrix  the rotation matrix to apply
     * @param dirX       direction X component
     * @param dirY       direction Y component
     * @param dirZ       direction Z component
     */
    private void addConeTip(final Point3D endPoint, final double radius,
                            final double length, final int segments,
                            final LineAppearance appearance, final Matrix3x3 rotMatrix,
                            final double dirX, final double dirY, final double dirZ) {
        // Apex is at endPoint (the arrow tip)
        // Base center is at endPoint - length * direction (toward arrow start)
        final double baseCenterX = endPoint.x - length * dirX;
        final double baseCenterY = endPoint.y - length * dirY;
        final double baseCenterZ = endPoint.z - length * dirZ;

        // Generate base ring vertices
        // In local space, cone points in -Y direction, so base is at Y=0
        final Point3D[] baseRing = new Point3D[segments];

        for (int i = 0; i < segments; i++) {
            final double angle = 2.0 * Math.PI * i / segments;
            final double localX = radius * Math.cos(angle);
            final double localZ = radius * Math.sin(angle);

            // Base ring vertices at local Y=0
            final Point3D local = new Point3D(localX, 0, localZ);
            rotMatrix.transform(local, local);
            local.x += baseCenterX;
            local.y += baseCenterY;
            local.z += baseCenterZ;
            baseRing[i] = local;
        }

        // Apex point (the arrow tip)
        final Point3D apex = new Point3D(endPoint.x, endPoint.y, endPoint.z);

        // Create the circular base ring
        for (int i = 0; i < segments; i++) {
            final int next = (i + 1) % segments;
            addShape(appearance.getLine(
                    new Point3D(baseRing[i].x, baseRing[i].y, baseRing[i].z),
                    new Point3D(baseRing[next].x, baseRing[next].y, baseRing[next].z)));
        }

        // Create lines from apex to each base vertex
        for (int i = 0; i < segments; i++) {
            addShape(appearance.getLine(
                    new Point3D(apex.x, apex.y, apex.z),
                    new Point3D(baseRing[i].x, baseRing[i].y, baseRing[i].z)));
        }
    }
}