Render pitcher by-pitch location plots

src/baseball-charts.js

@@ -624,6 +624,9 @@ export async function createPitcherArsenalChartPng(payload = {}) {
 }
 
 export async function createPitcherLocationChartPng(payload = {}) {
+  if (payload.view === 'bypitch' && Array.isArray(payload.plotPoints)) {
+    return createPitcherLocationPlotPng(payload);
+  }
   const width = payload.width ?? 1080;
   const height = payload.height ?? 760;
   const canvas = new Canvas(width, height);
@@ -731,6 +734,149 @@ export async function createPitcherLocationChartPng(payload = {}) {
   return canvas.toBuffer('png');
 }
 
+async function createPitcherLocationPlotPng(payload = {}) {
+  const width = payload.width ?? 1080;
+  const height = payload.height ?? 760;
+  const canvas = new Canvas(width, height);
+  const ctx = canvas.getContext('2d');
+
+  paintCanvasBackground(ctx, width, height, ['#081a1a', '#102432', '#1f2d3f']);
+  drawHeader(
+    ctx,
+    width,
+    payload.title ?? 'Pitch Location Plot',
+    payload.subtitle ?? 'Pitch locations by pitch type.',
+    PITCHER_COLORS.primary
+  );
+
+  const boardX = 46;
+  const boardY = 124;
+  const boardWidth = width - 92;
+  const boardHeight = height - 170;
+  drawPanel(ctx, boardX, boardY, boardWidth, boardHeight);
+
+  ctx.fillStyle = TEXT.title;
+  ctx.font = 'bold 24px sans-serif';
+  ctx.fillText(payload.pitcherName ?? 'Unknown Pitcher', boardX + 26, boardY + 44);
+  ctx.font = '18px sans-serif';
+  ctx.fillStyle = TEXT.subtitle;
+  ctx.fillText(payload.teamLine ?? '', boardX + 26, boardY + 74);
+
+  ctx.font = 'bold 18px sans-serif';
+  ctx.fillStyle = PITCHER_COLORS.primary;
+  ctx.fillText(`Pitch plot by offering | Sample: ${payload.sampleSize ?? 0} pitches`, boardX + 26, boardY + 106);
+
+  const plotX = boardX + 54;
+  const plotY = boardY + 148;
+  const plotWidth = 430;
+  const plotHeight = 500;
+  drawPanel(ctx, plotX, plotY, plotWidth, plotHeight, 18);
+
+  const strikeZone = {
+    left: plotX + 120,
+    top: plotY + 92,
+    width: 190,
+    height: 220,
+  };
+
+  ctx.strokeStyle = 'rgba(255,255,255,0.45)';
+  ctx.lineWidth = 2;
+  ctx.strokeRect(strikeZone.left, strikeZone.top, strikeZone.width, strikeZone.height);
+  ctx.beginPath();
+  ctx.moveTo(strikeZone.left + strikeZone.width / 3, strikeZone.top);
+  ctx.lineTo(strikeZone.left + strikeZone.width / 3, strikeZone.top + strikeZone.height);
+  ctx.moveTo(strikeZone.left + (2 * strikeZone.width) / 3, strikeZone.top);
+  ctx.lineTo(strikeZone.left + (2 * strikeZone.width) / 3, strikeZone.top + strikeZone.height);
+  ctx.moveTo(strikeZone.left, strikeZone.top + strikeZone.height / 3);
+  ctx.lineTo(strikeZone.left + strikeZone.width, strikeZone.top + strikeZone.height / 3);
+  ctx.moveTo(strikeZone.left, strikeZone.top + (2 * strikeZone.height) / 3);
+  ctx.lineTo(strikeZone.left + strikeZone.width, strikeZone.top + (2 * strikeZone.height) / 3);
+  ctx.stroke();
+
+  ctx.strokeStyle = 'rgba(148, 163, 184, 0.25)';
+  ctx.lineWidth = 1;
+  ctx.strokeRect(plotX + 70, plotY + 40, plotWidth - 140, plotHeight - 110);
+
+  const pitchPalette = ['#22c55e', '#38bdf8', '#f59e0b', '#f97316', '#c084fc', '#f43f5e'];
+  const pitchColors = new Map();
+  const orderedPitches = (payload.pitchBreakdown ?? []).map((item) => item.pitchName);
+  orderedPitches.forEach((pitchName, index) => {
+    pitchColors.set(pitchName, pitchPalette[index % pitchPalette.length]);
+  });
+
+  const leftBound = -2.0;
+  const rightBound = 2.0;
+  const topBound = 4.8;
+  const bottomBound = 0.8;
+
+  for (const point of payload.plotPoints ?? []) {
+    const x = numberOrZero(point.x);
+    const y = numberOrZero(point.y);
+    const px = plotX + 70 + ((x - leftBound) / (rightBound - leftBound)) * (plotWidth - 140);
+    const py = plotY + 40 + ((topBound - y) / (topBound - bottomBound)) * (plotHeight - 110);
+    ctx.fillStyle = pitchColors.get(point.pitchName) ?? '#ffffff';
+    ctx.globalAlpha = 0.72;
+    ctx.beginPath();
+    ctx.arc(px, py, 4.6, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  ctx.globalAlpha = 1;
+
+  ctx.fillStyle = TEXT.muted;
+  ctx.font = '13px sans-serif';
+  ctx.fillText('Glove side', plotX + 72, plotY + plotHeight - 28);
+  ctx.fillText('Arm side', plotX + plotWidth - 126, plotY + plotHeight - 28);
+  ctx.fillText('Up', plotX + plotWidth - 34, plotY + 54);
+  ctx.fillText('Down', plotX + plotWidth - 50, plotY + plotHeight - 72);
+
+  const notesX = plotX + plotWidth + 28;
+  const notesWidth = boardX + boardWidth - notesX - 28;
+  drawMiniSummary(
+    ctx,
+    notesX,
+    plotY,
+    notesWidth,
+    122,
+    'How To Read',
+    'Each dot is one pitch at its plate location. Colors identify pitch types so you can see how the arsenal is spread in and around the zone.'
+  );
+  drawMiniSummary(
+    ctx,
+    notesX,
+    plotY + 144,
+    notesWidth,
+    170,
+    'Pitch Mix',
+    (payload.pitchBreakdown ?? []).length
+      ? payload.pitchBreakdown.map((item) => `${item.pitchName}: ${item.count} pitches (${item.pct.toFixed(0)}%)`).join(' | ')
+      : 'No pitch mix summary available.'
+  );
+  drawMiniSummary(
+    ctx,
+    notesX,
+    plotY + 336,
+    notesWidth,
+    122,
+    'Read',
+    payload.read ?? 'This chart shows where each pitch type actually finishes at the plate.'
+  );
+
+  let legendY = plotY + 16;
+  for (const item of (payload.pitchBreakdown ?? []).slice(0, 6)) {
+    const color = pitchColors.get(item.pitchName) ?? '#ffffff';
+    ctx.fillStyle = color;
+    ctx.beginPath();
+    ctx.arc(notesX + 18, legendY, 6, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.fillStyle = TEXT.subtitle;
+    ctx.font = '14px sans-serif';
+    ctx.fillText(item.pitchName, notesX + 34, legendY + 4);
+    legendY += 24;
+  }
+
+  return canvas.toBuffer('png');
+}
+
 export async function createPitcherApproachChartPng(payload = {}) {
   const labels = payload.labels?.length ? payload.labels : ['No Data'];
   const datasets = payload.datasets?.length

src/matchups.js

@@ -1414,6 +1414,8 @@ function pitcherLocationTitle(view) {
 
 function pitcherLocationRead(view) {
   switch (view) {
+    case 'bypitch':
+      return 'Each dot is a pitch. Colors separate pitch types so you can see where each offering lives.';
     case 'damage':
       return 'Hotter cells flag where contact quality has done the most damage.';
     case 'miss':
@@ -1613,6 +1615,36 @@ function locationMetricSuffix(view) {
   return '%';
 }
 
+function buildPitchLocationPlot(rows) {
+  const counts = new Map();
+  const points = rows
+    .filter((row) => numberOrNull(row.plate_x) !== null && numberOrNull(row.plate_z) !== null)
+    .slice(0, 600)
+    .map((row) => {
+      const pitchName = firstNonBlankValue(row.pitch_name, row.pitch_type, 'Unknown');
+      counts.set(pitchName, (counts.get(pitchName) ?? 0) + 1);
+      return {
+        x: numberOrNull(row.plate_x) ?? 0,
+        y: numberOrNull(row.plate_z) ?? 0,
+        pitchName,
+      };
+    });
+
+  const breakdown = [...counts.entries()]
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, 5)
+    .map(([pitchName, count]) => ({
+      pitchName,
+      count,
+      pct: points.length ? (count / points.length) * 100 : 0,
+    }));
+
+  return {
+    points,
+    breakdown,
+  };
+}
+
 function buildPitcherApproachDatasets(rows, view) {
   const buckets = view === 'ahead_behind'
     ? ['ahead', 'even', 'behind']
@@ -3469,6 +3501,25 @@ export class MatchupService {
       if (!filtered.length) {
         throw new Error(`No location rows matched the ${countBucketLabel(countBucket).toLowerCase()} filter for ${context.pitcherName}.`);
       }
+      if (view === 'bypitch') {
+        const plot = buildPitchLocationPlot(filtered);
+        if (!plot.points.length) {
+          throw new Error(`No pitch plot points were available for ${context.pitcherName}.`);
+        }
+        return {
+          ...context,
+          view,
+          split,
+          pitchType,
+          countBucket,
+          title: `${pitcherLocationTitle(view)} - ${context.pitcherName}`,
+          subtitle: `${context.team ?? 'N/A'} | ${splitLabel(split)} | ${countBucketLabel(countBucket)}${pitchType ? ` | ${pitchType}` : ''}`,
+          sampleSize: filtered.length,
+          plotPoints: plot.points,
+          pitchBreakdown: plot.breakdown,
+          read: pitcherLocationRead(view),
+        };
+      }
       const cells = buildPitcherLocationCells(filtered, view);
       const bestCell = [...cells].sort((left, right) => compareNullableDescending(left.overlayValue, right.overlayValue))[0];
       return {