{"id":17250091,"url":"https://github.com/stephengold/heart","last_synced_at":"2025-04-14T05:31:32.740Z","repository":{"id":37523689,"uuid":"237680434","full_name":"stephengold/Heart","owner":"stephengold","description":"A general-purpose add-on library for jMonkeyEngine (code has New BSD license)","archived":false,"fork":false,"pushed_at":"2025-03-05T20:21:23.000Z","size":2155,"stargazers_count":15,"open_issues_count":0,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-27T19:49:59.634Z","etag":null,"topics":["debug","java","jme3","jmonkeyengine","jmonkeyengine3","jvm-library","library","math-library","mesh","open-source","perlin-noise","platonic-solids","quaternions"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stephengold.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-01T21:29:06.000Z","updated_at":"2025-03-05T20:21:26.000Z","dependencies_parsed_at":"2023-10-14T22:24:37.145Z","dependency_job_id":"aa353377-f346-4c64-806f-8d6456f3334a","html_url":"https://github.com/stephengold/Heart","commit_stats":null,"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FHeart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FHeart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FHeart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FHeart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephengold","download_url":"https://codeload.github.com/stephengold/Heart/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248826592,"owners_count":21167718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","java","jme3","jmonkeyengine","jmonkeyengine3","jvm-library","library","math-library","mesh","open-source","perlin-noise","platonic-solids","quaternions"],"created_at":"2024-10-15T06:46:09.816Z","updated_at":"2025-04-14T05:31:32.733Z","avatar_url":"https://github.com/stephengold.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg height=\"150\" src=\"https://i.imgur.com/O7MMp7A.png\" alt=\"Heart Project logo\"\u003e\n\n[The Heart Project][heart] provides\na general-purpose add-on library for\n[the jMonkeyEngine (JME) game engine][jme].\n\nIt contains 3 subprojects:\n\n1. HeartLibrary: the Heart [JVM] runtime library and its automated tests\n2. HeartExamples: demos, examples, and non-automated test software\n3. J3oDump: a command-line utility to dump J3O assets\n\nComplete source code (in [Java]) is provided under\n[a 3-clause BSD license][license].\n\nMany other libraries depend on the Heart Library, including\n[Acorus], [jme3-wireframe], [JmePower], [Minie],\n[MonkeyWrench], [SkyControl], and [Wes].\n\n\n\u003ca name=\"toc\"\u003e\u003c/a\u003e\n\n## Contents of this document\n\n+ [Important features](#features)\n+ [How to add Heart to an existing project](#add)\n+ [How to build Heart from source](#build)\n+ [Downloads](#downloads)\n+ [Conventions](#conventions)\n+ [An overview of the example applications](#examples)\n+ [External links](#links)\n+ [History](#history)\n+ [Acknowledgments](#acks)\n\n\n\u003ca name=\"features\"\u003e\u003c/a\u003e\n\n## Important features\n\n+ debugging aids:\n  + `Dumper` to concisely dump a scene graph or a subtree thereof, or to\n    dump appstates or viewports\n  + `Validate` to validate arguments passed to a library method\n  + `AxesVisualizer` to visualize the coordinate axes of a `Node`\n  + `BoundsVisualizer` to visualize the world bounds of a `Spatial`\n  + `PointVisualizer` to visualize a particular location in the world\n  + `SkeletonVisualizer` to visualize the bones/joints of an animated model\n  + `VectorVisualizer` to visualize a vector\n  + `MyAsset.createDebugMaterial()` to visualize mesh normals\n    with or without gamma correction\n  + `MyMesh.boneWeightMaterial()` to visualize bone weights in a `Mesh`\n+ `Mesh` subclasses:\n  + `Dodecahedron`, `Icosahedron`, `Octahedron`, and `Tetrahedron`\n    to generate meshes for Platonic solids\n  + `CapsuleMesh`, `Cone`, `DomeMesh`, `Icosphere`, `LoopMesh`,\n    `Octasphere`, `PointMesh`, `Prism`, and `RectangleOutlineMesh`\n    to generate familiar 3-D shapes\n  + `RectangleMesh` to generate custom quads\n  + `DiscMesh` and `RoundedRectangle` to generate eye-pleasing backgrounds\n    for user-interface text\n+ `MyMesh` utilities to analyze and manipulate JMonkeyEngine meshes:\n  + compress a `Mesh` by introducing an index buffer\n  + expand a `Mesh` to ensure no vertex data are re-used\n  + generate normals for an outward-facing sphere, a faceted mesh,\n    or a smooth mesh\n  + translate, rotate, or uniformly scale a `Mesh`\n  + merge 2 meshes into one\n  + flip mesh normals and/or triangle windings\n  + subdivide all elements of a mesh\n  + enumerate all vertices in a scene-graph subtree\n  + convert mesh triangles to lines\n+ JME-oriented math:\n  + generate pseudo-random quaternions and vectors\n  + interpolate and cardinalize quaternions and vectors\n  + other useful operations on scalars, quaternions, vectors,\n    arrays, buffers, and sets of vectors\n  + generate 2-D Perlin noise\n+ loaders for `Properties` and `String` assets\n+ `ContrastAdjustmentFilter`\n+ an `AppState` to manage `ViewPort` updating\n+ and much, much more!\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"add\"\u003e\u003c/a\u003e\n\n## How to add Heart to an existing project\n\nHeart comes pre-built as a single library that depends on\nthe standard \"jme3-core\" library from jMonkeyEngine.\nAdding Heart to an existing [jMonkeyEngine][jme] project should be\na simple matter of adding this library to the classpath.\n\nFor projects built using [Maven] or [Gradle], it is sufficient to add\na dependency on the Heart Library.\nThe build tool should automatically resolve the remaining dependencies.\n\n### Gradle-built projects\n\nAdd to the project’s \"build.gradle\" file:\n\n    repositories {\n        mavenCentral()\n    }\n    dependencies {\n        implementation(\"com.github.stephengold:Heart:9.2.0\")\n    }\n\nFor some older versions of Gradle,\nit's necessary to replace `implementation` with `compile`.\n\n### Maven-built projects\n\nAdd to the project’s \"pom.xml\" file:\n\n    \u003crepositories\u003e\n      \u003crepository\u003e\n        \u003cid\u003emvnrepository\u003c/id\u003e\n        \u003curl\u003ehttps://repo1.maven.org/maven2/\u003c/url\u003e\n      \u003c/repository\u003e\n    \u003c/repositories\u003e\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.stephengold\u003c/groupId\u003e\n      \u003cartifactId\u003eHeart\u003c/artifactId\u003e\n      \u003cversion\u003e9.2.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\n### Ant-built projects\n\nFor projects built using [Ant], download the library from GitHub:\n\n+ https://github.com/stephengold/Heart/releases/latest\n\nYou'll definitely want the class jar\nand probably the \"-sources\" and \"-javadoc\" jars as well.\n\nOpen the project's properties in the IDE (JME SDK or NetBeans):\n\n1. Right-click on the project (not its assets) in the \"Projects\" window.\n2. Select \"Properties\" to open the \"Project Properties\" dialog.\n3. Under \"Categories:\" select \"Libraries\".\n4. Click on the \"Compile\" tab.\n5. Add the Heart class jar:\n  + Click on the \"Add JAR/Folder\" button.\n  + Navigate to the download folder.\n  + Select the \"Heart-9.2.0.jar\" file.\n  + Click on the \"Open\" button.\n6. (optional) Add jars for javadoc and sources:\n  + Click on the \"Edit\" button.\n  + Click on the \"Browse...\" button to the right of \"Javadoc:\"\n  + Select the \"Heart-9.2.0-javadoc.jar\" file.\n  + Click on the \"Open\" button.\n  + Click on the \"Browse...\" button to the right of \"Sources:\"\n  + Select the \"Heart-9.2.0-sources.jar\" file.\n  + Click on the \"Open\" button again.\n  + Click on the \"OK\" button to close the \"Edit Jar Reference\" dialog.\n7. Click on the \"OK\" button to exit the \"Project Properties\" dialog.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"build\"\u003e\u003c/a\u003e\n\n## How to build Heart from source\n\n1. Install a [Java Development Kit (JDK)][adoptium],\n   if you don't already have one.\n2. Point the `JAVA_HOME` environment variable to your JDK installation:\n   (In other words, set it to the path of a directory/folder\n   containing a \"bin\" that contains a Java executable.\n   That path might look something like\n   \"C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.3.7-hotspot\"\n   or \"/usr/lib/jvm/java-17-openjdk-amd64/\" or\n   \"/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home\" .)\n  + using Bash or Zsh: `export JAVA_HOME=\"` *path to installation* `\"`\n  + using [Fish]: `set -g JAVA_HOME \"` *path to installation* `\"`\n  + using Windows Command Prompt: `set JAVA_HOME=\"` *path to installation* `\"`\n  + using PowerShell: `$env:JAVA_HOME = '` *path to installation* `'`\n3. Download and extract the Heart source code from GitHub:\n  + using [Git]:\n    + `git clone https://github.com/stephengold/Heart.git`\n    + `cd Heart`\n    + `git checkout -b latest 9.2.0`\n  + using a web browser:\n    + browse to [the latest release][latest]\n    + follow the \"Source code (zip)\" link\n    + save the ZIP file\n    + extract the contents of the saved ZIP file\n    + `cd` to the extracted directory/folder\n4. Run the [Gradle] wrapper:\n  + using Bash or Fish or PowerShell or Zsh: `./gradlew build`\n  + using Windows Command Prompt: `.\\gradlew build`\n\nAfter a successful build,\nMaven artifacts will be found in \"HeartLibrary/build/libs\".\n\nYou can install the artifacts to your local Maven repository:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew install`\n+ using Windows Command Prompt: `.\\gradlew install`\n\nYou can restore the project to a pristine state:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew clean`\n+ using Windows Command Prompt: `.\\gradlew clean`\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"downloads\"\u003e\u003c/a\u003e\n\n## Downloads\n\nNewer releases (since v4.5.0) can be downloaded from\n[GitHub](https://github.com/stephengold/Heart/releases).\n\nOlder releases (v0.9.5 through v4.4.0) can be downloaded from\n[the Jme3-utilities Project](https://github.com/stephengold/jme3-utilities/releases).\n\nNewer Maven artifacts (since v6.3.0) are available from\n[MavenCentral](https://repo1.maven.org/maven2/com/github/stephengold/Heart/).\n\nOld Maven artifacts (v5.0.0 through v6.4.0) are available from JCenter.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"conventions\"\u003e\u003c/a\u003e\n\n## Conventions\n\nPackage names begin with `jme3utilities`.\n\nThe source code and pre-built libraries are compatible with JDK 8.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"examples\"\u003e\u003c/a\u003e\n\n## An overview of the example applications\n\nApplications have been created to test and demonstrate\ncertain features of Heart.\n\nThese can be run from the menu-driven AppChooser app:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew AppChooser`\n+ using Windows Command Prompt: `.\\gradlew AppChooser`\n\nYou can also run specific apps from a command prompt:\n+ using Bash or Fish or PowerShell or Zsh: `./gradlew :HeartExamples:LoopMeshTest`\n+ using Windows Command Prompt: `.\\gradlew :HeartExamples:LoopMeshTest`\n\n### LoopMeshTest\n\nThis app demonstrates constructing a regular polygon\nusing the `LoopMesh` class.\n\n### TestBoundsVisualizer\n\nThis app demonstrates visualizing the bounding volume of a geometry\nusing a `BoundsVisualizer`.\n\nPressing the \"B\" key\ntoggles the bounding volume between a sphere and an axis-aligned box.\n\n### TestContrast\n\nThis app demonstrates changing the contrast of a rendered scene\nusing a `ContrastAdjustmentFilter`.\n\n+ Pressing the NUMPAD4 key reduces the exponent of the filter.\n+ Pressing the NUMPAD6 key increases the exponent.\n\n### TestGenerator\n\nThis app demonstrates generating pseudo-random vectors and rotations\nusing a `Generator`.\n\n### TestMergeMeshes\n\nThis app demonstrates translating, indexing, and merging meshes\nusing the `MyMesh` utility class.\n\n### TestMulticolor\n\nThis app demonstrates visualizing a mesh with vertex colors\nusing the \"multicolor.j3md\" material definitions.\n\n### TestPas\n\nThis app demonstrates monitoring the maximum time per frame\nusing a `PerformanceAppState`.\n\n### TestRotate\n\nThis app demonstrates rotation of mesh vertices\nusing the `MyMesh.rotate()` utility method.\n\nPressing the Enter key rotates both meshes\nto a new, pseudo-randomly chosen orientation.\n\n### TestSkeletonVisualizer\n\nThis app demonstrates visualizing the skeleton of an animated model\nusing `SkeletonVisualizer`.\n\nPressing the \".\" key toggles the animation between paused and running.\n\n### TestSolidMeshes\n\nThis app demonstrates procedurally generating meshes\nusing the `Cone`, `Dodecahedron`, `DomeMesh`, `Icosahedron`, `Icosphere`,\n`Octahedron`, `Octasphere`, `Prism`, and `Tetrahedron` classes.\n\nPressing the \"N\" key cycles through 6 different test materials.\n\n### TestSubdivide\n\nThis app demonstration subdividing a mesh\nusing the `MyMesh.subdivideTriangles()` utility method.\n\n+ Pressing the Tab key toggles between textured and wireframe materials.\n+ Pressing the NUMPAD4 key reduces the number of subdivisions.\n+ Pressing the NUMPAD6 key increases the number of subdivisions.\n\n### TestWireframe\n\nThis app demonstrates visualizing a mesh as a wireframe\nusing the `MyAsset.createWireframeMaterial()` utility method.\n\n### TrianglesToLines\n\nThis app demonstrates converting a triangle mesh to a line mesh\nusing the `MyMesh.trianglesToLines()` utility method.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"links\"\u003e\u003c/a\u003e\n\n## External links\n\n+ [the Heart page](https://library.jmonkeyengine.org/#!entry=11511%2Fe534fc1e-5b78-46b7-a831-d5d40cbd9dcd)\n  in [the JmonkeyEngine Library][library]\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"history\"\u003e\u003c/a\u003e\n\n## History\n\nThe evolution of this project is chronicled in\n[its release log][log].\n\nThe oldest parts of the Heart Library were originally included in [SkyControl].\n\nFrom May 2017 to February 2020, Heart was a subproject of\n[the Jme3-utilities Project][utilities].\n\nSince February 2020, Heart has been a separate project, hosted at\n[GitHub][heart].\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"acks\"\u003e\u003c/a\u003e\n\n## Acknowledgments\n\nLike most projects, the Heart Project builds on the work of many who\nhave gone before.  I therefore acknowledge the following\nsoftware developers:\n\n + \"jayfella\", for creating and sharing the original `Icosphere.java`\n + Paul Speed, for helpful insights\n + \"rvandoosselaer\", for reporting and fixing issue #2.\n + plus the creators of (and contributors to) the following software:\n    + the [Blender] 3-D animation suite\n    + the [Checkstyle] tool\n    + the [FindBugs] source-code analyzer\n    + the [Firefox] and [Google Chrome][chrome] web browsers\n    + the [Git] revision-control system and GitK commit viewer\n    + the [GitKraken] client\n    + the [Gradle] build tool\n    + the [IntelliJ IDEA][idea] and [NetBeans] integrated development environments\n    + the [Java] compiler, standard doclet, and runtime environment\n    + [jMonkeyEngine][jme] and the jME3 Software Development Kit\n    + the [Linux Mint][mint] operating system\n    + [LWJGL], the Lightweight Java Game Library\n    + the [Markdown] document-conversion tool\n    + the [Meld] visual merge tool\n    + Microsoft Windows\n    + the PMD source-code analyzer\n    + the [WinMerge] differencing and merging tool\n\nI am grateful to [GitHub], [Sonatype], [JFrog], and [Imgur]\nfor providing free hosting for this project\nand many other open-source projects.\n\nI'm also grateful to my dear Holly, for keeping me sane.\n\nIf I've misattributed anything or left anyone out, please let me know, so I can\ncorrect the situation: sgold@sonic.net\n\n[Jump to the table of contents](#toc)\n\n\n[acorus]: https://stephengold.github.io/Acorus \"Acorus Project\"\n[adoptium]: https://adoptium.net/temurin/releases/ \"Adoptium Project\"\n[ant]: https://ant.apache.org \"Apache Ant Project\"\n[blender]: https://docs.blender.org \"Blender Project\"\n[checkstyle]: https://checkstyle.org \"Checkstyle\"\n[chrome]: https://www.google.com/chrome \"Chrome\"\n[findbugs]: http://findbugs.sourceforge.net \"FindBugs Project\"\n[firefox]: https://www.mozilla.org/en-US/firefox \"Firefox\"\n[fish]: https://fishshell.com/ \"Fish command-line shell\"\n[git]: https://git-scm.com \"Git\"\n[github]: https://github.com \"GitHub\"\n[gitkraken]: https://www.gitkraken.com \"GitKraken client\"\n[gradle]: https://gradle.org \"Gradle Project\"\n[heart]: https://github.com/stephengold/Heart \"Heart Project\"\n[idea]: https://www.jetbrains.com/idea/ \"IntelliJ IDEA\"\n[imgur]: https://imgur.com/ \"Imgur\"\n[java]: https://en.wikipedia.org/wiki/Java_(programming_language) \"Java programming language\"\n[jfrog]: https://www.jfrog.com \"JFrog\"\n[jme]: https://jmonkeyengine.org \"jMonkeyEngine Project\"\n[jme3-wireframe]: https://github.com/joliver82/jme3-wireframe \"jME3 Wireframe render library\"\n[jmepower]: https://github.com/stephengold/JmePower \"JmePower Project\"\n[jvm]: https://en.wikipedia.org/wiki/Java_virtual_machine \"Java virtual machine\"\n[latest]: https://github.com/stephengold/Heart/releases/latest \"latest release\"\n[library]: https://library.jmonkeyengine.org \"jMonkeyEngine Library\"\n[license]: https://github.com/stephengold/Heart/blob/master/license.txt \"Heart license\"\n[log]: https://github.com/stephengold/Heart/blob/master/HeartLibrary/release-notes.md \"release log\"\n[lwjgl]: https://www.lwjgl.org \"Lightweight Java Game Library\"\n[markdown]: https://daringfireball.net/projects/markdown \"Markdown Project\"\n[maven]: https://maven.apache.org \"Maven Project\"\n[meld]: https://meldmerge.org \"Meld merge tool\"\n[minie]: https://stephengold.github.io/Minie/minie/overview.html \"Minie Project\"\n[mint]: https://linuxmint.com \"Linux Mint Project\"\n[monkeywrench]: https://github.com/stephengold/MonkeyWrench \"MonkeyWrench Project\"\n[netbeans]: https://netbeans.org \"NetBeans Project\"\n[skycontrol]: https://github.com/stephengold/SkyControl \"SkyControl Project\"\n[sonatype]: https://www.sonatype.com \"Sonatype\"\n[utilities]: https://github.com/stephengold/jme3-utilities \"Jme3-utilities Project\"\n[wes]: https://github.com/stephengold/Wes \"Wes Project\"\n[winmerge]: https://winmerge.org \"WinMerge Project\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fheart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephengold%2Fheart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fheart/lists"}