{
    "info": {
        "author": "Reza Ahmadzadeh",
        "author_email": "reza.ahmadzadeh.iit@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: MIT License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3"
        ],
        "description": "# tinyQuaternion\nA tiny python module for Quaternions\n\nAuthor: Reza Ahmadzadeh - 2019\n\n## 1. Installation\n\nClone the repository. For separate projects you need to copy the `tinyQuaternion.py` file into your source folder and import the module as follows:\n\n``` python\nfrom tinyQuaternion import Quaternion\n```\n\nThe only dependency is `numpy`, so import it as follows:\n\n``` python\nimport numpy as np\n```\n\n## 2. Documentation\n\n### 2.1 Define Quaternions\n\nIn this package, there are two methods to define a quaternion:\n\n1. using a 4D array representing the elements of a quaternion `q=[w,x,y,z]`. Define the array using numpy's `ndarray`.\n\n``` python\nq = Quaternion(q=np.array([0., 0., 1., 0.]))\n\n>>> q\nQuaternion(0.0, 0.0, 1.0, 0.0)\n```\n\n\n2. using an axis-angle representation. Use `n` for denoting the axis of rotation and `a` for denoting the angle of rotation in radians.\n\n``` python\nq = Quaternion(a=np.pi/3, n=np.array([0.,0.,1.]))\n\nq\nQuaternion(0.8660254037844387, 0.0, 0.0, 0.49999999999999994)\n```\n\n### 2.2. Quaternion elements \n\nEach quaternion is a vector `q=[w,x,y,z]` with four elements `w`, `x`, `y`, `z`. Each element of the quaternion can be retrieved as follows:\n\n``` python\nq.w\nq.x\nq.y\nq.z\n```\nExample:\n\n``` python\n>>> q.w\n0.8660254037844387\n>>> q.x\n0.0\n>>> q.y\n0.0\n>>> q.z\n0.49999999999999994\n>>> \n```\n\n### 2.3. Scalar and Vector parts\n\nTo retrieve the scalar part of the quaternion, `w` use the `scalar` method as follows:\n\n``` python\nq.scalar\n```\n\nand to retrieve the vector part of the quaternion, `[x,y,z]` use the `vector` method as follows:\n\n``` python\nq.vector\n```\nExample:\n\n``` python\n>>> q.scalar\n0.8660254037844387\n>>> q.vector\narray([0. , 0. , 0.5])\n>>> \n```\n\n### 2.4. Magnitude \n\nGet the norm or magnitude of the quaternion as follows: \n\n``` python\nq.magnitude\n```\n\nExample \n\n``` python\n>>> q.magnitude\n1.0\n```\n\n### 2.5. Check if the quaternion is normalized\n\nTo see if the quaternion is normalized you can use the `is_unit()` method. This will return `True` if the magnitude of the quaternion is equal to 1 and `False` otherwise.\n\n``` python\nq.is_unit()\n```\n\nExample:\n\n``` python\n>>> q.is_unit()\nTrue\n```\n\n### 2.6. Normalize\n\nTo normalize the quaternion use the `normalized` method. \n\n``` python\nq.normalized\n```\n\nExample:\n\n``` python\n>>> q.normalized\nQuaternion(0.8660254037844387, 0.0, 0.0, 0.49999999999999994)\n```\n\n### 2.7. Conjugate\n\nTo retrieve the conjugate of a quaternion `q=[w,x,y,z]` as `q*=[w,-x,-y,-z]` use the `conjugate` method as follows:\n\n``` python\nq.conjugate\n```\n\n\nExample:\n\n``` python\n>>> q.conjugate\nQuaternion(0.8660254037844387, -0.0, -0.0, -0.49999999999999994)\n```\n\n### 2.8. Inverse\n\nTo retrieve the inverse of a quaternion use the `inverse` method as follows:\n\n``` python\nq.inverse\n```\n\n\nExample:\n\n``` python\n>>> q.inverse\nQuaternion(0.8660254037844387, -0.0, -0.0, -0.49999999999999994)\n```\n\n### 2.9. Extract Axis-Angle from Quaternion\n\nTo extract the axis-angle form of a quaternion use this method as follows:\n\n``` python\nq.axisangle()\n```\n\nExample:\n\n``` python\n>>> q.axisangle()\n(array([0., 0., 1.]), 1.0471975511965974)\n```\n\nkeep in mind that this is not equal to the original quaternion that we defined above. The main reason is that we have performed some operations on the original quaternion. \n\n### 2.10. Main operations \n\n``` python\n# addition\nq1.add(q2)\n\n# subtraction\nq1.sub(q2)\n\n# multiplication\nq1.mul(q2)\n\n# division\nq1.div(q2)\n```\n\nExample:\n\n``` python\n>>> q1 = Quaternion(np.array([1.,0.,0.,0.]))\n>>> q2 = Quaternion(np.array([0.,0.,0.,1.]))\n>>> q1.add(q2)\nQuaternion(1.0, 0.0, 0.0, 1.0)\n>>> q1.sub(q2)\nQuaternion(1.0, 0.0, 0.0, -1.0)\n>>> q1.mul(q2)\nQuaternion(0.0, 0.0, 0.0, 1.0)\n>>> q1.div(q2)\nQuaternion(0.0, 0.0, 0.0, -1.0)\n```\n\nNote that these operations do not perfrom normalization implicitly.\n\n### 2.11. Quaternion Log\n\nTo get logarithm of a quaternion perform\n\n``` python \nq.log\n```\nExample:\n\n``` python\n>>> q=Quaternion(np.array([0.,1.,0.,0.]))\n>>> q\nQuaternion(0.0, 1.0, 0.0, 0.0)\n>>> q.log\nQuaternion(0.0, 1.5707963267948966, 0.0, 0.0)\n```\n\n### 2.12. Quaternion Exp\n\nTo get exponential of a quaternion perform\n\n``` python \nq.exp\n```\n\nExample:\n\n``` python\n>>> q=Quaternion(np.array([0.,1.,0.,0.]))\n>>> q\nQuaternion(0.0, 1.0, 0.0, 0.0)\n>>> q.exp\nQuaternion(0.5403023058681398, 0.8414709848078965, 0.0, 0.0)\n```\n\n### 2.13. Rotate point in 3D space using Quaternion (axis-angle)\n\n``` python\nq.rotatePoint(p)\n```\n\nExample:\n\nThe point should be define using a 3D numpy array as follows:\n\n``` python\n>>> q = Quaternion(a=np.pi/3, n=np.array([0.,0.,1.]))\n>>> p = np.array([1.,2.,-1.])\n>>> q.rotatePoint(p)\narray([-1.23205081,  1.8660254 , -1.        ])\n```\n\n## 3. Tutorials\n\n## 3.1. Rotation Using Quaternions\n\nThe code can be found in the `test` folder. First import all the required packages:\n\n``` python\nimport numpy as np\nfrom tinyQuaternion import Quaternion\nfrom plotCube import plot_cube\n```\n\nTo perform this test, we first plot a cube using the function `plotCube.py` provided in the test folder. \n\n``` python\n# plot the initial cube\np1 = np.array([0.,0.,0.])\np2 = np.array([0.,.1,0.])\np3 = np.array([2.,0.,0.])\np4 = np.array([0.,0.,.1])\n\ncube1 = [\n    (p1[0],p1[1],p1[2]), (p2[0],p2[1],p2[2]), (p3[0],p3[1],p3[2]), (p4[0],p4[1],p4[2])\n]\nplot_cube(cube1)\n```\n\nThis will result in the following cube:\n\n![\"initial cube\"](https://github.com/rezaahmadzadeh/tinyquaternion/blob/master/tinyquaternion/test/results/Figure_1.png \"initial cube\")\n\n\nNow, we define a known quaternion. Assume, we want to rotate about Y-axis by 90 degrees. The quaternion will look like this:\n\n``` python\n# define a known quaternion\nq = Quaternion(a=np.pi/2, n=np.array([0., 1., 0.]))\n```\n\nBy using the `a` and `n` keywords, we tell the function that we are representing the quaternion by defining the angle and axis of rotation.\n\n\nNow, we rotate each point using the quaternion through the method `rotatePoint` as follows:\n\n``` python\n# rotate the cube\np1r = q.rotatePoint(p1)\np2r = q.rotatePoint(p2)\np3r = q.rotatePoint(p3)\np4r = q.rotatePoint(p4)\n```\n\nand plot the rotated cube \n\n``` python\ncube2 = [\n    (p1r[0],p1r[1],p1r[2]), (p2r[0],p2r[1],p2r[2]), (p3r[0],p3r[1],p3r[2]), (p4r[0],p4r[1],p4r[2])\n]\nplot_cube(cube2)\n```\n\n![\"rotated cube\"](https://github.com/rezaahmadzadeh/tinyquaternion/blob/master/tinyquaternion/test/results/Figure_2.png \"rotated cube\")\n\nNow let's perform two rotations using quaternions. We consider a new rotation and then combine it with the previous rotation.\nOur previous rotation was about Y-axis by 90 degrees. For this one we want to have a rotation about X-axis by 90 degrees. The quaternion will look like this:\n\n``` python\nq2 = Quaternion(a=np.pi/2, n=np.array([1.,0.,0.])) # rotate about x by 90\n```\n\nNow, we should combine the two quaternions. The rule is that \"First rotation should go last\", so we can write\n\n``` python\nq = q2.mul(q) \n```\nThis quaternion has the effect of a rotation about Y-axis, followed by a rotation about X-axis.\n\nNow perform the rotation:\n\n``` python\np1r = q.rotatePoint(p1)\np2r = q.rotatePoint(p2)\np3r = q.rotatePoint(p3)\np4r = q.rotatePoint(p4)\n```\n\nand plot the rotated cube:\n\n``` python\ncube3 = [\n    (p1r[0],p1r[1],p1r[2]), (p2r[0],p2r[1],p2r[2]), (p3r[0],p3r[1],p3r[2]), (p4r[0],p4r[1],p4r[2])\n]\nplot_cube(cube3)\n```\n\n![\"rotated cube\"](https://github.com/rezaahmadzadeh/tinyquaternion/blob/master/tinyquaternion/test/results/Figure_3.png \"multiple rotations\")\n\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/rezaahmadzadeh/tinyquaternion",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "tinyquaternion",
        "package_url": "https://pypi.org/project/tinyquaternion/",
        "platform": "",
        "project_url": "https://pypi.org/project/tinyquaternion/",
        "project_urls": {
            "Homepage": "https://github.com/rezaahmadzadeh/tinyquaternion"
        },
        "release_url": "https://pypi.org/project/tinyquaternion/0.0.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "A Tiny Python Package for Quaternions",
        "version": "0.0.1"
    },
    "last_serial": 5482568,
    "releases": {
        "0.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4ec3705bc5d2864ec5619f1d67ac25a9",
                    "sha256": "fe4656f8f53d4dc2be14efccdee44e6cb4cb2882da95fb7c45b82c6a7e270ce7"
                },
                "downloads": -1,
                "filename": "tinyquaternion-0.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "4ec3705bc5d2864ec5619f1d67ac25a9",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 6691,
                "upload_time": "2019-07-03T16:23:28",
                "url": "https://files.pythonhosted.org/packages/89/c1/a4b6ee1e51998e2419fcd937be805b492cbdc32ccbd544870dfa500a94b0/tinyquaternion-0.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "cb355efa66abf22d022fe651462cb863",
                    "sha256": "5c2797278cf806c8a0088c53ce2844fd0c131d9e3c2295fcef03b67949a7b602"
                },
                "downloads": -1,
                "filename": "tinyquaternion-0.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "cb355efa66abf22d022fe651462cb863",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6082,
                "upload_time": "2019-07-03T16:23:30",
                "url": "https://files.pythonhosted.org/packages/df/47/6cfd8786802b83454c077a36b0d6f917ae9b57c02dc23eaead4e328fc954/tinyquaternion-0.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "4ec3705bc5d2864ec5619f1d67ac25a9",
                "sha256": "fe4656f8f53d4dc2be14efccdee44e6cb4cb2882da95fb7c45b82c6a7e270ce7"
            },
            "downloads": -1,
            "filename": "tinyquaternion-0.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4ec3705bc5d2864ec5619f1d67ac25a9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 6691,
            "upload_time": "2019-07-03T16:23:28",
            "url": "https://files.pythonhosted.org/packages/89/c1/a4b6ee1e51998e2419fcd937be805b492cbdc32ccbd544870dfa500a94b0/tinyquaternion-0.0.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "cb355efa66abf22d022fe651462cb863",
                "sha256": "5c2797278cf806c8a0088c53ce2844fd0c131d9e3c2295fcef03b67949a7b602"
            },
            "downloads": -1,
            "filename": "tinyquaternion-0.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "cb355efa66abf22d022fe651462cb863",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 6082,
            "upload_time": "2019-07-03T16:23:30",
            "url": "https://files.pythonhosted.org/packages/df/47/6cfd8786802b83454c077a36b0d6f917ae9b57c02dc23eaead4e328fc954/tinyquaternion-0.0.1.tar.gz"
        }
    ]
}