{"id":17250107,"url":"https://github.com/stephengold/maud","last_synced_at":"2025-04-14T03:11:30.603Z","repository":{"id":37951067,"uuid":"87848729","full_name":"stephengold/Maud","owner":"stephengold","description":"An editor for jMonkeyEngine 3-D models (code has New BSD license)","archived":false,"fork":false,"pushed_at":"2025-04-07T19:58:48.000Z","size":30458,"stargazers_count":40,"open_issues_count":2,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-07T20:30:07.790Z","etag":null,"topics":["3d-models","animation","application","editor","java","jme3","jmonkeyengine","jmonkeyengine3","minie","open-source","retargeting-animations","skeleton-map"],"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","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":"2017-04-10T19:17:55.000Z","updated_at":"2025-04-07T19:58:51.000Z","dependencies_parsed_at":"2023-02-15T12:31:26.138Z","dependency_job_id":"21631348-6ff3-46d0-be55-eefe63866f60","html_url":"https://github.com/stephengold/Maud","commit_stats":{"total_commits":2725,"total_committers":3,"mean_commits":908.3333333333334,"dds":"0.013577981651376136","last_synced_commit":"bb4fd0875ef8b7b506e74847d4030a49f58f1df4"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FMaud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FMaud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FMaud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stephengold%2FMaud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stephengold","download_url":"https://codeload.github.com/stephengold/Maud/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813796,"owners_count":21165634,"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":["3d-models","animation","application","editor","java","jme3","jmonkeyengine","jmonkeyengine3","minie","open-source","retargeting-animations","skeleton-map"],"created_at":"2024-10-15T06:46:13.485Z","updated_at":"2025-04-14T03:11:30.577Z","avatar_url":"https://github.com/stephengold.png","language":"Java","readme":"\u003cimg height=\"150\" src=\"https://i.imgur.com/beTKjwO.png\" alt=\"Maud logo\"\u003e\n\nMaud is an editor for the animated 3-D models used with\n[the jMonkeyEngine (JME) game engine][jme].\n\nAnticipated uses:\n\n + customize models created by others\n + develop animations from motion-capture data\n + copy/retarget animations between models\n + convert models in other formats to native J3O format\n + troubleshoot issues with models (or with the model-asset pipeline)\n\nSummary of features:\n\n + load models from local filesystems, JAR/ZIP archives, or HTTP servers\n + import models from [Blender]/[glTF]/[IQE]/[Ogre]/[Wavefront][obj]/[Xbuf] and save to native J3O format\n + import animations from [Biovision Hierarchy (BVH)](#bvh) files\n + visualize animations, axes, bones, bounding boxes, lights,\n   mesh vertices, physics objects, and skeletons\n + merge models or geometries\n + split geometries\n + apply transforms to meshes or child spatials\n + browse animations, bones, keyframes, lights, material parameters,\n   material-parameter overrides, mesh vertices, physics objects,\n   physics shapes, scene-graph controls, spatials, tracks, and user data\n + play animations forward/backward at various speeds and pause them\n + create new animations from poses or by altering/mixing existing animations\n + retarget bone animations from one model to another using skeleton maps\n + create new attachments nodes, lights, physics controls, scene-graph controls,\n   scene-graph nodes, and user data\n + insert keyframes into animations and bone tracks\n + rename animations, bones, lights, spatials, and user data\n + change animation speeds/durations\n + behead/mix/truncate animations\n + reduce/resample/wrap animations and tracks\n + translate animations for support or traction\n + delete animations, keyframes, lights, material parameters,\n   material-parameter overrides, scene-graph controls, spatials, tracks,\n   and user data\n + modify bone/spatial transforms (translation, rotation, and scale)\n + modify batch hints, cull hints, lights, material parameters,\n   material-parameter overrides, render-queue buckets, shadow modes, and user data\n + review the edit history and undo/redo edits\n + customizable mouse-button assignments and keyboard shortcuts\n\nJava source code is provided under\n[a 3-clause BSD license][license].\n\nMaud was designed for a desktop environment with:\n\n + a wheel mouse and\n + a display at least 640 pixels wide and 720 pixels tall.\n\n\n\u003ca name=\"toc\"\u003e\u003c/a\u003e\n\n## Contents of this document\n\n+ [How to download and run a pre-built release of Maud](#prebuilt)\n+ [How to build and run Maud from source](#build)\n+ [Using Maud](#use)\n+ [3-D Models](#cgms)\n+ [Bones](#bones)\n+ [Animations](#animations)\n+ [The displayed pose](#pose)\n+ [The skeleton map](#map)\n+ [The edit history](#edithistory)\n+ [Scripting](#scripting)\n+ [Command-line arguments](#args)\n+ [External links](#links)\n+ [Wish list](#wishlist)\n+ [Conventions](#conventions)\n+ [History](#history)\n+ [Acknowledgments](#acks)\n\n\n\u003ca name=\"prebuilt\"\u003e\u003c/a\u003e\n\n## How to download and run a pre-built release of Maud\n\n1. Install a 64-bit [Java], if you don't already have one.\n   (Maud no longer supports 32-bit Java.)\n2. Point the `JAVA_HOME` environment variable to your Java installation.\n   (In other words, set it to the path of a directory/folder\n   containing a \"bin\" that contains a Java executable.\n   The path might be something like \"C:\\Program Files\\Java\\jre1.8.0_301\"\n   or \"/usr/lib/jvm/java-11-openjdk-amd64/\" .)\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. Install the latest Maud release from GitHub:\n  + Browse to [the latest release](https://github.com/stephengold/Maud/releases/latest)\n  + Follow the \"Maud.zip\" link.\n  + Save the ZIP file.\n  + Extract the contents of the saved ZIP file.\n4. `cd` to the extracted \"Maud\" directory/folder that contains \"bin\" and \"lib\".\n5. Run the Maud startup script:\n  + using Bash or Fish or Zsh: `./bin/Maud`\n  + using Windows Command Prompt: `./bin/Maud.bat`\n  + using PowerShell: `.\\bin\\Maud.bat`\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"build\"\u003e\u003c/a\u003e\n\n## How to build and run Maud from source\n\n1. Install a 64-bit [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 Maud source code from GitHub:\n  + using Git:\n    + `git clone https://github.com/stephengold/Maud.git`\n    + `cd Maud`\n    + `git checkout -b latest 1.0.0-beta2`\n  + using a web browser:\n    + browse to [the latest release](https://github.com/stephengold/Maud/releases/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,\narchives for distribution will be found in `build/distributions`.\n\nYou can run the local build using the Gradle wrapper:\n+ using Bash or Fish or Zsh or PowerShell: `./gradlew run`\n+ using Windows Command Prompt: `.\\gradlew run`\n\nYou can restore the project to a pristine state:\n+ using Bash or Fish or Zsh or PowerShell: `./gradlew clean cleanSandbox`\n+ using Windows Command Prompt: `.\\gradlew clean cleanSandbox`\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"use\"\u003e\u003c/a\u003e\n\n## Using Maud\n\n### Overview of the user interface\n\nMaud's user interface consists of 4 screens:\n\"Start\", \"Editor\", \"Display Settings\", and \"Bind\".\nThe Start Screen loads first. It merely displays the Maud logo while\ninitialization completes.  It should automatically transition to the Editor\nScreen after a few seconds.\n\nThe Editor Screen is Maud's main screen, where 3-D models are visualized, browsed,\nand edited.  There's a menu bar across the top and a message bar across the bottom.\nMost of its user interface\nis split into overlapping sub-windows called \"tools\".\n\n![screenshot](https://i.imgur.com/1GRhpOB.png \"Editor Screen with 3 tools visible and a menu active\")\n\n#### Tools\n\nAt last count, Maud had 52 tools.\nEach tool can be independently hidden or made visible.\n\nSelecting a tool makes it visible and moves it to the top layer for convenient\nuse, but you can use a tool without it being on top.\nThe controls in a tool work even when partly obscured by other tools.\nYou can move a tool by dragging its title bar with the left mouse button (LMB).\n\nIf a tool gets in your way, you can hide it by clicking on\nthe X in its upper right corner with the LMB.\nHiding a tool won't affect anything else, so it's always a safe move.\n\n#### Menus\n\nClicking a button in the menu bar with the LMB activates the corresponding menu.\nMenus are modal: activating a menu disables all other user interfaces in Maud.\nWhen a menu is active, the remainder of the screen darkens,\nand the mouse cursor becomes a right-pointing magenta arrow.\nYou can then select a menu item by clicking on it with the LMB or RMB.\n\nMany menu items display icons to help indicate what they do:\n\n + a right-pointing black arrow to activate a submenu\n + a wrench icon to select a tool\n + a dialog-box icon to open a dialog box or go to a different screen\n + a pencil icon to immediately edit the loaded skeleton map or target model\n + a bone icon to select a bone\n + an ogre's head to immediately load an [Ogre] model\n + and so forth.\n\nMenus are context-sensitive, so for instance you'll see many more options\nin the Animation menu when a real animation is loaded than when the model is\nin its bind pose.\n\nThe first 10 items in each menu are numbered.\nFor instance, the first item in the menu bar is\nlabeled \"1] View\".  The numbers indicate keyboard shortcuts for\nnavigating menus.  When no popups are open,\nyou can select the View Menu by pressing\nthe \"1\" key on the main keyboard (but NOT the \"1\" key on the numeric keypad).\n\n#### Keyboard shortcuts\n\nKeyboard shortcuts in the Editor Screen include:\n\n + \".\" or \"Pause\" to pause/restart the loaded animation(s)\n + \"Esc\" to exit from the active menu (or if there's no active menu, to exit from Maud)\n + \"H\" to toggle the visibility of the menu bar and the status bar\n + \"X\" to create a checkpoint\n + \"Z\" to undo to the previous checkpoint\n + \"Y\" to redo to the next checkpoint\n + \"F1\" to switch to the Bind Screen\n\nMouse-button assignments and keyboard shortcuts can be customized using the\nBind Screen (or by editing the \"Interface/bindings/editor.properties\" asset\nprior to startup)\nin which case shortcuts described in this document might not work.\n\n### Views and models in the Editor Screen\n\nAt startup, the Editor Screen displays a \"scene\" view of a single 3-D model:\nJaime, from the jme3-testdata library, with no tools selected.\n\n![screenshot](https://i.imgur.com/vaKixFI.png \"Editor Screen at startup\")\n\nStartup actions can be customized using the \"Settings -\u003e Update startup script\"\nmenu item (or by editing the \"Scripts/startup.js\" asset prior to startup)\nin which case Maud's initial state might differ from that described here.\n\nA scene view consists of a 3-D render of a loaded model, possibly with a\nbackground, a 3-D cursor, a supporting platform, and/or overlaid visualizations.\nVisualizations can include axes, a bounding box, a mesh vertex, physics objects, and/or a\nskeleton.  If you load and play an animation in a scene view, you'll see the\nmodel move, rather like it would in a game.\n\nWhen the mouse cursor is in a scene view, you can use the \"A\" and \"D\" keys\nto rotate the model left and right.  (These keys don't alter the model itself,\nonly its orientation in the view.)  You can also press:\n\n + \"B\" to select the bone closest to the mouse pointer\n + \"E\" to deselect the selected bone\n + \"Q\" to open the \"View -\u003e Scene options\" menu\n + \"V\" to select the mesh vertex closest to the mouse pointer\n + \"W\" to deselect the selected mesh vertex\n\nThe Editor Screen can also display \"score\" views of loaded animations.\nA score view is a schematic diagram, like a musical score, with bones arranged\nvertically and time (indicated by a gnomon) progressing from left to right.\nWhen the mouse cursor is in a score view, the following keyboard\nshortcuts may prove helpful:\n\n + \"B\" to select the bone track closest to the mouse pointer\n + \"G\" to grab the gnomon and (while key is held down) drag it with the mouse pointer\n + \"K\" to select the keyframe closest to the mouse pointer\n + \"Q\" to open the \"View -\u003e Score options\" menu\n\nWhile Maud can only *edit* one model at a time, the Editor Screen can be split\nto *display* 2 different models.\n(This is useful when merging models or\nretargeting animations from one model to another.)\nThe model being edited is called the \"target\" model.\nThe other model is called the \"source\" model.\n\nThe Editor Screen can also be split to display 2 views of the same model.\n\nWhen the editor screen is split, you can adjust the horizontal position of the\nboundary by dragging it with the RMB.\n\n### Views modes of the Editor Screen\n\nThe Editor Screen operates in 3 \"view modes\":\n\"Scene Mode\", \"Score Mode\", and \"Hybrid Mode\".\nYou can change the view mode using the \"View -\u003e Select mode\" submenu or\nuse the backtick (\"`\") keyboard shortcut to cycle through these modes.\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003cth\u003e\u003c/th\u003e\n        \u003cth\u003eWith no source model loaded:\u003c/th\u003e\n        \u003cth\u003eWith a source model loaded:\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eIn Scene Mode...\u003c/td\u003e\n        \u003ctd style=\"border: 1px solid black;\"\u003eA full-width scene view of the target model\u003c/td\u003e\n        \u003ctd style=\"border: 1px solid black;\"\u003eA split display with a scene view of the source model on the left\n            and a scene view of the target model on the right\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eIn Score Mode...\u003c/td\u003e\n        \u003ctd style=\"border: 1px solid black;\"\u003eA full-width score view of the target model\u003c/td\u003e\n        \u003ctd style=\"border: 1px solid black;\"\u003eA split display with a score view of the source model on the left\n            and a score view of the target model on the right\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eIn Hybrid Mode...\u003c/td\u003e\n        \u003ctd colspan=\"2\" style=\"border: 1px solid black;\"\u003eA split display with a score view of the target model on the left\n            and a scene view of the target model on the right\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n### Maud's cameras\n\nEach view has its own camera.\nGenerally, the mouse wheel and middle mouse button (MMB) control Maud's cameras.\nRotate the mouse wheel to move a camera forward or backward.\nIn scene views, drag with MMB to turn the camera.\nIn score views, drag up/down with MMB to scroll the view down/up.\n\n#### Scene-view cameras\n\nBeyond that, it gets complicated, since scene-view cameras operate in\n2 \"movement modes\" and 2 \"projection modes\".\nThe \"Camera Tool\" (selected using \"View -\u003e Scene options -\u003e Camera\")\nis used to select these modes.\n\n\"Orbit Mode\" is a scene-view camera's default movement mode.\nIn orbit mode, the camera orbits a central point.\nIn orbit mode, turning the camera also changes its location, making it easy to\nview models from many directions.\nBy the default, the central point is the \"3-D cursor\" -- a user-selected\nlocation, typically visible as a small, black/yellow, 6-pointed star\nat the center of the view.\n\nMove the 3-D cursor to a new location by clicking LMB on an object in the view:\neither the model or the platform.\nThe 3-D cursor doesn't attach to other objects, so moving or altering objects\nin the scene won't affect the location of the 3-D cursor.\nThe \"Cursor Tool\" (selected using \"View -\u003e Scene options -\u003e Cursor\")\ncan alter the appearance of the 3-D cursor.\nThe \"Camera Tool\" (selected using \"View -\u003e Scene options -\u003e Camera\")\ncan be used to redefine what the camera orbits.\n\n\"Fly Mode\" is a scene-view camera's alternative movement mode.\nIn fly mode, the camera disregards the central point.\nThis is useful for close-up viewing of places the 3-D cursor can't easily reach,\nsuch as the interior of a model.\n\n\"Perspective Mode\" is a scene-view camera's default projection mode,\nand \"Parallel Mode\" is the alternative.\nIn Parallel Mode, the mouse wheel\nalters the scale of the projection without actually moving the camera.\n\nStandard keyboard shortcuts affecting the scene-view cameras:\n\n + \"Numpad-0\" to toggle between movement modes\n + \"Numpad-1\" to move (or rotate) a camera to a horizontal view\n + \"Numpad-5\" to toggle between projection modes\n\n#### Score-view cameras\n\nScore views don't have anything analogous to the 3-D cursor, but you can\nmove the score-view camera up/down by clicking LMB where you want it to look.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"cgms\"\u003e\u003c/a\u003e\n\n## 3-D models\n\nAs mentioned above, Maud always has a (target) model loaded,\nand an additional model (the source model) can also be loaded.\nThe source model can't be modified; only the target can be modified.\n\nThe \"Model Tool\" (selected using \"Models -\u003e Tool\") displays basic\ninformation about the target model.\n\n### Loading (or importing) models from assets\n\nModels are loaded from assets, which may be located in the\nJava classpath (built into Maud) or in a local filesystem or on a web server.\n\nBefore loading a model from a local filesystem, you must specify\na where in the filesystem the model's assets are located:\nselect \"Settings -\u003e Add asset location\",\nthen navigate to the asset folder (typically it contains a \"Model\" subfolder),\nand select \"! add this folder\".\nOr if the assets are in a JAR/ZIP file, simply select that file.\n\nTo load a model as the target model, select the \"Models -\u003e Load\" menu item,\nthen select an asset location, then navigate to the model file.\nTo load a model as the source model, select \"Models -\u003e Source model -\u003e Load\",\nthen select an asset location, then navigate to the model file.\n\nMaud can of course load models in jME's native binary format.\nTo be recognized, such models must have filenames ending in \".j3o\".\n\nMaud can also import models in other formats:\n\n + [Blender 3D][blender] (filename must end in \".blend\")\n + [glTF] (filename must end in \".glb\" or \".gltf\")\n + [Inter-Quake Export][iqe] (filename must end in \".iqe\")\n + [Ogre] DotScene (filename must end in \".scene\")\n + [Ogre] XML (filename must end in \".mesh.xml\")\n + [Wavefront OBJ][obj] (filename must end in \".obj\")\n + [Xbuf] (filename must end in \".xbuf\")\n\nIn addition, Biovision Hierarchy animations can be imported as models.\nTo be recognized, such animations must have filenames ending in \".bvh\".\nThe imported model will consist of a single scene-graph node without any geometries.\n\n### Saving the target model\n\nTo write the target model to a file in jME's native binary format,\nopen the save dialog: \"Models -\u003e Save\".\nModify the base file path as desired, and click on the \"Save\" button.\nThe suffix \".j3o\" is automatically appended to the base file path.\nNote that materials and textures are not saved.\n\nBy default, models loaded from the classpath or from an archive will be written to a\n\"Written Assets\" folder under Maud's working folder.\nWhen loading assets, Maud treats this folder as if it overrides the classpath.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"bones\"\u003e\u003c/a\u003e\n\n## Bones\n\nIn jME, \"bones\" are named parts of a 3-D model that can influence\nvertices in the model's meshes.\nA single vertex can be influenced by up to 4 bones.\nA bone can also influence other bones, called its \"children\".\nA bone with no children is a \"leaf\" bone.\nA bone with no parent is a \"root\" bone.\n\nEach bone has a \"head\" around which it pivots.\nHowever, a jME bone need not have a well-defined \"tail\", a length,\nnor even a direction.\n\nIn a scene view, Maud visualizes each bone as a round dot\n(red or green by default)\nconnected to its children by lines (white by default).\n(You can customize these colors using the \"Skeleton Tool\":\n\"View -\u003e Scene options -\u003e Skeleton\".)\n\nIn a score view, each bone is represented by horizontal \"staff\".\nIf space permits, the staff includes a rectangular name label on the left.\nIf the bone is tracked (more about that later) the staff also includes\nup to 10 stacked \"sparklines\" bracketed by a pair of \"finials\".\nThe sparklines, rendered in 4 colors, represent animation data,\nand the finials help identify which sparkline is which.\n\n![screenshot](https://i.imgur.com/nnXqZAI.png \"a detailed staff in a score view\")\n\nBefore editing a bone in Maud, you must \"select\" it.\nIn a scene view, the selected bone (if any) is typically indicated by\n3 arrows, denoting the axes of its local coordinate axes.\n\nThe \"Bone Tool\" (selected using \"Bone -\u003e Tool\") controls and describes\nthe target model's selected bone.\n\n### Selecting bones\n\nMaud provides many ways to select a bone.\n\nThe \"Bone -\u003e Select\" submenu enables you to select a bone in the\ntarget model by name:\n\n + from among all bones in the selected skeleton, or\n + from among the root bones in the selected skeleton, or\n + from among all bones with attachments nodes, or\n + from among all bones with tracks in the loaded animation, or\n + from among the children of the selected bone.\n\nIt also enables you to navigate the bone hierarchy \"By parent\"\nor cycle through bones in numeric order (\"Previous\" and \"Next\").\n\nThe Bone Tool (\"Bone -\u003e Tool\") provides a more convenient interface to these same\nselection options.\n\nThe quickest way to select a bone is to click the right mouse\nbutton (RMB) on or near it in a scene view.\nThis works for both the source model and the target model.\nHowever, since bones can appear close together in scene views,\nand since the RMB is also used to select objects other than bones,\nuse this technique with caution.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"animations\"\u003e\u003c/a\u003e\n\n## Animations\n\nIn jME, \"animations\" are usually found as part of a 3-D model.\nEach animation has a name and a duration.\n\nMaud treats the model's bind pose like a zero-duration\nanimation for many purposes.\n\nA real animation is stored in an `AnimControl` and composed of \"tracks\", usually bone tracks.\nEach bone track transforms a single bone.\nAn animation need not include a track for every bone.\nMaud refers to bones that have tracks in the loaded animation\nas \"tracked bones\".\n\nEach track is composed of series of \"keyframes\", starting at time zero.\n\nThe (Target) Animation Tool (selected using \"Animations -\u003e Tool\")\ncontrols the target model's loaded animation.\nThere's also a Source Animation Tool (\"Animations -\u003e Source tool\")\nto control the source model's loaded animation.\n\n### Loading animations\n\nIn Maud, \"loading\" an animation means selecting it\nfor visualization, playback, and/or editing.\n\nTo load an animation for the target model,\nselect \"Animations -\u003e Load\" and then the name of the animation.\nTo load an animation for the source model,\nselect \"Animations -\u003e Load source\" and then the name of the animation.\n\n### Playing, pausing, and pinning animations\n\nOnce an animation is loaded, Maud can play it forward or backward at speeds\nof up to 2x.\nEach animation tool has a slider to control the speed and direction\nof playback.\n\nEach animation tool also has a button to pause/resume the loaded animation.\nAs mentioned above, you can also use the \".\" keyboard shortcut\nto pause/resume loaded animations.\n\nBy default, Maud \"loops\" to the start (or end) of the loaded animation\nwhen playback reaches the animation's end (or start).\nUsing the animation tools, you can instruct Maud to pause and/or reverse\ndirection (\"pong\") instead.\n\nUsing the animation tools, you can also \"pin\" a loaded animation.\nPinning an animation forces all its root bones to the model origin\nfor display (scene-view) purposes.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"pose\"\u003e\u003c/a\u003e\n\n## The displayed pose\n\nWhile an animation is playing on the target model, Maud typically refreshes\nthe model's bone transforms on every frame.\nOnce the animation is paused, however, the target model's bone transforms\n(called the \"displayed pose\") can be modified independently\nof the loaded animation.\n\nUse the \"Bone-Translation Tool\" (\"Bone -\u003e Translate\") to modify the local\ntranslation of the selected bone in the displayed pose.\nUse the \"Bone-Scale Tool\" (\"Bone -\u003e Scale\") to scale\nthe selected bone in the displayed pose.\nAnd use the \"Bone-Rotation Tool\" (\"Bone -\u003e Rotate\") to rotate\nthe selected bone in the displayed pose.\n\nIn scene views, you can also rotate the selected bone by grabbing\nany of the bone's 3 axis tips with the RMB and dragging with the mouse.\nThe axis tips are constrained to an invisible sphere surrounding the\nselected bone's head, so for many mouse-pointer screen locations,\n2 axis directions are possible.\nWhile you're dragging a bone axis, Maud remembers whether the axis\ninclines toward the camera or away from it.\nYou can toggle this inclination using the \"S\" shortcut key.\n\nThe displayed pose has many uses.  For instance:\nTo save a pose (creating a new, zero-length animation from it)\nselect \"Animations -\u003e Add new -\u003e Pose\".\nTo insert keyframes (and replace any pre-existing keyframes)\nat the current time in the loaded animation,\nselect \"Animations -\u003e Edit -\u003e Insert keyframes\".\nTo insert a keyframe (or replace the pre-existing keyframe)\nat the current time in the selected bone track,\nselect \"Keyframe -\u003e Insert from pose\".\nTo alter all keyframes in the selected bone\ntrack, use the \"Set all to pose\" buttons in the \"Keyframe Tool\"\n(\"Keyframe -\u003e Tool\").\n\nYou can also use the displayed pose like a paste buffer, to copy bone transforms\nfrom one time to another.\nFor this to work, you must \"freeze\" the pose so Maud won't\noverwrite it as soon as the animation time changes.\nTo freeze the pose, either tick the \"freeze\" check box in the Animation Tool\nor use the \"F\" keyboard shortcut.\nThen go to the animation time when you want to paste and select\n\"Keyframe -\u003e Insert from pose\" (to paste to the selected bone track)\nor \"Animations -\u003e Edit -\u003e Insert keyframes\" (to paste to all bone tracks in the loaded animation).\nRemember to unfreeze the pose afterward!\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"map\"\u003e\u003c/a\u003e\n\n## The skeleton map\n\nOnce an animation is created for one model, it's a simple matter to\ncopy it to another model, provided both models have identical\nskeletons.\n\nTo retarget animations between models with different skeletons, Maud\nrequires a \"skeleton map\" to match up bones in the source model with\ncorresponding ones in the target model.\n(Corresponding bones may have different names and/or indices.)\n\nFurthermore, since jME bones don't have defined tails,\nit's often necessary to adjust bone orientations when retargeting\nanimations between models.\nTo automate these adjustments, each bone mapping in a jME skeleton\nmap includes a \"twist\" rotation value.\n\nMaud can load skeleton maps from assets, edit\nthem, save them, and use them to retarget animations.\nA few sample skeleton maps are build into Maud, such as \"SinbadToJaime\" which\nmaps Sinbad's skeleton to that of Jaime.\n\nUse the \"Mapping Tool\" (\"Map -\u003e Tool\") to load and edit skeleton maps.\nTo do anything with a skeleton map, you must have a source model loaded.\nTo add a mapping between 2 bones, select the source bone in the source\nmodel and the target bone in the target model, then click LMB on\nthe \"Map\" button in the lower left or use the equals (\"=\") keyboard shortcut.\n\nAs long as the 2 selected bones map to each other in the loaded map,\nthe corresponding bone mapping stays selected.\nYou can unmap the selected bone mapping (with the \"Unmap\" button) or\nadjust its twist value with the \"Twist Tool\" (\"Map -\u003e Twist tool\").\n\nWhen editing a skeleton map, it's helpful to see\nits effect on the target model in real time.\nTo do this, click LMB on the \"Show retargeted pose\" button in the Mapping Tool or\nselect \"Animations -\u003e Load -\u003e ( retargeted pose )\".\nWith this pseudo-animation loaded:\n\n + changing the source pose automatically updates the target pose,\n + changing the skeleton map automatically updates the target pose,\n + selecting a mapped source bone also selects the corresponding target bone,\n + selecting a mapped target bone also selects the corresponding source bone, and\n + dragging an axis of the target bone automatically updates the twist value of the selected bone mapping.\n\nTo save the loaded skeleton map, select \"Map -\u003e Save\".\n\nWhen you're ready to retarget animations between models,\nuse the \"Retarget Tool\" (\"Animations -\u003e Add new -\u003e Retarget source animation\").\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"edithistory\"\u003e\u003c/a\u003e\n\n## The edit history\n\nLike any serious editor, Maud provides an \"undo\" capability.\n\nMaud's undo capability is based on checkpointing the editor's state.\nTool visibility and positioning are not checkpointed, nor are shortcut\nkey bindings, but nearly everything else is, including selections, view mode,\nview options, and loaded models, maps, and animations.\n\nBy default, Maud creates a checkpoint before editing or unloading any map or model.\nYou can also create a checkpoint manually using the \"X\" keyboard shortcut.\nTo undo changes since the most recent checkpoint, use the \"Z\" keyboard shortcut.\n\nTo safeguard work since the last checkpoint,\nthe \"Z\" key often creates a new checkpoint as well.\nTo redo each change you've undone, use the \"Y\" keyboard shortcut.\n\nTo help you visualize and navigate your edit history,\nMaud provides a \"History Tool\" (selected using \"History -\u003e Tool\").\n\nThe edit history occupies heap memory.\nTo release this memory, you can delete the history using \"History -\u003e Clear\".\n\nMaud places a limit on the number of checkpoints you can have at any one time.\nThe default limit is 8.\nYou can alter this limit using the History Tool.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"scripting\"\u003e\u003c/a\u003e\n\n## Scripting\n\nMaud has a built-in JavaScript scripting capability based\non the [Nashorn] engine.\n\nDuring startup, Maud looks for a \"/Scripts/startup.js\" asset.\nThe built-in startup script (on the classpath) simply loads the Jaime model.\nHowever, if Maud finds a custom script in the \"Written Assets\" folder,\nit executes the custom script instead of the built-in one.\n\nTo auto-generate a custom startup script,\nselect \"Settings -\u003e Update startup script\".\nThe generated script will initialize:\n\n + asset locations\n + global options such as view mode, boundary position, menu-bar visibility,\n   performance debug mode, base index, and tweening techniques\n + most scene-view and score-view options\n + the screen positions of any selected tools\n\nNote that customized hotkeys and display settings\nare not included in the startup script.\nMaud has other mechanisms to make them persist.\n\nTo remove a custom startup script,\nselect \"Settings -\u003e Revert startup script to default\".\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"args\"\u003e\u003c/a\u003e\n\n## Command-line arguments\n\nThe following arguments can be specified on the command line (or in the Gradle\nbuild script) to configure Maud prior to executing its startup script:\n\n + `--forceDialog` (or `-f`)\n  to show the JME3 \"Display Settings\" dialog during startup.\n  This dialog can be used to edit display properties (such as resolution)\n  in case they become corrupted.  If this argument is not\n  specified, Maud shows the dialog only if it believes\n  (based on JME3 AppSettings) that this is the first time it has run.\n + `--openGL3` (or `-3`)\n  to force LWJGL to use the core OpenGL3.2 renderer.\n  Forcing this renderer enables Maud to run on systems with\n  non-proprietary GPU drivers.\n + `--skipStartup` (or `-s`)\n  to bypass the startup script.  If this argument is not specified, Maud\n  looks for a startup script and attempts to execute it before displaying the\n  Editor Screen.\n + `--verbose` (or `-v`)\n  to generate verbose log output.\n  This output may assist in diagnosing certain issues.\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"links\"\u003e\u003c/a\u003e\n\n## External links\n\nYouTube videos about Maud:\n\n+ January 2018 demo (pick-and-drag editing):\n  https://www.youtube.com/watch?v=OLLl7xiuCw0 (8:43)\n+ December 2017 demo (importing animated models via glTF):\n  https://www.youtube.com/watch?v=tv7QgAtwDCA (7:47)\n+ September 2017 spatial animation clip:\n  https://www.youtube.com/watch?v=EDtiYu-u_Ls (0:12)\n+ September 2017 demo part 2:\n  https://www.youtube.com/watch?v=2kmxOzDCl_8 (28:22)\n+ September 2017 demo part 1:\n  https://www.youtube.com/watch?v=4UwxbsOewow (15:02)\n+ June 2017 retargeted animation clip:\n  https://www.youtube.com/watch?v=yRjh1rAsipI (0:09)\n+ May 2017 demo (out-of-date!):\n  https://www.youtube.com/watch?v=fSjsbyBWlPk (9:13)\n\n\u003ca name=\"bvh\"\u003e\u003c/a\u003e\n\nBVH resources:\n\n+ BVH format description:\n  http://research.cs.wisc.edu/graphics/Courses/cs-838-1999/Jeff/BVH.html\n+ motion-capture data from CMU's Graphics Lab, converted to BVH by Bruce Hahn:\n  https://sites.google.com/a/cgspeed.com/cgspeed/motion-capture\n+ free motion-capture data from Ohio State University's ACCAD:\n  https://accad.osu.edu/research/motion-lab/system-data\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"wishlist\"\u003e\u003c/a\u003e\n\n## Wish list\n\nMaud is incomplete.\nThe following features are on my \"to do\" list, in no particular order:\n\n + advance/delay keyframe(s)\n + better support for physics controls/joints/objects/shapes\n + smoother camera motion in score views\n + select bone mappings that don't correspond to the loaded models\n + export a model to [OBJ] format\n + export an animation to [BVH](#bvh) format\n + localization\n + more scene-view options for platform\n + tool tips\n + mirror an animation/pose\n + joint-angle limits for models\n\n[Jump to the table of contents](#toc)\n\n\u003ca name=\"conventions\"\u003e\u003c/a\u003e\n\n## Conventions\n\nMaud's source code is compatible with JDK 7.\n\nWorld coordinate system: the Y axis points upward (toward the zenith).\nPrior to loading a model that uses the Z-up convention, select the \"+Z up\"\nload orientation in the Settings Tool (\"Settings\" -\u003e \"Tool\").\n\nThe first keyframe in each track must be at time=0.\n\n[Jump to the table of contents](#toc)\n\n\n\u003ca name=\"history\"\u003e\u003c/a\u003e\n\n## History\n\nSince April 2017, the Maud project has been hosted at\nhttps://github.com/stephengold/Maud\n\nMaud began as a demo application for the jme3-utilities-debug library,\npart of the jme3-utilities project at\nhttps://github.com/stephengold/jme3-utilities\n\nMaud incorporates code from [jMonkeyEngine][jme] and the [BVH Retarget Project][bvhretarget].\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, Maud builds on the work of many who\nhave gone before.  I therefore acknowledge the following\nartists and software developers:\n\n+ Rémy Bouquet (aka \"nehon\") for creating the Jaime model and the [BVH Retarget\n  Project][retarget] and also for many helpful insights\n+ Paul Speed (aka \"pspeed\") for many helpful insights\n+ David Bernard (aka \"david_bernard_31\") for creating [Xbuf]\n+ Adam T. Ryder (aka \"tryder\") for creating [jME-TTF]\n+ Tobias Jung for creating [ProFont]\n+ [Nathan Vegdahl][vegdahl], for creating the Puppet model\n+ [Can Bican][bican], for creating the Jprefctl preferences editor\n+ Zi Ye, for creating the Sinbad model\n+ Alweth on hub.jmonkeyengine.org forums\n  for providing `IQELoader` for use, free of charge\n+ the brave souls who volunteered to be alpha testers for Maud, including:\n    + \"Jesterrrrrr\"\n    + Moff Kalast\n    + Adam (aka \"safari\")\n    + Ryan (aka \"yaRnMcDonuts\")\n    + \"raistm\"\n    + Remy Van Doosselaer (aka \"remy_vd\")\n    + \"Ali_RS\"\n    + \"Toboi\"\n+ plus the creators of (and contributors to) the following software:\n    + [Adobe Photoshop Elements][elements]\n    + the [Blender] 3-D animation suite\n    + the [Bullet] real-time physics library\n    + the [Checkstyle] tool\n    + the [FindBugs] source-code analyzer\n    + the [Firefox] and [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 virtual machine\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 [MakeHuman] 3-D character creation tool\n    + the [Markdown] document-conversion tool\n    + Microsoft Windows\n    + the [Nifty] graphical user-interface library\n    + [Open Broadcaster Software Studio][obs]\n    + the PMD source-code analyzer\n    + [ProFont], the programmers' font\n    + the [RealWorld Cursor Editor][rwce]\n    + the [WinMerge] differencing and merging tool\n\nI am grateful to [GitHub], [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[adoptium]: https://adoptium.net/releases.html \"Adoptium Project\"\n[ant]: https://ant.apache.org \"Apache Ant Project\"\n[bican]: https://github.com/canbican \"Can Bican\"\n[blender]: https://docs.blender.org \"Blender Project\"\n[bullet]: https://pybullet.org/wordpress \"Bullet Real-Time Physics Simulation\"\n[bvhretarget]: https://github.com/Nehon/bvhretarget \"BVH Retarget Project\"\n[checkstyle]: https://checkstyle.org \"Checkstyle\"\n[chrome]: https://www.google.com/chrome \"Chrome\"\n[elements]: https://www.adobe.com/products/photoshop-elements.html \"Photoshop Elements\"\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[gltf]: https://www.khronos.org/gltf \"glTF Project\"\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[iqe]: http://sauerbraten.org/iqm \"Inter-Quake Model Formats\"\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[jme-ttf]: https://1337atr.weebly.com/jttf.html \"jME-TTF Rendering System\"\n[license]: https://github.com/stephengold/Maud/blob/master/LICENSE \"Maud license\"\n[makehuman]: http://www.makehumancommunity.org/ \"MakeHuman Community\"\n[markdown]: https://daringfireball.net/projects/markdown \"Markdown Project\"\n[minie]: https://github.com/stephengold/Minie \"Minie Project\"\n[mint]: https://linuxmint.com \"Linux Mint Project\"\n[nashorn]: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/nashorn \"Nashorn User Guide\"\n[netbeans]: https://netbeans.org \"NetBeans Project\"\n[nifty]: https://nifty-gui.github.io/nifty-gui \"Nifty GUI Project\"\n[obj]: https://www.fileformat.info/format/wavefrontobj/egff.htm \"Wavefront OBJ File Format\"\n[obs]: https://obsproject.com \"Open Broadcaster Software Project\"\n[ogre]: https://www.ogre3d.org \"Ogre Project\"\n[openJDK]: https://openjdk.java.net \"OpenJDK Project\"\n[profont]: https://tobiasjung.name/profont \"ProFont Project\"\n[retarget]: https://github.com/Nehon/bvhretarget \"BVH Retarget Project\"\n[rwce]: http://www.rw-designer.com/cursor-maker \"RealWorld Cursor Editor\"\n[skycontrol]: https://github.com/stephengold/SkyControl \"SkyControl Project\"\n[utilities]: https://github.com/stephengold/jme3-utilities \"Jme3-utilities Project\"\n[vegdahl]: https://www.cessen.com \"Nathan Vegdahl\"\n[wes]: https://github.com/stephengold/Wes \"Wes Project\"\n[winmerge]: https://winmerge.org \"WinMerge Project\"\n[xbuf]: https://github.com/xbuf/xbuf \"Xbuf Project\"\n[youtube]: https://www.youtube.com/ \"YouTube\"\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fmaud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephengold%2Fmaud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephengold%2Fmaud/lists"}