# iRacing custom paint: guide for your AI helper

Put this file in your project folder, next to your photos and design files, then start Claude Code in that folder. Claude Code reads the CLAUDE.md in the folder you start it in at the start of every session. Using a different AI helper? Ask it to read this file first.

## The goal

Make a custom paint for a car in iRacing so the 3D car matches a real race car, built from photos of the real car and, when you have them, the wrap shop's design files. This was worked out on iRacing's Dirt Street Stock. The method works for any iRacing car; the measured map below is for the Dirt Street Stock only.

## The file iRacing loads

- One flat picture of the whole car, 2048 x 2048 (iRacing also takes 1024 x 1024 for cars).
- TGA, 24 bit (no alpha channel), with RLE compression on. A 32 bit file can make the car show up all black.
- Name: `car_<customer ID>.tga`. The customer ID is in iRacing: click the helmet at the top right, then Profile; the number is at the top.
- Own painted number: save the same picture again as `car_num_<customer ID>.tga`. iRacing then uses it without stamping its own number.
- Folder: `Documents\iRacing\paint\<car folder>\` (Dirt Street Stock: `dirtstreetstock`). iRacing makes the car folder the first time you run that car in a test or race session. If Windows keeps Documents in OneDrive, the folder is under `OneDrive\Documents\iRacing\paint\`.
- Only you see a file on your own PC. Other drivers see it through Trading Paints: upload it there, and drivers who run the Trading Paints Downloader see it.

## Checking it

- iRacing Paint Shop: in the iRacing app, click Paint in the far left column (or My Content, then its Paint Shop tab). Pick the car, then under Model Options turn on Show Custom Paint. Drag to spin the car, scroll to zoom.
- The Paint Shop picks up a file saved again under the same name. If the 3D view goes blank after a new file lands, move the camera a little.
- In a test session, Ctrl+R reloads paints. It does not reload a car sitting in its pit stall.
- Check every version from every side AND from above, next to photos of the real car.
- If you cannot see the iRacing PC yourself, ask the human for screenshots of the Paint Shop (every side and from above) after each version, and compare them with the photos before changing anything.

## The template

- Get it inside iRacing: Paint (far left column) opens the Paint Shop; then Model Options, Download Template (iRacing's help page also lists My Content, Car Manager, Download Template). The Dirt Street Stock gives `Dirt Street Stock.psd`, 2048 x 2048.
- The layer folder "Turn Off Before Exporting TGA" holds guides only: Mask (shades what is not body), Wire (panel edges), Number Blocks, Sponsor Blocks. Use them while working; hide the folder before export.
- `base` (inside Color Change) is the body color. Car Patterns holds 24 optional patterns, hidden. The parts layers (Rollbars, Cockpit Panels, Mudplugs, Foam Air Breather Cover and others) are parts that are not body. Custom Spec Map is a separate shine file; skip it.
- In Python, read the PSD with `psd-tools` and render Mask and Wire to PNG files to see every island of the layout.

## Map of the Dirt Street Stock

Measured on the 3D car while building three cars. Numbers are template pixels (x from the left edge, y from the top). Confirm them with your own label test; they tell you where to look first.

- Bottom strip, about y 1650 to 2048: the RIGHT side, right side up. Front of the car at the right end (about x 1700), rear at the left (about x 100).
  - Wheel openings: rear about x 275 to 590, front about x 1262 to 1590.
  - Above the front wheel, the body is only about 50 to 56 px tall. Names there can be long but not tall.
  - Corners: art behind about x 135 or past about x 1665 wraps around the corner and disappears.
- Middle strip, about y 675 to 1073: the LEFT side, UPSIDE DOWN. Build the left side right side up first (an 1800 x 398 canvas with the front at its left end), rotate it 180 degrees, and paste it at x 0, y 675. The x numbers above then apply here too.
- Top view band, about y 1050 to 1700: rear of the car at the left, front at the right, the car's LEFT side toward the top of the file.
  - Trunk lid about x 18 to 286. Roof about x 492 to 998, y 1102 to 1620. A thin strip along the roof's front edge about x 1020 to 1064 (a banner fits there). Windshield screen about x 1100 to 1200. Hood about x 1212 to 1842.
  - The air cleaner sticks up through the hood at about x 1386 to 1547, y 1311 to 1472. Anything painted there is hidden.
  - The strip just above each door window: left side about y 1112 to 1135, right side about y 1585 to 1609 (a driver name fits there).
- Top of the file: the back of the car. Back panel about x 975 to 1580, y 195 to 405. The sloped panel between the roof and the trunk lid about x 570 to 916, y 34 to 671.
- The headlights sit in the parts layer at about x 1145, y 1110 and y 1601.
- On the 3D car, side art looks narrower than in the flat file (about 1.6 times on the front fender sides). Widen side names a little.

## Method that worked

1. Label test before anything else: big words (RIGHT FRONT, LEFT REAR, ROOF FRONT, BACK) on each island, export, and look on the car. Then colored bands or a numbered grid to pin exact rows.
2. Gather sources: the wrap shop's design files first (sharpest), photos of each side shot as straight on as possible, and any photo from above and from behind. Check every design file against photos of THIS car before using it.
3. Sides: warp each photo or design side onto its strip, landmark to landmark: rear end, rear wheel opening edges, front wheel opening edges, front end. Use three control lines (belt line, wheel arch tops, rocker) and pin the arch tops to the model's, because the model's fender is shorter above the wheel than a real car's.
4. Roof, hood and trunk: warp each panel's four corners from the design file onto its island (a perspective warp).
5. Logos: cut them from the design files (OpenCV GrabCut or a color key), find each one's spot (template matching), and keep its own shape. A logo too small or too blurry to scale up gets typed again in a matching font. Draw a custom race number as clean shapes.
6. Colors: pull the print colors to one body color so every panel matches.
7. Export, copy into the paint folder, check every side and from above, compare with the photos, fix, repeat. Keep every version (v1, v2, and so on) with a one line note of what changed.

## Tools

Python 3 and these libraries:

```
pip install pillow numpy scipy opencv-python psd-tools
```

- Pillow: images, and the TGA export: `img.convert('RGB').save('car_123456.tga', compression='tga_rle')`
- NumPy and SciPy (ndimage): masks, distances, labels
- OpenCV: GrabCut cutouts, inpainting old letters away, template matching
- `psd-tools`: reading the template's layers

## Traps we hit

- Sides swapped: the bottom strip is the RIGHT side, and the left side goes in upside down.
- Names copied from photos come out soft. Design files beat photos.
- The front fender above the wheel is short. A long name stretched to the photo's size gets flattened; keep each decal's own shape.
- Anything under the hood's air cleaner is hidden.
- An all black car: a 32 bit TGA, or the "2048 paint textures" option off in iRacing's graphics settings (turn it on and restart iRacing).
- After a new file lands, the Paint Shop's 3D view can go blank until the camera moves.
- Copying `car_num_` can fail once while iRacing has the file open. Try again.
- Text on a panel reads correctly from one direction only. Decide which way each panel reads (the trunk from behind, the roof from the side) and check it on the car.

## Starter message

Read CLAUDE.md first. I want my <car> in iRacing to look like my real race car. My photos are in ./photos and the wrap shop's files are in ./design. Start with a label test so we know which part of the template is which part of the car. After each version, save car_<my customer ID>.tga into my iRacing paint folder and tell me what to check in the Paint Shop.
