{"id":35804303,"url":"https://github.com/271374667/pypmxvmd","last_synced_at":"2026-01-16T06:13:45.647Z","repository":{"id":331840947,"uuid":"1129522032","full_name":"271374667/pypmxvmd","owner":"271374667","description":"Wrapper for reading and modifying VMD and PMX files","archived":false,"fork":false,"pushed_at":"2026-01-11T11:05:54.000Z","size":172,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-11T14:59:04.987Z","etag":null,"topics":["3d","mikumikudance","mmd","pmx","vmd"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pypmxvmd/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/271374667.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T07:55:47.000Z","updated_at":"2026-01-11T11:08:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/271374667/pypmxvmd","commit_stats":null,"previous_names":["271374667/pypmxvmd"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/271374667/pypmxvmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/271374667%2Fpypmxvmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/271374667%2Fpypmxvmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/271374667%2Fpypmxvmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/271374667%2Fpypmxvmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/271374667","download_url":"https://codeload.github.com/271374667/pypmxvmd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/271374667%2Fpypmxvmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","mikumikudance","mmd","pmx","vmd"],"created_at":"2026-01-07T12:14:07.005Z","updated_at":"2026-01-16T06:13:45.638Z","avatar_url":"https://github.com/271374667.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyPMXVMD\n\n![pypmxvmd](https://socialify.git.ci/271374667/pypmxvmd/image?description=1\u0026font=Inter\u0026language=1\u0026name=1\u0026owner=1\u0026theme=Auto)\n\n[English API](docs/API.md) | [中文 API](docs/API_CN.md)\n\nPython MikuMikuDance File Parser Library\n\n[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-2.7.1-orange.svg)](https://github.com/pypmxvmd/pypmxvmd)\n\nPyPMXVMD is a Python library for parsing and modifying MikuMikuDance (MMD) files, supporting the following formats:\n\n- **VMD** (Vocaloid Motion Data) - Motion/animation data\n- **PMX** (Polygon Model eXtended) - 3D model data\n- **VPD** (Vocaloid Pose Data) - Pose data\n\n## Features\n\n- Full support for reading and writing VMD, PMX, and VPD files\n- Conversion between binary and text formats\n- Object-oriented API design, easy to use\n- Complete type annotation support\n- Optional Cython acceleration for core parsing and binary I/O (VMD/PMX, binary read/write)\n- No external dependencies (core functionality)\n- Supports Python 3.8+\n\n## Installation\n\n```bash\n# Install from PyPI\npip install pypmxvmd\n\n# Install from source\ngit clone https://github.com/pypmxvmd/pypmxvmd.git\ncd pypmxvmd\npip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n### Optional: Build Cython Accelerators\n\nThe core parsing path supports Cython-accelerated modules for VMD/PMX and binary I/O.\nIn typical workloads, the Cython implementation is ~3.7x faster on average than the previous implementation.\nPrebuilt wheels are provided for Windows (cp38-cp313). Other platforms or versions compile locally.\nIf the compiled modules are not available, the library automatically falls back to pure Python.\n\n```bash\npip install cython\npython scripts/build_cython.py\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport pypmxvmd\n\n# Load VMD motion file\nmotion = pypmxvmd.load_vmd(\"motion.vmd\")\nprint(f\"Bone frames: {len(motion.bone_frames)}\")\nprint(f\"Morph frames: {len(motion.morph_frames)}\")\n\n# Modify and save\npypmxvmd.save_vmd(motion, \"modified_motion.vmd\")\n\n# Load PMX model file\nmodel = pypmxvmd.load_pmx(\"model.pmx\")\nprint(f\"Vertices: {len(model.vertices)}\")\nprint(f\"Materials: {len(model.materials)}\")\n\n# Load VPD pose file\npose = pypmxvmd.load_vpd(\"pose.vpd\")\nprint(f\"Bone poses: {len(pose.bone_poses)}\")\n```\n\n### Automatic Format Detection\n\n```python\nimport pypmxvmd\n\n# Automatically detect file type and load\ndata = pypmxvmd.load(\"file.vmd\")  # Returns VmdMotion\ndata = pypmxvmd.load(\"file.pmx\")  # Returns PmxModel\ndata = pypmxvmd.load(\"file.vpd\")  # Returns VpdPose\n\n# Automatically detect data type and save\npypmxvmd.save(motion, \"output.vmd\")\npypmxvmd.save(model, \"output.pmx\")\npypmxvmd.save(pose, \"output.vpd\")\n```\n\n### Text Format Conversion\n\nPyPMXVMD supports converting binary files to readable text format for viewing and editing:\n\n```python\nimport pypmxvmd\n\n# VMD -\u003e Text\nmotion = pypmxvmd.load_vmd(\"motion.vmd\")\npypmxvmd.save_vmd_text(motion, \"motion.txt\")\n\n# Text -\u003e VMD\nmotion = pypmxvmd.load_vmd_text(\"motion.txt\")\npypmxvmd.save_vmd(motion, \"motion.vmd\")\n\n# PMX -\u003e Text\nmodel = pypmxvmd.load_pmx(\"model.pmx\")\npypmxvmd.save_pmx_text(model, \"model.txt\")\n\n# VPD -\u003e Text\npose = pypmxvmd.load_vpd(\"pose.vpd\")\npypmxvmd.save_vpd_text(pose, \"pose.txt\")\n```\n\n### Using Parser Classes\n\nIf you need more control, you can use the parser classes directly:\n\n```python\nfrom pypmxvmd import VmdParser, PmxParser, VpdParser\n\n# VMD Parser\nvmd_parser = VmdParser()\nmotion = vmd_parser.parse_file(\"motion.vmd\", more_info=True)\nvmd_parser.write_file(motion, \"output.vmd\")\n\n# PMX Parser\npmx_parser = PmxParser()\nmodel = pmx_parser.parse_file(\"model.pmx\", more_info=True)\npmx_parser.write_file(model, \"output.pmx\")\n\n# VPD Parser\nvpd_parser = VpdParser()\npose = vpd_parser.parse_file(\"pose.vpd\", more_info=True)\nvpd_parser.write_file(pose, \"output.vpd\")\n```\n\n## Data Structures\n\n### VmdMotion (VMD Motion)\n\n```python\nclass VmdMotion:\n    header: VmdHeader           # File header information\n    bone_frames: List[VmdBoneFrame]      # Bone keyframes\n    morph_frames: List[VmdMorphFrame]    # Morph keyframes\n    camera_frames: List[VmdCameraFrame]  # Camera keyframes\n    light_frames: List[VmdLightFrame]    # Light keyframes\n    shadow_frames: List[VmdShadowFrame]  # Shadow keyframes\n    ik_frames: List[VmdIkFrame]          # IK keyframes\n```\n\n### PmxModel (PMX Model)\n\n```python\nclass PmxModel:\n    header: PmxHeader           # File header information\n    vertices: List[PmxVertex]   # Vertex list\n    faces: List[int]            # Face indices\n    textures: List[str]         # Texture paths\n    materials: List[PmxMaterial]  # Material list\n    bones: List[PmxBone]        # Bone list\n    morphs: List[PmxMorph]      # Morph list\n    frames: List[PmxFrame]      # Display frames\n    rigidbodies: List[PmxRigidBody]  # Rigidbody list\n    joints: List[PmxJoint]      # Joint list\n```\n\n### VpdPose (VPD Pose)\n\n```python\nclass VpdPose:\n    model_name: str             # Model name\n    bone_poses: List[VpdBonePose]   # Bone pose list\n    morph_poses: List[VpdMorphPose] # Morph pose list\n```\n\n## API Reference\n\n### Core Functions\n\n| Function | Description |\n|------|------|\n| `load_vmd(path)` | Load VMD file |\n| `save_vmd(motion, path)` | Save VMD file |\n| `load_pmx(path)` | Load PMX file |\n| `save_pmx(model, path)` | Save PMX file |\n| `load_vpd(path)` | Load VPD file |\n| `save_vpd(pose, path)` | Save VPD file |\n| `load(path)` | Auto-detect and load |\n| `save(data, path)` | Auto-detect and save |\n\n### Text Format Functions\n\n| Function | Description |\n|------|------|\n| `load_vmd_text(path)` | Load VMD from text |\n| `save_vmd_text(motion, path)` | Save VMD as text |\n| `load_pmx_text(path)` | Load PMX from text |\n| `save_pmx_text(model, path)` | Save PMX as text |\n| `load_vpd_text(path)` | Load VPD from text |\n| `save_vpd_text(pose, path)` | Save VPD as text |\n| `load_text(path)` | Auto-detect and load text |\n| `save_text(data, path)` | Auto-detect and save text |\n\n## Project Structure\n\n```\npypmxvmd/                     # Main package\n  __init__.py                 # Public API (load/save helpers)\n  common/                     # Core implementation\n    io/                       # Binary/text IO (+ Cython accel)\n    models/                   # Data models (VMD/PMX/VPD)\n    parsers/                  # Parsers (+ fast modules)\n    validators/               # Validation helpers\ndocs/                         # Documentation\n  API.md                      # English API\n  API_CN.md                   # 中文 API\nscripts/                      # Build helpers\n  build_cython.py\n  build_wheels.py\ntests/                        # Tests + fixtures\n```\n\n\n## Testing\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run specific test\npytest tests/test_vmd_parser.py -v\n\n# Run coverage test\npytest tests/ --cov=pypmxvmd --cov-report=html\n```\n\n## Development\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Code formatting\nblack pypmxvmd/\nisort pypmxvmd/\n\n# Type checking\nmypy pypmxvmd/\n\n# Code linting\nflake8 pypmxvmd/\n```\n\n## Changelog\n\n### v2.7.1\n- Updated core parsers and binary I/O with Cython fast paths\n- Added/expanded Windows wheel builds (cp38-cp313)\n- Improved text format auto-detection and test coverage\n\n### v2.5.1\n- Added optional Cython acceleration for core parsing and binary I/O\n- Cython path averages ~3.7x faster than the previous implementation\n\n### v2.0.0 (2024)\n- Complete refactor to object-oriented architecture\n- Added complete type annotations\n- Support for text format export/import\n- Improved error handling and validation\n- Added progress callback support\n\n### v1.x (Original)\n- Based on Nuthouse01's original implementation\n- Functional API\n\n## Acknowledgments\n\nThis project is refactored from the original MMD scripting tools by [Nuthouse01](https://github.com/Nuthouse01/PMX-VMD-Scripting-Tools).\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file for details\n\n## Contributing\n\nIssues and Pull Requests are welcome!\n\n1. Fork this repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F271374667%2Fpypmxvmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F271374667%2Fpypmxvmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F271374667%2Fpypmxvmd/lists"}