{"id":13732055,"url":"https://github.com/ingowald/pbrt-parser","last_synced_at":"2025-06-28T17:02:08.579Z","repository":{"id":34021277,"uuid":"37778945","full_name":"ingowald/pbrt-parser","owner":"ingowald","description":"A simple parser for the PBRT file format","archived":false,"fork":false,"pushed_at":"2022-10-30T01:17:20.000Z","size":1666,"stargazers_count":209,"open_issues_count":9,"forks_count":24,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-15T16:42:46.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","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/ingowald.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":"2015-06-20T17:33:31.000Z","updated_at":"2024-11-25T07:45:47.000Z","dependencies_parsed_at":"2023-01-15T04:00:30.838Z","dependency_job_id":null,"html_url":"https://github.com/ingowald/pbrt-parser","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ingowald/pbrt-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingowald%2Fpbrt-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingowald%2Fpbrt-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingowald%2Fpbrt-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingowald%2Fpbrt-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ingowald","download_url":"https://codeload.github.com/ingowald/pbrt-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ingowald%2Fpbrt-parser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262465655,"owners_count":23315633,"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":[],"created_at":"2024-08-03T02:01:45.010Z","updated_at":"2025-06-28T17:02:08.538Z","avatar_url":"https://github.com/ingowald.png","language":"C++","readme":"Note: If you're using this project to import models\nlike PBRT landscape and/or Disney Moana for some rendering research purposes,\nthen you'll almost certainly want to use my newer `miniScene`\nproject instead of this one. Have a look here: https://github.com/ingowald/miniScene\n\nPBRT-Parser (V1.1)\n==================\n\nThe goal of this project is to provide a free (apache-lincensed) open\nsource tool to easily (and quickly) load PBRT files (such as PBRT's\nown \"pbrt-v3-scenes\" test scenes, or Disney's Moana island model).\n\nIn particular it\n\n- contains both a purely syntatical as well as a more advanced\n  semantical parser (see below)\n\n- can parse the original (ie, ascii-) '.pbrt' files from pretty much\n  any pbrt file I could find.\n\n- comes with support for reading and writing the resulting pbrt scene\n  graph to a binary \".pbf\" format (.pbf = binary pbrt format) that is\n  *significantly* faster to read.  I.e., you can use the included\n  pbrt2pbf to convert to convert a ascii .pbrt file to a binary .pbf\n  file, which when loaded by an application will yield exactly the\n  same scene graph as parsing the original .pbrt file, just much\n  faster (for moana, that drops parsing time from 30ish minutes to\n  seconds!).\n\n\nA few screenshots:\n\n![ecosys.pbrt](doc/jpg/ecosys.jpg \"ecosys\")\n![landscape.pbrt](doc/jpg/landscape.jpg \"landscape\")\n![moana.pbrt](doc/jpg/moana.jpg \"moana island, as shown at Siggraph 2018, using a slightly older version of this parser\")\n\n\n# Contributors (in \"order of appearance\")\n\n- Ingo Wald\n- Fabio Pellacini (University of Rome)\n- Stefan Zellman (University of Cologne)\n- Will Usher\n- Nate Morrical\n- lots of other people, through suggestions, bug reports, etc ...\n\n\n# Release Notes\n\nV 2.4:\n\n\u003c\u003c\u003c\u003c\u003c\u003c\u003c HEAD\n- added point and spot light sources - can now parse villa-lights-on\n=======\n- major bugfixes; changed attribute handling, can not properly parse area lights again\n\u003e\u003e\u003e\u003e\u003e\u003e\u003e devel\n\nV 2.3:\n\n- added 'hair' shape (can now parse pbrt v3 hair files)\n- removed all DLL build for windows; now using only static libraries on windows\n  (this avoids windows issues with passing std::string etc through dll boundaries)\n\nV 2.2:\n\n- have first area light sources (distant and infinite)\n- added reverseorientation\n- added InfiniteLight::{nsamples,L,scale}\n\nV 2.1.4: Various bugfixes:\n\n- textures now have 'name' field, which now gets read and written to/from binary\n- fixed core dump when reading/writing spectrum values in pbfs.\n- bumped binary file format to v1.0 (due to changes in format)\n\nV 2.1:\n\n- added semantic parsing of 'AreaLights', which are now attached to\n  shapes, and stored to/loaded from PBF files.\n\n- significant cleanup of semantic parser: SemanticParser is now a\n  separate class in a sepa rate header file, with all texture-,\n  mateiral-, geometry-, etc based parsing in separate implementation\n  files. Also, the single giant \"parseMaterial\" etc have been split\n  into type-specific parse functions (eg, parseMaterial_disney vs\n  parsematieral_mix, etc), further increasing readability.\n\nV 2.0:\n\n- amalgamated all *public* API into a single header file\n  (include/pbrtParser/Scene.h) that now only contains the fully\n  semantically parsed Scene. All intermediary syntax-only parsing is\n  now hidden in the impl/ directory, is no longer installed, and is no\n  longer exported as a separate library. From now on, only a single\n  library with a single header files is required after install.\n\n# Status\n\nThe *semantical* parser currently supports:\n\n- Shapes: `trianglemesh`, `disk`, `sphere`, and 'curve' are supported.\n- Materials: `Disney`, `Uber`, `Mix`, `Metal`, `Mirror`, `Matte`, `Translucent`, `Plastic`, `Substrate`, `Fourier`, and `Glass` should all work. In particular, all indirect references (e.g., a \"mix\" material referencing two other materials by name) are now properly resolved.\n- Textures: `Image`, `PtexFile` (storing only the filename, not the ptx data), `Fbm`, `Windy`, `Marble`, `Scale`, `Wrinkled`, `Mix`, and `Constant`. As with materials, all indirect references should be fully recognized.\n- File formats\n  - `.pbrt` : the original pbrt file format - slow to parse, but will work\n  - `.pbf`  : our own binary file format (use `pbrt2pbf` to convert ascii pbrt to binary pbf)\n\nDisclaimer(s): I did do a significant amonut of testing to make sure that the\nparser can load all .pbrt files without complaining, and that the above classes will\nparse everything that's in those files .... BUT:\n\n- I may have missed some things - please let me know...\n\n- The parser _should_ parse all .pbrt files I could find, but there\n  will likely be other files that are valid PBRT files that the parser\n  would choke. If you find any, please let me know.\n\n- I do not currently have a fully PBRT compliant renderer, so cannot\n  test whether all the parsed data is actualy parsed\n  correctly. Generally triangle meshes, objects, instances,\n  transforms, material and texture types, mapping of\n  materials/textures etc to shapes, etc, should all work, but I can't\n  entirely vouch for all material properties or texture properties of\n  all material types.\n\n- I *will* parse auxiliary .ply files as part of the parsing process,\n  but will *not* parse texture formats, ptex, spectrum specs, etc. For\n  all such auxiliary files I'll include the file name, but leave it to\n  the app to load such files (else I'd require tons of external\n  dependencies)\n\n## Known Limitations\n\n- `loopsubdiv` shapes are still ignored.\n\n- `curve` is currently a single shape type; would make senes to split\n  into FlatCurve, CylinderCurve, etc.\n\n- some models use camera space for object definitions - this isn't supported yet.\n\n\n\n\n\n# A Brief History of this Project\n\nThis project started out as being mostly a toy project for my own use,\n_originally_ with the sole goal of being able to load PBRT's heavily\ninstanced models (ecosys, landcape, and sanmiguel) for some ray\ntracing/instancing research.\n\nSince then, it's come a long way, and has pretty much become my method\nof choice for getting content into my various ray tracing projects:\nFirst, with more powerful hardware around it's now more practical to\nhave good material data around for one's ray tracing research, and\nother than PBRT's models there's previous few freely available models\nwith anything other than OBJ Wavefront's material model. Second, last\nyear Disney released the Moana island in two file formats, one of\nwhich is PBRT - and since my original \"toy project\" already did _most_\nof what was required to load Moana I ended up spending some more time\non this, and bringing it to a state where I can use it for pretty much\nany PBRT model (including Moana, of course).\n\nFor those that have looked at this library in its early stages: it has\nchanged a lot! In its original form, it was a purely syntactical\nparser that did parse the transforms and object hierarchy, as well as\nexternal ply files for triangle meshes, but wouldn't go much beyond\nthat. Anytying else - materials, textures, lights, and even most\nShape-related stuff - wasn't parsed beyond pure \"name:value\" pairs\nthat you'd then have to parse interpret yourself to figure out, for\nexample, what exact kind of material it was, what it's name-value\npairs meant in actual material parameters, etc.\n\nSince then, after having had to realize myself that that wasn't enough\nI eventually went ahead and significantly extended this library to\nhave _both_ a purely syntactical _and_ a more advanced semantical\nparser that would also parse materials, textures, shapes, etc (see\nbelow), and eventually also added a binary file format to deal with,\nin particular, the egregious load times for the 40+GB Moana model (in\nbinary format this now takes only seconds rather than half an\nhour...).\n\nAt its current stage, the library _should_ be able to parse pretty\nmuch anything I could find in pbrt file format. If you find something\nit doesn't parse at all, let me know. That said, since I don't have a\nfully PBRT compliant renderer yet there will, by necessity, be several\nthings that I haven't tested at all. If you do find something that's\nobviously broken, let me know (and I'll gladly take pull requests,\ntoo!).\n\nSemantical vs Syntactical Parser\n================================\n\nWhen looking at parsers, they typically consist of two intermingled\nstages: pure syntax (e.g., regnozizing the word \"Shape\" as the\nbeginning of a shape definition) to full semantic (e.g., what a shape\nactually is, and how it behaves). For many formats, the boundary\nbetween those two extremes is \"a bit\" wishy-washy, with much of the\nsemantics requiring way more effort to understand than the pure\nsyntax. Arguably the most extreme format on that spectrum is XML,\nwhere the syntax itself only defines \"nodes\", \"attributes\", and\n\"content\", with *all* semantical meaning of what specific nodes or\nattributes actually mean left for the app to figure out.\n\nPBRT specifies _some_ more semantics in the format (e.g., the file\nformat itself specifies that a Shape is different from a Material),\nbut still leaves a lot to be figured out afterwards. For example, in\nterms of pure syntax a triangle mesh and a sphere are both \"shapes\"\nthat just differ in what parameters got attached to that shape. That\nmakes the format easy to extend (you could add a new geometry type of\nmaterial type to PBRT without changing the file format at all!), but\nleaves more work for the app to figure our what certain name:value\npairs actually meant.\n\nInitially, this project only focussed on the syntax, and left all\ninterpretation of name:value pairs to the application. This however\ncan be rather tricky, and after I wrote that \"name:value\ninterpretation code\" multiple times in multiple project I eventually\ndecided to put that into this library as well, resulting in both a\npurely syntactical, as well as a more ready-to-use semantical parser.\n\nTo explain the difference: In the *syntactical* parser, for a given\ntriangle mesh you'd end with a C++ class of type \"Shape\" that would\nhave a parameter \"name\" with type \"string\", a size of 1, and a value\nof [ \"trianglemesh\" ], as well as a pamameter \"P\" with type \"float\", a\nsize of 3*N, and a value of [ x0 y0 z0 x1 .... zN ] .... but it'd have\nto be the application that has to figure out that this is a triangle\nmesh with a vertex array. In the *semantical* parser (which of course\nbuilds on top of the syntactical parser as an intermediary parsing\nstep) you will instead end up with a class \"TriangleMesh\" that has a\nC++ class member of \"std::vector\u003cvec3f\u003e position\", etc. Similarly for\nmaterials: The syntactical parser only tells you that there _is_ a\nmaterial with a string specifying, for example, the type \"disney\", and\na list of parameters; while the semantical parser would parse this\ndown to a C++ \"DisneyMaterial\" class, with C++ members for the\nmaterial parameters, etc.\n\n\nLICENSE\n=======\n\nThis project comes with Apache 2.0 license - pretty much \"use as you see fit\".\n\n\nUSAGE\n=====\n\nFor examples usages, see the simply tools (e.g., pbrtInfo or pbfInfo)\nin the apps directory.\n\nSuggested use is with CMake, in which form you can use it in either\none of two ways:\n\nOption 1: Make Install\n----------------------\n\nBuild the project with cmake, and \"make install\" to a\ninstall directory. Once installed (say, to /usr/local)\n- In your source code, `include \"pbrtParser/semantic/Scene.h\"`\n- In your project, link to the `pbrtParser_semantic` library.\n\nOf course, this way you can use whatever build system you want to use.\n\nOption 2: Cmake with source-access\n----------------------------------\n\nIf you don't like the \"make install\" option, you can also include the\nfull source three, either as a complete copy of this project (ugh), or\n(preferred!) as a git submodule.\n\nAssuming you're building your main project with cmake, and assuming this parser\nis included in \u003cproject\u003e/external/pbrtParser (hint: `git submodule add https://github.com/ingowald/pbrtParser.git external/pbrtParser` ... just saying....):\n\n- in your CMakeLists.txt:\n\n   add_subdirectory(external/pbrtParser EXCLUDE_FROM_ALL)\n   include_directories(${CMAKE_PROJECT_SOURCE_DIR}/external/pbrtParser)\n   ...\n   target_link_libraries(\u003cmyProjects\u003e pbrtParser_semantic)\n\n- in your source file:\n\n   #include \"pbrtParser/semantic/Scene.h\"\n   ...\n   pbrt::semantic::Scene::SP scene = pbrt::semantic::Scene::loadFrom(fileName);\n   ...\n\n\nOptional: Use your own vector library\n-------------------------------------\n\nOne of the most common issues with using other peoples' C++ libraries\nin graphics is that - of course! - everybody wants to use their own\nfavorite libraries for math and vector operations.\n\nThis project internally uses a somewhat older copy of the \"ospcommon\"\nlibrary that comes with the ospray project; however, to avoid some of\nthe otherwise common naming clashes all of this is hidden within the\nactual parser and lexer implementation, and the publicly visible\ninterface in semantic/Scene.h uses simple, plain-C structs that only\nspecify the data _layout_ of the vec3f, vec4i, etc classes.\n\nAs such, if you want to use your own vector classes, there are two\nways of doing this:\n\n- Option 1: Add a default constructor to your own vector classes that\n  will be able to construct your own types from these plain-C classes.\n\n- Option 2: Assuming your own vector calsses *do* have the same data layout\n  as the ones that the parser expects, you can also do a\n\n   #define PBRT_PARSER_PARSER_VECTYPE_NAMESPACE myown::math\n   #include \u003cpbrtParser/semantic/Scene.h\u003e\n   \n  ... which will make your own code \"think\" that the parser was\n  actually using your own vector library. This is, of course, a bit\n  hacky, so use at your own risk.\n","funding_links":[],"categories":["Graphics"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingowald%2Fpbrt-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fingowald%2Fpbrt-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fingowald%2Fpbrt-parser/lists"}