{"id":25898197,"url":"https://github.com/ruelalarcon/cpf3d","last_synced_at":"2026-06-08T12:02:37.537Z","repository":{"id":223981485,"uuid":"762069784","full_name":"ruelalarcon/cpf3d","owner":"ruelalarcon","description":"A package for reading and writing 3cpf files.","archived":false,"fork":false,"pushed_at":"2025-03-08T13:16:28.000Z","size":397,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-07T01:49:18.382Z","etag":null,"topics":["3cpf","points","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/cpf3d/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ruelalarcon.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}},"created_at":"2024-02-23T02:49:40.000Z","updated_at":"2025-03-08T13:16:32.000Z","dependencies_parsed_at":"2024-02-23T05:08:34.086Z","dependency_job_id":null,"html_url":"https://github.com/ruelalarcon/cpf3d","commit_stats":null,"previous_names":["ruelalarcon/cpf3d"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ruelalarcon/cpf3d","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruelalarcon%2Fcpf3d","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruelalarcon%2Fcpf3d/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruelalarcon%2Fcpf3d/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruelalarcon%2Fcpf3d/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ruelalarcon","download_url":"https://codeload.github.com/ruelalarcon/cpf3d/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ruelalarcon%2Fcpf3d/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34061123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["3cpf","points","python"],"created_at":"2025-03-03T00:17:31.264Z","updated_at":"2026-06-08T12:02:37.531Z","avatar_url":"https://github.com/ruelalarcon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cpf3d\r\n![GitHub Repo stars](https://img.shields.io/github/stars/ruelalarcon/cpf3d)\r\n![PyPI - License](https://img.shields.io/pypi/l/cpf3d)\r\n![GitHub top language](https://img.shields.io/github/languages/top/ruelalarcon/cpf3d)\r\n![PyPI - Version](https://img.shields.io/pypi/v/cpf3d)\r\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cpf3d)\r\n![PyPI - Format](https://img.shields.io/pypi/format/cpf3d)\r\n\r\n\u003e A python library to read and edit [3cpf](https://github.com/ruelalarcon/3cpf) files. Requires\r\n\u003e python 3.8.\r\n\r\n**Features**\r\n\r\n- Read 3cpf files into easily usable data\r\n- Create new points and frames\r\n- Apply basic position, scale, and rotation transformations to all points in a 3cpf file\r\n- Write 3cpf data into 3cpf files\r\n\r\n## Installation\r\n\r\nThe package can be installed with `pip`.\r\n\r\n```bash\r\npip install cpf3d\r\n```\r\n\r\n## Usage\r\n\r\n### Reading files\r\n\r\nThe `cpf3d.load` function can be used to load a 3cpf files as a `cpf3d.PointFrames` object, which has points and frames.\r\n\r\n```python\r\nimport cpf3d\r\n\r\n# Load a 3cpf file\r\npf = cpf3d.load('miku_example.3cpf')\r\n\r\n# From here, we can access any necessary data\r\nprint('# of Points:', len(pf.points))\r\nprint('# of Frames:', len(pf.frames))\r\n\r\n# Point colors\r\nprint('\\nColors of First 5 Points:')\r\nfor point in pf.points[:5]:\r\n    print(point.color)\r\n\r\n# Position of specific point at specific frame\r\nprint('\\nPositions of Point 0 Throughout First 5 Frames:')\r\nfor i in range(5):\r\n    print(pf.get_position(0, i))\r\n```\r\nOutput:\r\n```\r\n# of Points: 600\r\n# of Frames: 60\r\n\r\nColors of First 5 Points:\r\n(112, 112, 112)\r\n(112, 112, 112)\r\n(0, 0, 0)\r\n(112, 112, 112)\r\n(112, 112, 112)\r\n\r\nPositions of Point 0 Throughout First 5 Frames:\r\n[-0.01653824  0.05377164  1.10009   ]\r\n[-0.01205087  0.05788074  1.0995283 ]\r\n[-0.00502312  0.06201064  1.1008564 ]\r\n[0.00529542 0.06594937 1.1022888 ]\r\n[0.01859665 0.06944766 1.1035271 ]\r\n```\r\n\r\nIf your use-case uses a different coordinate order (XYZ vs. YXZ for example), you can load a 3cpf with any coordinate order of your choice.\r\n```python\r\nimport cpf3d\r\n\r\n# Load a 3cpf file, with dimensions in the order of xzy, rather than the default xyz\r\npf = cpf3d.load('miku_example.3cpf', 'xzy')\r\n```\r\n\r\n### Editing and Creating 3cpf Files\r\n\r\nYou can edit instances of `cpf3d.PointFrames` and save them as 3cpf files.\r\n\r\n```python\r\nimport cpf3d\r\n\r\n# Editing an existing 3cpf file\r\npf = nbtlib.load('miku_example.3cpf')\r\n\r\n# Rotate entire animation 90 degrees along the Z-axis\r\n# Scale to half size across all dimensions\r\n# And move 1 along the X-axis\r\npf.apply_rotation(0, 0, 90) \\\r\n  .apply_scale(.5, .5, .5) \\\r\n  .apply_offset(1, 0, 0)\r\n\r\n# Save the now-transformed point frames into a new file\r\npf.save('miku_example_transformed.3cpf')\r\n```\r\n\r\nOr write a 3cpf file from scratch.\r\n```python\r\nimport cpf3d\r\nfrom cpf3d import PointFrames, Point, Frame\r\n\r\n# Creating a 3cpf file from scratch\r\ncustom_pf = PointFrames()\r\n\r\npoint_r = Point(255, 0, 0) # Red point\r\npoint_g = Point(0, 255, 0) # Green point\r\n\r\ncustom_pf.add_point(point_r)\r\ncustom_pf.add_point(point_g)\r\n\r\n# First frame: Red point at 1,1,1. Green point at 2,2,2\r\nframe_1 = Frame([[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]])\r\n\r\n# Second frame: Red point at 2,2,2. Green point at 4,4,4\r\nframe_2 = Frame([[2.0, 2.0, 2.0], [4.0, 4.0, 4.0]])\r\ncustom_pf.add_frame(frame_1)\r\ncustom_pf.add_frame(frame_2)\r\n\r\n# Scale it all by ten times\r\ncustom_pf.apply_scale(10, 10, 10)\r\n\r\n# Export to a 3cpf file\r\ncustom_pf.save('my_pointframes.3cpf')\r\n```\r\n\r\n### Adding Points or Frames to Existing 3cpf Data\r\n\r\nThere are a variety of restrictions related to adding points or frames to existing 3cpf animations.\r\n\r\n**Firstly,** you cannot add frames *before* adding any points.\r\n```python\r\npf = PointFrames()\r\n\r\n# Will cause an error, as there are no points to attach this positional data to\r\nframe = Frame([[1.0, 2.0, 3.0]])\r\n```\r\n\r\n**Secondly,** when adding new frames, you must have one positional entry for each point.\r\n```python\r\n# Assume this 3cpf file contains 2 points\r\npf = cpf3d.load('2points.3cpf')\r\n\r\n# Will cause an error, as we are adding a frame with 1 position, but there are 2 points\r\nframe = Frame([[1.0, 2.0, 3.0]])\r\npf.add_frame(frame)\r\n\r\n# Similarly, this would also error\r\nframe = Frame([[1.0, 2.0, 3.0], [1.0, 2.0, 3.0], [1.0, 2.0, 3.0]])\r\npf.add_frame(frame)\r\n```\r\n\r\n**Lastly,** when adding new points, if you already have frames in your 3cpf file, you must provide positions for your new point at each frame.\r\n\r\n```python\r\n# Assume this 3cpf file contains 2 points and 2 frames\r\npf = cpf3d.load('2points2frames.3cpf')\r\n\r\n# Will cause an error, as there are already frames in this 3cpf animation\r\npoint = Point(255, 255, 255)\r\npf.add_point(point)\r\n```\r\n\r\nWe would instead need to do something like this:\r\n```python\r\npf = cpf3d.load('2points2frames.3cpf')\r\n\r\npoint = Point(255, 255, 255)\r\n\r\n# This point moves from 1,1,1 to 2,2,2 through frames 0 and 1\r\npositions = [[1.0, 1.0, 1.0], [2.0, 2.0, 2.0]]\r\n\r\npf.add_frame(point, positions) # This works fine\r\n```\r\n\r\nThis is necessary due to the nature of 3cpf files, in that each point must have corresponding positional data within each frame chunk.\r\n\r\n## Contributing\r\n\r\nContributions are welcome. This project is packaged with python's built-in [setuptools](https://setuptools.pypa.io/en/latest/).\r\n\r\nTo install this package locally for development, you can clone or download this repository and navigate to it in your terminal.\r\n\r\nYou should now be able to install it locally, including development dependencies.\r\n\r\n```bash\r\npip install -e .[dev]\r\n```\r\n\r\nYou can run the tests by simply executing pytest from the top directory.\r\n\r\n```bash\r\npytest\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruelalarcon%2Fcpf3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruelalarcon%2Fcpf3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruelalarcon%2Fcpf3d/lists"}