[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.solid;

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.Color;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.solidpolygon.SolidPolygon;
import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.composite.base.AbstractCompositeShape;

/**
 * A solid square-based pyramid that can be oriented in any direction.
 *
 * <p>The pyramid has a square base and four triangular faces meeting at an apex
 * (tip). Two constructors are provided for different use cases:</p>
 *
 * <ul>
 *   <li><b>Directional (recommended):</b> Specify apex point and base center point.
 *       The pyramid points from apex toward the base center. This allows arbitrary
 *       orientation and is the most intuitive API.</li>
 *   <li><b>Y-axis aligned:</b> Specify base center, base size, and height. The pyramid
 *       points in -Y direction (apex at lower Y). Useful for simple vertical pyramids.</li>
 * </ul>
 *
 * <p><b>Usage examples:</b></p>
 * <pre>{@code
 * // Directional constructor: pyramid pointing from apex toward base
 * SolidPolygonPyramid directionalPyramid = new SolidPolygonPyramid(
 *     new Point3D(0, -100, 0),   // apex (tip of the pyramid)
 *     new Point3D(0, 50, 0),     // baseCenter (pyramid points toward this)
 *     50,                        // baseSize (half-width of square base)
 *     Color.RED
 * );
 *
 * // Y-axis aligned constructor: pyramid pointing upward
 * SolidPolygonPyramid verticalPyramid = new SolidPolygonPyramid(
 *     new Point3D(0, 0, 300),    // baseCenter
 *     50,                        // baseSize (half-width of square base)
 *     100,                       // height
 *     Color.BLUE
 * );
 * }</pre>
 *
 * @see SolidPolygonCone
 * @see SolidPolygonCube
 * @see SolidPolygon
 */
public class SolidPolygonPyramid extends AbstractCompositeShape {

    /**
     * Constructs a solid square-based pyramid pointing from apex toward base center.
     *
     * <p>This is the recommended constructor for placing pyramids in 3D space.
     * The pyramid's apex (tip) is at {@code apexPoint}, and the square base
     * is centered at {@code baseCenter}. The pyramid points in the direction
     * from apex to base center.</p>
     *
     * <p><b>Coordinate interpretation:</b></p>
     * <ul>
     *   <li>{@code apexPoint} - the sharp tip of the pyramid</li>
     *   <li>{@code baseCenter} - the center of the square base; the pyramid
     *       "points" in this direction from the apex</li>
     *   <li>{@code baseSize} - half the width of the square base; the base
     *       extends this distance from the center along perpendicular axes</li>
     *   <li>The distance between apex and base center determines the pyramid height</li>
     * </ul>
     *
     * @param apexPoint  the position of the pyramid's tip (apex)
     * @param baseCenter the center point of the square base; the pyramid
     *                   points from apex toward this point
     * @param baseSize   the half-width of the square base; the base extends
     *                   this distance from the center, giving a total base
     *                   edge length of {@code 2 * baseSize}
     * @param color      the fill color applied to all faces of the pyramid
     */
    public SolidPolygonPyramid(final Point3D apexPoint, final Point3D baseCenter,
                               final double baseSize, final Color color) {
        super();

        // Calculate direction and height from apex to base center
        final double dx = baseCenter.x - apexPoint.x;
        final double dy = baseCenter.y - apexPoint.y;
        final double dz = baseCenter.z - apexPoint.z;
        final double height = Math.sqrt(dx * dx + dy * dy + dz * dz);

        // Handle degenerate case: apex and base center are the same point
        if (height < 0.001) {
            return;
        }

        // Normalize direction vector (from apex toward base)
        final double nx = dx / height;
        final double ny = dy / height;
        final double nz = dz / height;

        // Calculate rotation to align Y-axis with direction
        // Default pyramid points in -Y direction (apex at origin, base at -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();

        // Generate base corner vertices in local space, then rotate and translate
        // In local space: apex is at origin, base is at Y = -height
        // Base corners form a square centered at (0, -height, 0)
        final double h = baseSize;
        final Point3D[] baseCorners = new Point3D[4];

        // Local space corner positions (before rotation)
        // Arranged clockwise when viewed from apex (from +Y)
        final double[][] localCorners = {
                {-h, -height, -h},  // corner 0: negative X, negative Z
                {+h, -height, -h},  // corner 1: positive X, negative Z
                {+h, -height, +h},  // corner 2: positive X, positive Z
                {-h, -height, +h}   // corner 3: negative X, positive Z
        };

        for (int i = 0; i < 4; i++) {
            final Point3D local = new Point3D(localCorners[i][0], localCorners[i][1], localCorners[i][2]);
            rotMatrix.transform(local, local);
            local.x += apexPoint.x;
            local.y += apexPoint.y;
            local.z += apexPoint.z;
            baseCorners[i] = local;
        }

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

        // Create the four triangular faces connecting apex to base edges
        // Winding: next → current → apex creates CCW winding when viewed from outside
        // (Base corners go CW when viewed from apex, so we reverse to get outward normals)
        for (int i = 0; i < 4; i++) {
            final int next = (i + 1) % 4;
            addShape(new SolidPolygon(
                    new Point3D(baseCorners[next].x, baseCorners[next].y, baseCorners[next].z),
                    new Point3D(baseCorners[i].x, baseCorners[i].y, baseCorners[i].z),
                    new Point3D(apex.x, apex.y, apex.z),
                    color));
        }

        // Create base cap (square bottom face)
        // The cap faces away from the apex (in the direction the pyramid points).
        // Base corners go CW when viewed from apex, so CW when viewed from apex means
        // CCW when viewed from outside (base side). Use CCW ordering for outward normal.
        // Triangulate the square base: (center, 3, 0) and (center, 0, 1) and
        // (center, 1, 2) and (center, 2, 3)
        addShape(new SolidPolygon(
                new Point3D(baseCenter.x, baseCenter.y, baseCenter.z),
                new Point3D(baseCorners[3].x, baseCorners[3].y, baseCorners[3].z),
                new Point3D(baseCorners[0].x, baseCorners[0].y, baseCorners[0].z),
                color));
        addShape(new SolidPolygon(
                new Point3D(baseCenter.x, baseCenter.y, baseCenter.z),
                new Point3D(baseCorners[0].x, baseCorners[0].y, baseCorners[0].z),
                new Point3D(baseCorners[1].x, baseCorners[1].y, baseCorners[1].z),
                color));
        addShape(new SolidPolygon(
                new Point3D(baseCenter.x, baseCenter.y, baseCenter.z),
                new Point3D(baseCorners[1].x, baseCorners[1].y, baseCorners[1].z),
                new Point3D(baseCorners[2].x, baseCorners[2].y, baseCorners[2].z),
                color));
        addShape(new SolidPolygon(
                new Point3D(baseCenter.x, baseCenter.y, baseCenter.z),
                new Point3D(baseCorners[2].x, baseCorners[2].y, baseCorners[2].z),
                new Point3D(baseCorners[3].x, baseCorners[3].y, baseCorners[3].z),
                color));

        setBackfaceCulling(true);
    }

    /**
     * Constructs a solid square-based pyramid with base centered at the given point,
     * pointing in the -Y direction.
     *
     * <p>This constructor creates a Y-axis aligned pyramid. The apex is positioned
     * at {@code baseCenter.y - height} (above the base in the negative Y direction).
     * For pyramids pointing in arbitrary directions, use
     * {@link #SolidPolygonPyramid(Point3D, Point3D, double, Color)} instead.</p>
     *
     * <p><b>Coordinate system:</b> The pyramid points in -Y direction (apex at lower Y).
     * The base is at Y=baseCenter.y, and the apex is at Y=baseCenter.y - height.
     * In Sixth 3D's coordinate system, "up" visually is negative Y.</p>
     *
     * @param baseCenter the center point of the pyramid's base in 3D space
     * @param baseSize   the half-width of the square base; the base extends
     *                   this distance from the center along X and Z axes,
     *                   giving a total base edge length of {@code 2 * baseSize}
     * @param height     the height of the pyramid from base center to apex
     * @param color      the fill color applied to all faces of the pyramid
     */
    public SolidPolygonPyramid(final Point3D baseCenter, final double baseSize,
                               final double height, final Color color) {
        super();

        final double halfBase = baseSize;
        final double apexY = baseCenter.y - height;
        final double baseY = baseCenter.y;

        // Base corners arranged clockwise when viewed from above (+Y)
        // Naming: "negative/positive X" and "negative/positive Z" relative to base center
        final Point3D negXnegZ = new Point3D(baseCenter.x - halfBase, baseY, baseCenter.z - halfBase);
        final Point3D posXnegZ = new Point3D(baseCenter.x + halfBase, baseY, baseCenter.z - halfBase);
        final Point3D posXposZ = new Point3D(baseCenter.x + halfBase, baseY, baseCenter.z + halfBase);
        final Point3D negXposZ = new Point3D(baseCenter.x - halfBase, baseY, baseCenter.z + halfBase);
        final Point3D apex = new Point3D(baseCenter.x, apexY, baseCenter.z);

        // Four triangular faces from apex to base edges
        // Winding: apex → current → next creates CCW when viewed from outside
        addShape(new SolidPolygon(negXnegZ, posXnegZ, apex, color));
        addShape(new SolidPolygon(posXnegZ, posXposZ, apex, color));
        addShape(new SolidPolygon(posXposZ, negXposZ, apex, color));
        addShape(new SolidPolygon(negXposZ, negXnegZ, apex, color));

        // Base cap (square bottom face)
        // Cap faces +Y (downward, away from apex). The base is at higher Y than apex.
        // Base corners go CW when viewed from apex (looking in +Y direction).
        // For outward normal (+Y direction), we need CCW ordering when viewed from +Y.
        // CCW from +Y is: 3 → 2 → 1 → 0, so triangles: (3, 2, 1) and (3, 1, 0)
        addShape(new SolidPolygon(negXposZ, posXposZ, posXnegZ, color));
        addShape(new SolidPolygon(negXposZ, posXnegZ, negXnegZ, color));

        setBackfaceCulling(true);
    }

    /**
     * Creates a quaternion that rotates from the -Y axis to the given direction.
     *
     * <p>The pyramid by default points in the -Y direction (apex at origin, base at -Y).
     * This method computes the rotation needed to align the pyramid 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);
    }
}