Feature: Material Visualization
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Material Visualization feature allows users to photorealistically preview different driveway surfacing options—such as Hot Mix Asphalt, Asphalt Millings, Tar & Chip, and Gravel—directly on a photo of their property. This functionality is a core component of the Driveway Estimator Pro application, bridging the gap between raw measurements and final project expectations by using AI-powered image generation to modify the driveway surface while maintaining the original perspective and lighting.
Sources: README.md:10-14, server/routers/projects.ts:143-146
The system integrates frontend selection logic with backend AI services to produce high-fidelity previews that are stored in S3 and persisted in the database. These previews are then utilized in project summaries, shared contractor views, and PDF exports.
Sources: client/src/pages/Estimator.tsx:162-184, drizzle/schema.ts:56-57
Architecture and Data Flow
The visualization process follows a request-response cycle initiated from the client-side Estimator component. When a user selects a material and requests a preview, the application sends the original photo URL and material type to the generateMaterialPreview tRPC procedure.
The diagram shows the lifecycle of a material preview from initial request to persistent storage.
Sources: server/routers/projects.ts:124-184, client/src/pages/Estimator.tsx:162-184
Supported Materials
The system supports four primary driveway materials, each with unique density characteristics for quantity calculation and specific prompts for image generation.
| Material ID | Display Name | Visual Characteristics Prompt Fragment |
|---|---|---|
hotmix | Hot Mix Asphalt | "hot mix asphalt" |
millings | Asphalt Millings | "asphalt millings" |
tar_and_chip | Tar & Chip | "tar and chip" |
gravel | Gravel | "gravel" |
Sources: server/services/pricing.ts:4-5, server/routers/projects.ts:133-138, client/src/pages/SharedProject.tsx:21-26
Backend Implementation Details
Image Generation Logic
The backend uses a specialized prompt engineering approach to ensure the AI modifies only the driveway surface. The prompt explicitly instructs the generator to maintain perspective, lighting, and surroundings while applying the chosen material texture.
const prompt = `Take this driveway photo and generate a photorealistic preview showing what it would look like with ${materialNames[input.material]} applied. Keep the same perspective, lighting, and surroundings. Only modify the driveway surface itself.`;
Sources: server/routers/projects.ts:141-143
Storage and Persistence
Generated images are not stored temporarily. The server fetches the AI-generated result, converts it to a buffer, and uploads it to a specific S3 path (previews/{userId}/{nanoid}-preview.jpg) to ensure long-term availability for shared projects and PDF generation.
Sources: server/routers/projects.ts:154-165
Frontend Integration
The Estimator.tsx component manages the state for the visualization step, including loading states and UI transitions.
Preview Workflow
- Selection: Users select a material from a grid.
- Trigger: The
handleGeneratePreviewfunction invokes the mutation. - Display: Upon success, the
previewUrlis stored in the local state, and the UI transitions to the "preview" step.
The flow shows how visualization fits into the broader estimation wizard.
Sources: client/src/pages/Estimator.tsx:325-450, README.md:126-140
Component Visualization
The preview is rendered within a responsive container maintaining a 16:9 aspect ratio, consistent with the original photo capture to ensure the visual overlay appears accurate.
Sources: client/src/pages/Estimator.tsx:446-455, client/src/pages/SharedProject.tsx:114-123
Data Model
The visualization data is persisted in the projects table using the following fields:
| Field | Type | Description |
|---|---|---|
selectedMaterial | varchar(50) | The ID of the material chosen by the user. |
previewImageUrl | text | The public S3 URL of the AI-generated preview. |
previewImageKey | text | The S3 key for internal reference and management. |
Sources: drizzle/schema.ts:51-57
Conclusion
The Material Visualization feature serves as a critical decision-making tool in the project, transforming technical measurements into a visual reality. By leveraging AI to generate photorealistic previews and persisting those results through S3 and Drizzle ORM, the system provides users and contractors with a clear, shared vision of the final driveway appearance.
Sources: README.md:7-14, server/routers/projects.ts:316-320