{"id":28516768,"url":"https://github.com/mit-spark/threedfront","last_synced_at":"2026-04-24T23:34:22.183Z","repository":{"id":246281928,"uuid":"811558095","full_name":"MIT-SPARK/ThreedFront","owner":"MIT-SPARK","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-19T20:51:38.000Z","size":59439,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-09T04:15:50.665Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MIT-SPARK.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":"2024-06-06T20:41:43.000Z","updated_at":"2025-05-12T09:58:21.000Z","dependencies_parsed_at":"2025-01-03T07:37:52.678Z","dependency_job_id":null,"html_url":"https://github.com/MIT-SPARK/ThreedFront","commit_stats":null,"previous_names":["mit-spark/threedfront"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MIT-SPARK/ThreedFront","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIT-SPARK%2FThreedFront","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIT-SPARK%2FThreedFront/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIT-SPARK%2FThreedFront/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIT-SPARK%2FThreedFront/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MIT-SPARK","download_url":"https://codeload.github.com/MIT-SPARK/ThreedFront/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MIT-SPARK%2FThreedFront/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"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":[],"created_at":"2025-06-09T04:12:44.540Z","updated_at":"2026-04-24T23:34:22.171Z","avatar_url":"https://github.com/MIT-SPARK.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Threed-Front Dataset\n\u003cp\u003e\n    \u003cimg width=\"180\" alt=\"Example 1\" src=\"demo/example_gif/Bedroom-4098.gif\"/\u003e\n    \u003cimg width=\"180\" alt=\"Example 2\" src=\"demo/example_gif/LivingDiningRoom-37001.gif\"/\u003e\n    \u003cimg width=\"180\" alt=\"Example 3\" src=\"demo/example_gif/LivingDiningRoom-54997.gif\"/\u003e\n    \u003cimg width=\"180\" alt=\"Example 4\" src=\"demo/example_gif/DiningRoom-11628.gif\"/\u003e\n\u003c/p\u003e\n\nThis is developed as a part of [MiDiffusion](https://github.com/MIT-SPARK/MiDiffusion), a mixed diffusion model for 3D indoor scene synthesis.\nThis repository provides a standalone python package for dataset classes related to [3D-FRONT](https://tianchi.aliyun.com/specials/promotion/alibaba-3d-scene-dataset) and [3D-FUTURE](https://tianchi.aliyun.com/specials/promotion/alibaba-3d-future) datasets. We also include evaluation scripts for the 3D indoor scene synthesis problem.\n\nMost of the code is adapted from [ATISS](https://github.com/nv-tlabs/ATISS/). \nWe also incorporate features from [DiffuScene](https://github.com/tangjiapeng/DiffuScene/) so that the evaluation scripts are compatible with their setup. \nThe optional floor plan preprocessing script converting images to points is adapted from [LEGO-Net](https://github.com/QiuhongAnnaWei/LEGO-Net/).\nPlease refer to the \u003ca href=\"./external_licenses/\"\u003eexternal_licenses\u003c/a\u003e directory for their licensing information. \n\n## Installation\nWe list dependency versions in `requirements.txt`. The following dependencies are required:\n- [numpy](https://numpy.org/doc/stable/user/install.html)\n- [pillow](https://pillow.readthedocs.io/en/stable/installation.html)\n- [pyrr](https://pyrr.readthedocs.io/en/latest/index.html)\n- [pyyaml](https://pyyaml.org/wiki/PyYAMLDocumentation)\n- [PyTorch \u0026 Torchvision](https://pytorch.org/get-started/locally/)\n- [scipy](https://scipy.org/install/)\n- [tqdm](https://github.com/tqdm/tqdm)\n\nThese are required to process raw meshes and visualize the scenes:\n- [seaborn](https://seaborn.pydata.org/)\n- [simple-3dviz==0.7.0](https://simple-3dviz.com/)\n- [trimesh](https://github.com/mikedh/trimesh)\n- [opencv-python](https://opencv.org/get-started/) (optional, better than pillow in saving textured layouts to images)\n- [wxPython==4.1.0](https://wxpython.org/index.html) (optional, for simple-3dviz GUI)\n\nThese additional dependencies are required for evaluation:\n- [clean-fid](https://www.cs.cmu.edu/~clean-fid/) (optional, for FID and KID)\n- [shapely](https://shapely.readthedocs.io/en/stable/installation.html) (optional, for bounding box analysis)\n\n`pip install wxPython` might fail looking for a specific wheel and automatically switch to building from source. \nFor Linux, the easiest way to install wxPython is to use the pre-built wheels from https://extras.wxpython.org/wxPython4/extras/linux/. For example,\n```\npip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-20.04/wxPython-4.1.0-cp38-cp38-linux_x86_64.whl\n```\nTo use simple-3dviz on a remote ubuntu18 or ubuntu20 server, follow [this link](https://moderngl.readthedocs.io/en/5.6.2/the_guide/headless_ubunut18_server.html).\n\n## Data Preprocessing\nWe use the same dataset splits and data filtering method as [ATISS](https://github.com/nv-tlabs/ATISS/). The dataset files in `dataset_files/` are directly copied from [here](https://github.com/nv-tlabs/ATISS/tree/e643000de5990c2325653afa86174957f0f0e8de/config). Parsed and preprocessed data will be saved to an `output/` directory. The default output paths can be modified in `scripts/utils.py`.\n\n### Download the datasets\nYou need to first obtain the 3D-FRONT and the 3D-FUTURE datasets. To download both datasets, please follow the download instructions from [the official website](https://tianchi.aliyun.com/specials/promotion/alibaba-3d-scene-dataset). This repository is developed based on [this release](https://tianchi.aliyun.com/dataset/65347). \n\n### Parse 3D-FRONT\nFirst, use `pickle_threed_front_dataset.py` to pickle a list of `Room` objects to `threed_front.pkl`:\n```\npython scripts/pickle_threed_front_dataset.py \u003cdataset_dir\u003e/3D-FRONT/3D-FRONT \u003cdataset_dir\u003e/3D-FUTURE/3D-FUTURE-model \u003cdataset_dir\u003e/3D-FUTURE/3D-FUTURE-model/model_info.json\n```\nThis script will save the parsed rooms to `output/threed_front.pkl` by default.\n\n### Parse 3D-FUTURE by room types\nUse `pickle_threed_future_dataset.py` to pickle a `ThreedFutureDataset` object which contains a list of `ThreedFutureModel` (furnitures in the training set of the specified room type) to `threed_future_model_\u003croom_type\u003e.pkl`:\n```\npython scripts/pickle_threed_future_dataset.py threed_front_\u003croom_type\u003e\n```\nThis script will save the parsed dataset to `output/threed_future_model_\u003croom_type\u003e.pkl` by default. \n\n### Preprocess 3D-FRONT by room types\nUse `preprocess_data.py` to extract and save basic object encoding (`boxes.npz`), floor plan (`room_mask.png`), and top-down projection of the layout (`rendered_scene_256.png`) for each scene to a separate subdirectory: \n```\npython scripts/preprocess_data.py threed_front_\u003croom_type\u003e\n```\nBy default, the results are saved to `output/3d_front_processed/\u003croom_type\u003e` with each sub-directory named as the UID of that scene.\nNote that texture (`--no_texture`) and floor plan (`--without_floor`) options will result in different rendered image names.\nThis means you can run this script multiple times and save multiple layout images to each sub-directory by allowing to overwrite when prompted (choose option 1 to save/overwrite rendered images without changing other files).\nIf you want to use point cloud embeddings as an additional object feature, please refer to the [DiffuScene repository](https://github.com/tangjiapeng/DiffuScene/).\n\n### (Optional) Sample floor plan boundary\nInstead of a binary mask, the floor plan can also be represented as sampled 2D points and normals along the boundary. Use `preprocess_floorplan.py` to add these features to each scene data (`boxes.npz`). \n```\npython scripts/preprocess_floorplan.py output/3d_front_processed/\u003croom_type\u003e --room_side \u003croom_side\u003e\n```\nYou need to make sure `--room_side` is set close to the value used to generate `room_mask.png` in the data directory. By default, this script samples 256 points per room. You can adjust this using the `--n_sampled_points` argument.\n\n### Render scenes\nTo render ground-truth scenes, you can run `render_threedfront_scene.py` with a scene ID (e.g., Bedroom-4098):\n```\npython scripts/render_threedfront_scene.py \u003cscene_id\u003e\n```\nPlease read the script for visualization options.\n\n## Evaluation\nYou can `pip install` this package as a dependency for your own project. \nFor evaluation, you need to save the generated results as a `ThreedFrontResults` object (see `threed_front/evaluation/__init__.py`) and pickle it to a file (e.g., `results.pkl`). Our [MiDiffusion repository](https://github.com/MIT-SPARK/MiDiffusion) contains an example script (`scripts/generate_results.py`). \nThen you can render results to top-down projection images in the same way as it is done for ground-truth layouts in the preprocessing step:\n```\npython scripts/render_results.py \u003cresult_file\u003e\n```\nBy default, the rendered images will be saved to the same directory as the result file. Please read the script for visualization options.\n\nOur evaluation scripts include:\n- `evaluate_kl_divergence_object_category.py`: Compute **KL-divergence** between ground-truth and synthesized object category distributions.\n- `compute_fid_scores.py`: Compute average **FID** or **KID** (if run with \"--compute_kid\" flag) between ground-truth and synthesized layout images.\n- `synthetic_vs_real_classifier.py`: Train image classifier to distinguish real and synthetic projection images, and compute average **classification accuracy**.\n- `bbox_analysis.py`: Count the number of **out-of-boundary** object bounding boxes and compute pairwise bounding boxes **IoU** (this requires sampled floor plan boundary and normal points).\n\nMost evaluation scripts can be run by simply providing the path to the pickled result file. For image comparisons, make sure you set the `--no_texture` flag when comparing textureless synthetic layouts with the ground-truth.\n\n## Code organization\nThe dependency relationships in `threed_front/datasets`: \n```\n__init__.py\n├── base.py\n├── common.py\n├── splits_builder.py\n├── threed_front.py\n│   └── parse_utils.py\n│       └── threed_front_scene.py\n└── threed_future_dataset.py\nthreed_front_encoding_base.py\n```\nThe `__init__.py` contains all dataset classes/functions to read and host preprocessed scene data, \nincluding `CachedThreedFront` which loads data from `output/3d_front_processed/\u003croom_type\u003e`. \nThe `threed_front_encoding_base.py` stores other feature encoding and dataset augmentation classes for training.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmit-spark%2Fthreedfront","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmit-spark%2Fthreedfront","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmit-spark%2Fthreedfront/lists"}