Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

docs: add community contribution templates (#47)

TamL.e8225b2c477e
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..d72aa97
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,72 @@
+name: Bug report
+description: Report a reproducible problem in the img2threejs pipeline.
+title: "[Bug]: "
+labels: [bug]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thank you for helping improve img2threejs. Please remove or redact any private reference images, API keys, or other sensitive material before submitting.
+
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched existing issues and did not find a duplicate.
+ required: true
+ - label: I confirmed this is a reproducible behavior problem, not a request for help using the project.
+ required: true
+
+ - type: textarea
+ id: summary
+ attributes:
+ label: What happened?
+ description: State the observed behavior and the behavior you expected instead.
+ placeholder: The pipeline produced ...; I expected ...
+ validations:
+ required: true
+
+ - type: textarea
+ id: reproduction
+ attributes:
+ label: Reproduction steps
+ description: Provide the smallest sequence of commands and inputs that reproduces the problem.
+ placeholder: |
+ 1. From the skill root, run `...`
+ 2. Use this sanitized input or configuration: `...`
+ 3. Observe `...`
+ render: shell
+ validations:
+ required: true
+
+ - type: textarea
+ id: reference
+ attributes:
+ label: Reference image or input characteristics
+ description: Describe the subject, image dimensions, viewpoint, and any relevant visual characteristics. Attach a sanitized image or screenshot when sharing it is permitted.
+ placeholder: Hard-surface object, 2048×2048 PNG, three-quarter view, reflective finish.
+ validations:
+ required: true
+
+ - type: textarea
+ id: artifacts
+ attributes:
+ label: Relevant output and evidence
+ description: Include the relevant spec, generated-output excerpt, traceback, and/or render screenshots. Redact sensitive content.
+ render: text
+ validations:
+ required: false
+
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment
+ value: |
+ - img2threejs version or commit:
+ - Python version:
+ - Host agent (Claude Code, Codex, OpenCode, or other):
+ - Operating system:
+ render: markdown
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..226028c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,43 @@
+name: Feature request
+description: Propose a focused, code-only improvement to the img2threejs pipeline.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thank you for the idea. img2threejs prioritizes procedural, code-only reconstruction with observable quality gates. Please explain how the proposal supports that contract.
+
+ - type: checkboxes
+ id: checks
+ attributes:
+ label: Before submitting
+ options:
+ - label: I searched existing issues and did not find a duplicate.
+ required: true
+ - label: This proposal does not depend on silently downloading meshes or art packs.
+ required: true
+
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem to solve
+ description: Describe the user or pipeline problem, not just the proposed implementation.
+ validations:
+ required: true
+
+ - type: textarea
+ id: proposal
+ attributes:
+ label: Proposed outcome
+ description: Describe the observable behavior, acceptance criteria, and affected stage or documentation area if known.
+ validations:
+ required: true
+
+ - type: textarea
+ id: examples
+ attributes:
+ label: Reference examples or alternatives
+ description: Link examples, related issues, or describe alternatives you considered.
+ validations:
+ required: false
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..259fd35
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,28 @@
+<!--
+Thanks for contributing to img2threejs. Keep the pull request focused and remove instructional comments that do not apply before submitting.
+-->
+
+## Summary
+
+<!-- What behavior or documentation changes? Why is it needed? Link related issues with "Fixes #123" where applicable. -->
+
+## Changes
+
+<!-- List the key changes. -->
+
+-
+
+## Validation
+
+<!-- Record the checks you ran and their results. Include render/comparison-sheet evidence for changes that affect reconstruction quality. -->
+
+- [ ] `python3 forge/tests/test_pipeline.py`
+- [ ] Relevant targeted validation or test:
+- [ ] Render or comparison-sheet review, if applicable:
+
+## Contributor checklist
+
+- [ ] This PR keeps the code-only procedural reconstruction contract; it does not silently download meshes or art packs.
+- [ ] Existing object specs remain valid, or this PR documents the intentional compatibility change.
+- [ ] I added or updated tests for new gates, schema fields, or templates where applicable.
+- [ ] I updated documentation and roadmap status where applicable.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e8e2f6a..6b792d3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,11 +31,21 @@ explicit, flagged, opt-in mode.
- Keep changes backward compatible: existing object specs must continue to validate.
- No emojis in source, docs, or generated output.
+## Before you open an issue
+
+- Search existing issues first.
+- For a bug, include the reference image characteristics, the exact command, the relevant spec or generated output, expected versus actual behavior, and a render screenshot when it helps. Do not post private images, credentials, or other sensitive material.
+- For a proposal, describe the problem, the observable outcome, and how it preserves the project's code-only procedural reconstruction contract.
+- Use a discussion channel or another appropriate forum for usage questions when one is available; issues should be actionable bugs or focused proposals.
+
## Pull requests
- Keep PRs focused and describe the behavior change plus how you verified it.
- Add or update tests for new gates, schema fields, or templates.
- Update `docs/UPGRADE_PLAN.md` status when you land a roadmap item.
+- Link the issue with `Fixes #<number>` when applicable.
+- For changes that affect visual fidelity, include the relevant render or comparison-sheet evidence and the result of its review.
+- Do not include private reference images, credentials, or other sensitive material in the PR description, commits, or attachments.
## Reporting issues