@brandonlukas/luminar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Lukas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# luminar
+
+Looping particle-flow study inspired by the bloom-heavy look of [lumap](https://github.com/brandonlukas/lumap). It renders a 2D vector field using Three.js with additive particles and an Unreal Bloom pass; flow magnitude controls glow intensity.
+
+## Quick start
+
+Visualize a CSV field (columns: x, y, dx, dy; header optional) with zero install:
+
+```sh
+npx @brandonlukas/luminar path/to/field.csv
+```
+
+Optional flags: `--port 5173`, `--host 0.0.0.0`, `--preview` (uses production build)
+
+### Local development
+
+```sh
+npm install
+npm run dev
+```
+
+Or use the old script syntax:
+
+```sh
+npm run visualize:csv -- --file path/to/field.csv
+```
+The parser auto-detects and skips header rows if present. Use `--preview` to run against the built bundle instead of dev, and `--host 0.0.0.0` to expose on your network.
+
+Build for production:
+
+```sh
+npm run build
+```
+
+## How it works
+- Orthographic camera framing a square field with particles advected each frame.
+- Vector field defined in `sampleField` inside [src/main.ts](src/main.ts#L98-L110); edit to fit your data or dynamics.
+- Glow intensity maps to local speed; particles respawn when leaving the world bounds.
+- Unreal Bloom and additive blending preserve the luminous, hazy aesthetic.
+- On-canvas controls (top-right) adjust size, bloom strength, and bloom radius in real time.
+
+## Tweaks to try
+- Increase `PARTICLE_COUNT` or `FLOW_SCALE` in [src/main.ts](src/main.ts#L20-L24) for denser motion.
+- Adjust `WORLD_EXTENT` and `JITTER` to change containment and randomness.
+- Swap `sampleField` to consume your own `(x, y, dx, dy)` tuples; normalize magnitudes before applying `FLOW_SCALE` for stability.
+
+## Notes
+- The scene is non-interactive and loops continuously.
+- Fonts and overlay styling live in [src/style.css](src/style.css).

package/bin/luminar.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawn } from 'node:child_process'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const projectRoot = resolve(__dirname, '..')
+
+function parseArgs() {
+    const args = process.argv.slice(2)
+    const out = { file: null, port: 5173, host: '0.0.0.0', preview: false }
+
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i]
+        if (arg === '--port' || arg === '-p') {
+            out.port = Number(args[++i]) || out.port
+        } else if (arg === '--host') {
+            out.host = args[++i] || out.host
+        } else if (arg === '--preview') {
+            out.preview = true
+        } else if (!arg.startsWith('-') && !out.file) {
+            // First positional argument is the file
+            out.file = arg
+        }
+    }
+    return out
+}
+
+function parseCsv(text) {
+    const lines = text.split(/\r?\n/).filter(Boolean)
+    const rows = []
+    let skippedHeader = false
+    for (const line of lines) {
+        const parts = line.split(/[,\s]+/).filter(Boolean)
+        if (parts.length < 4) continue
+        const [x, y, dx, dy] = parts.map(Number)
+        if ([x, y, dx, dy].some((n) => Number.isNaN(n))) {
+            if (!skippedHeader && rows.length === 0) {
+                skippedHeader = true
+                console.log('skipping header line:', line.substring(0, 60))
+            }
+            continue
+        }
+        rows.push({ x, y, dx, dy })
+    }
+    return rows
+}
+
+function writeFieldJson(rows) {
+    const target = resolve(projectRoot, 'public', 'vector-field.json')
+    writeFileSync(target, JSON.stringify(rows, null, 2), 'utf8')
+    console.log(`wrote ${rows.length} vectors to ${target}`)
+}
+
+function runServer({ port, host, preview }) {
+    const cmd = 'npm'
+    const args = preview
+        ? ['run', 'build-and-preview', '--', '--host', host, '--port', String(port)]
+        : ['run', 'dev', '--', '--host', host, '--port', String(port)]
+    console.log(`starting ${preview ? 'preview' : 'dev'} server on http://${host}:${port}`)
+    const child = spawn(cmd, args, {
+        stdio: 'inherit',
+        cwd: projectRoot,
+        env: process.env,
+    })
+    child.on('exit', (code) => process.exit(code ?? 0))
+}
+
+function main() {
+    const { file, port, host, preview } = parseArgs()
+    if (!file) {
+        console.error('Usage: luminar <file.csv> [--port 5173] [--host 0.0.0.0] [--preview]')
+        console.error('Example: luminar data.csv')
+        process.exit(1)
+    }
+    const resolved = resolve(process.cwd(), file)
+    if (!existsSync(resolved)) {
+        console.error(`File not found: ${resolved}`)
+        process.exit(1)
+    }
+    const text = readFileSync(resolved, 'utf8')
+    const rows = parseCsv(text)
+    if (rows.length === 0) {
+        console.error('Parsed 0 rows; ensure CSV has x,y,dx,dy columns (header optional)')
+        process.exit(1)
+    }
+    writeFieldJson(rows)
+    runServer({ port, host, preview })
+}
+
+main()