{"id":19876700,"url":"https://github.com/dirktoewe/sjmply","last_synced_at":"2025-05-02T12:30:21.003Z","repository":{"id":176082586,"uuid":"80633071","full_name":"DirkToewe/sjmply","owner":"DirkToewe","description":"Simple Java Model for the PLY File Format","archived":false,"fork":false,"pushed_at":"2021-09-10T19:39:39.000Z","size":65,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-26T05:47:01.206Z","etag":null,"topics":["java","java-8","mesh","mesh-import","meshviewer","ply"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DirkToewe.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-02-01T15:24:48.000Z","updated_at":"2023-09-08T17:20:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"63eedf76-6115-4331-958f-d410333d4025","html_url":"https://github.com/DirkToewe/sjmply","commit_stats":null,"previous_names":["dirktoewe/sjmply"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirkToewe%2Fsjmply","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirkToewe%2Fsjmply/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirkToewe%2Fsjmply/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DirkToewe%2Fsjmply/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DirkToewe","download_url":"https://codeload.github.com/DirkToewe/sjmply/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252038063,"owners_count":21684617,"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":["java","java-8","mesh","mesh-import","meshviewer","ply"],"created_at":"2024-11-12T16:33:58.042Z","updated_at":"2025-05-02T12:30:20.997Z","avatar_url":"https://github.com/DirkToewe.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sjmply\n\nsjmply is a simple Java-based model for [PLY files](https://en.wikipedia.org/wiki/PLY_(file_format)).\n\n## Reading a PLY File\n```Java\nimport java.nio.file.Path;\nimport java.nio.file.Paths;\nimport org.jengineering.sjmply.PLY;\n\nPath path = Paths.get( System.getProperty(\"user.home\"), \"Documents/3d_models/bunny.ply\" );\nPLY bunny = PLY.load(path);\nSystem.out.println(bunny);\n```\n\n## Visualizing a PLY File\nsjmply offers convenience methods that generate standalone HTML visualizations of a PLY file,\neither as triangle mesh or point cloud (scatter plot). The visualization uses [Plotly](Plot.ly).\nAs of now these methods are only meant for debugging and quick visualization. They do not support\nthe full configurability and features that Plotly itself offers.\n\nIn order to minimize the HTML file size, the data is compressed as zip archive.\n[JSZip](https://stuk.github.io/jszip/) is used to decompress the data during loading.\n\n### Mesh\n```Java\nimport org.jengineering.sjmply.PLY_Plotly;\n\nPLY_Plotly.Mesh3d_show(\"Bunneh\",bunny);\n```\n\n### Point Cloud\n```Java\nimport org.jengineering.sjmply.PLY_Plotly;\n\nPLY_Plotly.Scatter3d_show(\"Bunneh\",bunny);\n```\n\n## Accessing Elements and Properties\nThe data in PLY files is organized in element lists. In an element list, all elements\nhave the same properties. The element lists and their properties are declared in the\nfile header. The format can be extended with additional element lists and properties.\n\nSupported property types are:\n  * int8, int16, int32 (char, short, int)\n  * uint8, uint16, uint32 (uchar, ushort, uint)\n  * float32, float64 (float, double)\n  * list\n\nThe list type has an associated size type and an element type that need to be declare alongside it,\ne.g. `property list uint8 uint32 vertex_indices` is a property of name `vertex_indices`\nwhose type is a list with a size type of `uint8` and an element type `uint32`. It is\nunclear to the author of sjmply whether or not nested lists (e.g. `list uint8 list uint8 float32`)\nare allowed according to the PLY file specification. sjmply however supports them,\nother PLY file libraries might not. Elements are accessed by their name using the `elements()` method.\n```Java\nPLYElementList\n  vertex = bunny.elements(\"vertex\"),\n  face = bunny.elements(\"face\");\nSystem.out.println(vertex);\nSystem.out.println(face);\n```\n\nsjmply stores property data in form or primitive arrays. The primitive types are mapped to the Java\nprimitive types of the same bit count. Those array can be accessed using the `property()` method.\n```Java\nimport java.util.Arrays;\nimport static org.jengineering.sjmply.PLYType.*;\n\nfloat[] x = vertex.property(FLOAT32,\"x\");\nint[][] vertex_indices = face.property(LIST(UINT32),\"vertex_indices\");\nSystem.out.println( Arrays.toString(x) );\nSystem.out.println( Arrays.deepToString(vertex_indices) );\n```\nThe specified type must match the exact property type. Calling `property(LIST(FLOAT64), ...)` on a \n`LIST(FLOAT32)` property will fail. An `IllegalArgumentException` is thrown.\n\nThe array returned by the `property()` method is the underlying data array. Changes to the array changes\nthe content of the element list. The entry `arr[i]` of an array `arr` represents the property value of the\n(i+1)th element.\n\nKeep in mind that there are no unsigned integer types in Java. Unsigned value have to be handled accordingly.\nIt is recommended to convert them to a higher bit count signed integer, e.g. using the [Byte.toUnsignedInt](https://docs.oracle.com/javase/8/docs/api/java/lang/Byte.html#toUnsignedInt-byte-), [Short.toUnsignedInt](https://docs.oracle.com/javase/8/docs/api/java/lang/Short.html#toUnsignedInt-short-) or the [Integer.toUnsignedLong](https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#toUnsignedLong-int-) method.\n\nThe `propertyAs()` method allows to canonically read property data. It always returns a new array which contains\nthe data converted to the requested type.\n```Java\ndouble[] x_double = vertex.propertyAs(FLOAT64,\"x\");\nshort[][] vertex_indices_short = face.propertyAs(LIST(UINT16),\"vertex_indices\");\n```\nConversion between integer types are allowed, as long as there is no integer over- or underflow during conversion.\nAny number type can be converted to a floating point type potentially causing loss of data. A conversion from\nfloat to integer is not supported.\n\n## Converting a Property\nIn order to canonicalize PLY files, it may become necessary to convert different typs of the same property\nto a uniform type. The `convertProperty` method allows just that.\n```Java\nbunny.elements(\"face\").convertProperty( \"vertex_indices\", LIST(UINT8,UINT16) );\nSystem.out.println( bunny.elements(\"face\") );\n```\nWhile converting a property from one list type to another the size type has to be specified. Calling\n`convertProperty( \"vertex_indices\", LIST(UINT16) )` will not even compile.\n\n## Writing a PLY File\nA PLY instance can be written to a file using its `save()` method.\n```Java\nPath out = Paths.get(\"/tmp/bunny.ply\");\nbunny.save(out);\n```\n\n## Creating a PLY File\nPLY instance can created in-memory using their constructor.\n```Java\nPLY ply = new PLY();\nSystem.out.println(ply);\n```\n\n## Adding an Element List\nNew element lists can be directly added to the `elements` map of a PLY instance.\n```Java\nPLYElementList edge = new PLYElementList(1337);\nply.elements.put(\"edge\",edge);\nSystem.out.println(ply);\n```\n\nThe size of an element has to be specified while creating it. In this case a list of 1337 \"edges\" was created.\n\n## Adding a Property\nThe `addProperty()` methods adds a new property to an element list.\n```Java\nedge.addProperty(LIST(UINT8,UINT32),\"vertex_indices\");\nSystem.out.println(ply);\n```\nWhile adding a property from one list type to another the size type has to be specified. Calling\n`addProperty(LIST(UINT32),\"vertex_indices\")` will not even compile.\n\n## Changing the Output Format\nThe output format of a PLY instance is determined by its `format` field. To change it use the\n`setFormat()` method.\n```Java\nimport static org.jengineering.sjmply.PLYFormat.*;\n\nbunny.setFormat(ASCII);\nSystem.out.println(bunny);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirktoewe%2Fsjmply","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirktoewe%2Fsjmply","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirktoewe%2Fsjmply/lists"}