PSD2Live turns layered PSDs into editable Live2D models

What PSD2Live actually automates, and for whom

Rigging a Live2D character by hand means building a mesh over every art layer, placing deformers, wiring parameters to those deformers, and then writing physics so hair and eyes react without exploding. PSD2Live targets the first pass of that work. You feed it a layered PSD, it identifies what each layer is, splits connected regions into left and right sides where needed, triangulates the artwork, builds a nine-axis face lattice with a decoupled deformer hierarchy, simulates hair swing and eye squash, generates a looping idle motion, and exports both an editable .cmo3 project and a runtime .moc3 file family.

The audience is narrow and specific. You need a PSD whose layers already follow the project's naming conventions, because the semantic recognition depends on them: the repository documents 31 semantic tags with Chinese, English and Japanese equivalents in docs/zh/spec/PSD_LAYER_SPEC.md. If your file is a flat illustration with layers called "Layer 4 copy 2", nothing downstream has anything to work with. The second audience is tooling people: the app exposes a local MCP server so an agent host can read the project, render PNG views and write keyframes, though the README is unusually blunt about how far that goes.

The mesh, warp and physics pipeline in detail

The geometry stage is the part with the most documented mechanism. Edge noise is removed with a separable Gaussian smoothing filter and 95th-percentile adaptive binarisation. Contours are then fitted with periodic cubic Bézier curves that include corner detection over a physical window, and sampling is curvature-weighted with up to 12x densification. Triangulation is constrained Delaunay, followed by topology convergence using Lawson edge flipping and midpoint bisection of over-long interior edges. The README shows mesh spacing at 22, 64 and 115 px as a density comparison, and the CLI exposes that as --mesh-spacing with a default of 64.

Warp generation is where the design choices show. Eyes and eyebrows share a perspective plane constraint, pupils get automatic inverse compensation so they do not squash, and eyelashes bend along an alpha-weighted centreline to form a smooth U-shaped closed-eye curve. The mouth compresses toward its centreline from the maximum-open pose, with teeth and tongue auto-masked by the mouth region. The nine-axis build establishes an 8x8 facial lattice over AngleX at plus or minus 45 degrees and AngleY at plus or minus 30 degrees, with a C1-continuous horizontal expand/compress curve (near side expands, near-eye width holds on a plateau, far side compresses in perspective), vertical V and inverted-V pitch curvature, and a corner cross-correction term the spec writes as Cxy = yaw x pitch.

Physics is deliberately split. Front and back hair follow the head shell as fully decoupled independent chains, built as a multi-pendulum system with fixed roots and a cubic v^3 swing gradient toward the tips. Eye opening and closing drives a second-order damped spring oscillator that outputs jelly-eye squash and rebound into ParamEyeBallForm. Note what is absent: the README does not document cloth, body jiggle beyond breathing, or accessory physics.

Installing PSD2Live and running a first export

For Windows 10/11 x64 the README points at the Releases page rather than a build. The portable ZIP unpacks and runs, and the EXE and MSI packages are alternatives; all three bundle a Java runtime, so you do not need a JDK. Only source builds need JDK 21 or higher. From the repository root, run-gui.bat starts the desktop application on Windows, and Gradle works on all three platforms.

# Linux / macOS
./gradlew run

That launches the GUI. The README lists Ctrl+O to open a PSD, Ctrl+R to re-analyse, and Ctrl+G to generate and export. If you would rather skip the interface, the CLI takes the same pipeline headlessly. The example below is the advanced form the README gives, with an 8192 px atlas, 48 px mesh spacing and boosted head deformation:

./gradlew.bat run --args="--input ./sample.psd --output ./output --atlas 8192 --mesh-spacing 48 --head-strength 1.2 --lang zh"

--input is required. --output defaults to a psd2live-output directory beside the PSD. --atlas accepts 256 to 16384 and defaults to 4096. --head-strength and --body-strength are floats from 0.0 to 4.0, both defaulting to 1.0. --no-physics, --no-cmo3 and --no-moc3 skip their respective outputs, which is useful for a first pass where you only want the runtime files.

After the run, the output directory should contain the .moc3 family: .model3.json, .cdi3.json, physics3.json, idle.motion3.json and the texture atlas, plus a .cmo3 project unless you passed --no-cmo3. The README states the pipeline runs three geometry self-check gates before export: neutral-pose fidelity, extreme-pose completeness, and deformer mirror symmetry.

Where PSD2Live is the wrong tool

The most consequential limitation is upstream of the code. Semantic layer recognition is the entry point for everything, and the README does not describe a fallback for unlabelled layers. A PSD that was never organised for rigging will not produce a usable model, and no flag fixes that.

Rendering consistency is the second boundary. The built-in renderer is a CPU software rasteriser, and it is the only option out of the box. The project does not include or distribute Live2D's official SDK binaries. Pixel-level and physics-level agreement with the official runtime requires you to configure the official Cubism 5-r.5 Native SDK yourself, following docs/zh/guide/CUBISM_SDK_SETUP.md, which covers the licence policy and shader extraction. Without that, the README describes an automatic fallback to CPU rendering. On Linux and macOS the README says CPU rasterisation is what you get.

The deform path feature is explicitly experimental. The README states the current algorithm has not passed Cubism Editor effect-consistency acceptance, even though paths are preserved on project save, written as native controllers in .cmo3, and exported as generated mesh deformation in .moc3.

And then there is the Agent/MCP layer, which deserves its own warning. The README's own capability list marks adding a head accessory and checking it from several parameter poses as the only available workflow. Parameter adjustment, expression and motion variants, simple layer splitting, mouth part separation, hair splitting and occlusion completion, waving motions, tail deformation and physics, and self-generated images with nine-axis adjustment are all listed as pending. Per-point precise deformation of a part is listed as not currently feasible. The README adds that pending items are extremely unstable end to end and should not be attempted except for debugging, and that repeated image generation, localisation and correction can burn large amounts of tokens and image quota for no usable result. It also notes that models which can read images but cannot generate and return them cannot complete the asset creation step at all.

How PSD2Live differs from Live2D Cubism and from sprite-based tools

The obvious alternative is Live2D Cubism Editor itself, and the difference is one of starting point rather than feature parity. Cubism gives you manual mesh drawing, deformer placement and parameter wiring, and it is the tool whose output defines correctness. PSD2Live attempts to generate that structure automatically and then hands you a .cmo3 that Cubism Modeler 5 can open for second-pass editing. The README frames the official SDK path as a ground-truth verification mode rather than as the product, and the project neither bundles nor redistributes those binaries. So the realistic workflow is PSD2Live for the first pass, Cubism for the correction pass, not one replacing the other.

The other family of alternatives is sprite-based animation tooling, where a character is a set of flat images moved as rigid pieces. That approach needs no mesh, no deformer tree and no physics solver, and it is far more predictable. It also cannot bend an eyelash into a closed-eye curve or drive a pendulum chain from a head shell, because there is no continuous surface to deform. PSD2Live's whole value proposition sits in the gap: it produces deformable geometry, and it accepts the complexity that comes with it.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-14. Three releases landed in the six days before that, v0.6.0 on 2026-09-08, then v0.7.0 and v0.7.1 on 2026-09-12. That cadence means the export formats and the CLI surface are still moving, so pin a release rather than tracking master if you are building a pipeline on top of it. The CLI flag set documented in the README is the contract to watch: --input, --output, --lang, --atlas, --mesh-spacing, --head-strength, --body-strength, --no-physics, --no-cmo3 and --no-moc3.

PSD2Live is GPL-3.0. If you distribute a modified build, or ship something that incorporates it, the copyleft terms apply to the combined work; if you only run it internally to produce .cmo3 and .moc3 assets, the output files are not the program. That is a general reading of how the licence operates, not legal advice, and the repository also carries a THIRD_PARTY_NOTICES.md and a licenses/ directory that you should read before relying on any of it commercially.

There is a second licence question the README raises directly. The official Live2D Native SDK is proprietary, and the project states it does not include or distribute those binaries. Enabling the official-renderer verification path therefore puts you under Live2D's own licence terms in addition to GPL-3.0, and docs/zh/guide/CUBISM_SDK_SETUP.md is where the project documents that policy.

Editorial conclusion

Adopt PSD2Live if you already have a layered PSD and want a .cmo3 you can open in Cubism Modeler 5 for hand correction, and you accept that the mesh, warp and physics output is a starting point rather than a finished rig. Do not adopt it if your PSD layers are unlabelled or merged, if you need macOS or Linux output to match the official runtime pixel for pixel, or if you are buying into the Agent/MCP authoring story: the README states those tasks are end-to-end unstable and not recommended outside debugging. Verify first that your layer names match the 31 semantic tags in docs/zh/spec/PSD_LAYER_SPEC.md, then run the CLI with --no-cmo3 on one character and check the generated mesh spacing before committing to a full export.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. tsunehimatoi/psd2live on GitHub