{"id":19071084,"url":"https://github.com/mokiat/java-data-front","last_synced_at":"2025-10-25T17:34:14.820Z","repository":{"id":18467460,"uuid":"21662282","full_name":"mokiat/java-data-front","owner":"mokiat","description":"A Java library for reading Wavefront 3D model resources (OBJ, MTL).","archived":false,"fork":false,"pushed_at":"2022-01-18T20:30:04.000Z","size":134,"stargazers_count":49,"open_issues_count":0,"forks_count":8,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-28T15:42:56.907Z","etag":null,"topics":["java","parsing","wavefront"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mokiat.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}},"created_at":"2014-07-09T17:43:31.000Z","updated_at":"2024-10-06T15:11:30.000Z","dependencies_parsed_at":"2022-09-11T20:20:52.479Z","dependency_job_id":null,"html_url":"https://github.com/mokiat/java-data-front","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mokiat/java-data-front","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mokiat%2Fjava-data-front","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mokiat%2Fjava-data-front/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mokiat%2Fjava-data-front/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mokiat%2Fjava-data-front/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mokiat","download_url":"https://codeload.github.com/mokiat/java-data-front/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mokiat%2Fjava-data-front/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267029407,"owners_count":24024199,"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","status":"online","status_checked_at":"2025-07-25T02:00:09.625Z","response_time":70,"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":["java","parsing","wavefront"],"created_at":"2024-11-09T01:22:18.072Z","updated_at":"2025-10-25T17:34:09.771Z","avatar_url":"https://github.com/mokiat.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"java-data-front\n===============\n\n![maven verify status](https://github.com/mokiat/java-data-front/actions/workflows/maven.yml/badge.svg?branch=master)\n\nA Java library for reading Wavefront 3D model resources (OBJ, MTL).\n\nThe OBJ and MTL file formats are one of the most popular 3D model formats used at the moment. This is mainly due to their simplicity.\n\nOBJ files are used to describe the coordinates, connections and shapes that make up a 3D model.\n\n```\nv -1.0 1.0 0.0\nv -1.0 -1.0 0.0\nv 1.0 -1.0 0.0\nv 1.0 1.0 0.0\n\no Rectangle\nf 1 2 3\nf 1 3 4\n```\n\nMTL files are optional and are present when a 3D model uses materials.\n\n```\nnewmtl TestMaterial\nKa 1.0 0.5 0.1\nKd 0.5 0.7 0.3\nKs 0.2 0.4 0.8\nNs 650\nd 0.7\nmap_Kd vehicle.png\n```\n\nThe `obj` and `mtl` file formats were originally developed by the Wavefront Technologies company for their 3D visualizer software. Currently, they are available in practically all 3D modeling solutions.\n\n## Loading OBJ resources\n\nUsing this library is meant to be easy and straightforward. All you need to do is instantiate an `OBJParser` and pass it an `InputStream` to your OBJ resource.\n\n**Example:**\n\n```java\n// Open a stream to your OBJ resource\ntry (InputStream in = new FileInputStream(\"example.obj\")) {\n  // Create an OBJParser and parse the resource\n  final IOBJParser parser = new OBJParser();\n  final OBJModel model = parser.parse(in);\n\n  // Use the model representation to get some basic info\n  System.out.println(MessageFormat.format(\n          \"OBJ model has {0} vertices, {1} normals, {2} texture coordinates, and {3} objects.\",\n          model.getVertices().size(),\n          model.getNormals().size(),\n          model.getTexCoords().size(),\n          model.getObjects().size()));  \n}\n```\n\nWhen you parse an OBJ resource, you get a `OBJModel` representation.\nWe use the `getVertices`, `getNormals`, and `getTexCoords` methods to get access to all of the vertices, normals and texture coordinates respectively that are defined in the OBJ resource. Since these can be shared between multiple objects, their getter methods are defined on the root `OBJModel` element.\n\nAdditionally, you have the `getMaterialLibraries` method. It provides a list of all the material dependencies that were declared in the OBJ resource. The method returns a list of strings, representing resources that can be parsed via a `MTLParser` parser. It is up to your implementation to locate those resources and process them, as the `OBJParser` has no way of knowing from where the OBJ resource originates.\n\nThe `getObjects` method lists all of the objects that are defined in the OBJ resource. These are the entities you would usually iterate through to get the mesh data.\n\n**Example:**\n\n```java\nfor (OBJObject object : model.getObjects()) {\n    for (OBJMesh mesh : object.getMeshes()) {\n        for (OBJFace face : mesh.getFaces()) {\n        \t// You have reached a face.\n        }\n    }\n}\n```\n\nOne thing that does not exactly match the OBJ specification is the `OBJMesh` concept. This object is used to encapsulate any material dependencies of the object and corresponding mesh. To be more precise, it is possible that a single `OBJObject` has triangles with different materials. The `OBJMesh` is used to group these different material dependencies.\n\n**Example:**\n\n```java\nfinal OBJMesh mesh = ...;\nfinal String materialName = mesh.getMaterialName();\nfinal List\u003cOBJFace\u003e faces = mesh.getFaces();\n```\n\nOne would use the `materialName` value to select the proper material to use for rendering the list of `OBJFace` instances. The actual material would need to have been parsed in advance (as explained above) and probably stored in a map structure for easy access.\n\nKnowing how to get to all faces and related materials, one needs a way to get the mesh data of each individual face.\n\n**Example:**\n\n```java\nfinal OBJFace face = ...; // You already know how to get this.\nfor (OBJDataReference reference : face.getReferences()) {\n    final OBJVertex vertex = model.getVertex(reference);\n    System.out.println(MessageFormat.format(\n    \t\"Vertex ({0}, {1}, {2})\", vertex.x, vertex.y, vertex.z));\n    if (reference.hasNormalIndex()) {\n        final OBJNormal normal = model.getNormal(reference);\n        System.out.println(MessageFormat.format(\n        \t\"Normal ({0}, {1}, {2})\", normal.x, normal.y, normal.z));\n    }\n    if (reference.hasTexCoordIndex()) {\n    \tfinal OBJTexCoord texCoord = model.getTexCoord(reference);\n        System.out.println(MessageFormat.format(\n        \t\"TexCoord ({0}, {1})\", texCoord.u, texCoord.v));\n    }\n}\n```\n\nA face can be defined by arbitrary number of vertices, as long as they are more than three. This is why each face has the `getReferences` method that returns a list of `OBJDataReference` objects. This object represents a single vertex and allows you to locate the positional, normal and texture coordinate information for that vertex. This happens through the usage for indices that point at the master data (the one available through `getVertices`, `getNormals`, `getTexCoords`). There are helper methods like `hasNormalIndex` that help you determine if the vertex has a normal declared and `getNormal` that automatically locates the `OBJNormal` instance for you.\n\n\n## Loading MTL resources\n\nParsing material libraries is performed in the same way as objects. All one needs to do is instantiate an `MTLParser` and pass it an `InputStream` to the MTL resource.\n\n**Example:**\n\n```java\ntry (InputStream in = new FileInputStream(\"example.mtl\")) {\n  final IMTLParser parser = new MTLParser();\n  final MTLLibrary library = parser.parse(in);\n  for (MTLMaterial material : library.getMaterials()) {\n  \tSystem.out.println(MessageFormat.format(\"Material with name `{0}`.\", material.getName()));\n  }  \n}\n```\n\nThe `MTLMaterial` object represents a material that is defined in the MTL resource. There can be a number of these defined in a single MTL resource. Each of these has a name and some generic material data like diffuse color, ambient color, specular color, etc.\n\n**Example:**\n\n```java\nfinal MTLMaterial material = ...;\nfinal MTLColor diffuseColor = material.getDiffuseColor();\nfinal MTLColor ambientColor = material.getAmbientColor();\nfinal MTLColor specularColor = material.getSpecularColor();\n```\n\nOne would rarely parse MTL files separately. Often, this would be as part of the parsing of an OBJ file.\n\n**Example:**\n\n```java\nfinal IOBJParser objParser = new OBJParser();\nfinal IMTLParser mtlParser = new MTLParser();\n\nfinal InputStream objStream = ...; // Depends on your use case.\nfinal OBJModel model = objParser.parse(objStream);\nfor (String libraryReference : model.getMaterialLibraries()) {\n\tfinal InputStream mtlStream = ...; // You will need to resolve this based on `libraryReference` and the storage used\n    final MTLLibrary library = mtlParser.parse(mtlStream);\n    // Do something with the library. Maybe store it in a map for later usage.\n}\n```\n\n## Setting Up\n\nEven though this project relies on Maven for packaging, it has not been published to the central Maven repository. Following are a number of approaches to get the library imported in your project.\n\n### JitPack\n\nAn amazing web page that allows one to import Maven projects directly from GitHub. It is ideal for publishing new and small projects like this one.\nOne only needs to add the following configuration in their `pom.xml` file to get the library included.\n\n```xml\n\u003crepositories\u003e\n\t\u003crepository\u003e\n\t\t\u003cid\u003ejitpack.io\u003c/id\u003e\n\t\t\u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n\t\u003c/repository\u003e\n\u003c/repositories\u003e\n\n\u003cdependencies\u003e\n\t\u003cdependency\u003e\n\t\t\u003cgroupId\u003ecom.github.mokiat\u003c/groupId\u003e\n\t\t\u003cartifactId\u003ejava-data-front\u003c/artifactId\u003e\n\t\t\u003cversion\u003ev2.0.1\u003c/version\u003e\n\t\u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nJitPack works with other packaging frameworks as well. Check the [official webpage](https://jitpack.io/) for more information.\n\n### Packaging\n\nIf `JitPack` is not an option for your use case, then you could package the `jar` files into your project. They are available for download from the [Releases](https://github.com/mokiat/java-data-front/releases) section of the repository.\n\n\n### Local Maven repository\n\nYou can use a set of commands to import the `jar` files into your local Maven repository. Following are two available approaches. (I find the first one to do the job)\n\n* [http://maven.apache.org/plugins/maven-install-plugin/examples/custom-pom-installation.html](http://maven.apache.org/plugins/maven-install-plugin/examples/custom-pom-installation.html)\n* [http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html](http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html)\n\n## License\n\nThe source code is provided to you under the license in `LICENSE` file.\n\nThe documents in the `documents` folder, however, are not released under this license. These documents are not my ownership and have been copy-pasted from sources on the internet. They are specifications that were used to guarantee the correctness of the API. Since it is difficult to find an official specification, these resources have been added to the repository for locking in the specification.\n\nThese documents are not a fundamental part of the source code and are not included in the final binary, so most likely they should not be an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmokiat%2Fjava-data-front","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmokiat%2Fjava-data-front","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmokiat%2Fjava-data-front/lists"}