diff --git a/packages/bake/authoring/ngc-3132/grid-fit.mts b/packages/bake/authoring/ngc-3132/grid-fit.mts
index 638dd4f9b33..5830fe02da5 100644
--- a/packages/bake/authoring/ngc-3132/grid-fit.mts
+++ b/packages/bake/authoring/ngc-3132/grid-fit.mts
@@ -59,10 +59,10 @@ const file = await readFile(resolve(sourceDirectory, 'source.jpg')), tags = file
const tag = (name: string) => { const found = new RegExp(`([\\s\\S]*?)`, 'u').exec(tags) ?? new RegExp(`avm:${name}="([^"]*)"`, 'u').exec(tags); if (!found) throw new Error(`source.jpg has no avm:${name}.`); return found[1]!.replace(/<[^>]+>/gu, ' ').trim().split(/\s+/u).map(Number); };
const pixelArcsec = Math.abs(tag('Spatial.Scale')[0]!) * 3600, rotation = tag('Spatial.Rotation')[0]! * rad;
const full = await sharp(file).removeAlpha().raw().toBuffer({ resolveWithObject: true }), fullWidth = full.info.width, fullHeight = full.info.height;
-// Where the tags alone put the star: the recipe's target, from the tags' reference place and pixel (counted from the bottom).
+// Where the tags alone put the star: the recipe's target, from the tags' reference place and pixel (counted from the bottom left, the first pixel's middle at 1, as FITS counts).
const target = (JSON.parse(await readFile(resolve(sourceDirectory, 'recipe.json'), 'utf8')) as { target: { centerRaDeg: number; centerDecDeg: number } }).target, reference = tag('Spatial.ReferenceValue'), referencePixel = tag('Spatial.ReferencePixel'), degrees = Math.abs(tag('Spatial.Scale')[0]!);
const eastPixels = (target.centerRaDeg - reference[0]!) * Math.cos(target.centerDecDeg * rad) / degrees, northPixels = (target.centerDecDeg - reference[1]!) / degrees;
-const tagged = [referencePixel[0]! - eastPixels * Math.cos(rotation) - northPixels * Math.sin(rotation), fullHeight - (referencePixel[1]! - eastPixels * Math.sin(rotation) + northPixels * Math.cos(rotation))] as const, within = Math.round(STAR_WITHIN_ARCSEC / pixelArcsec);
+const tagged = [referencePixel[0]! - 1 - eastPixels * Math.cos(rotation) - northPixels * Math.sin(rotation), fullHeight - (referencePixel[1]! - eastPixels * Math.sin(rotation) + northPixels * Math.cos(rotation))] as const, within = Math.round(STAR_WITHIN_ARCSEC / pixelArcsec);
// The star: the largest patch of saturated pixels that starts within that reach of the place.
const saturated = (p: number) => full.data[3 * p]! >= 250 && full.data[3 * p + 1]! >= 250 && full.data[3 * p + 2]! >= 250, seen = new Uint8Array(fullWidth * fullHeight); let star = { pixels: 0, x: 0, y: 0, from: 0 };
for (let y = Math.max(0, Math.round(tagged[1] - within)); y <= Math.min(fullHeight - 1, tagged[1] + within); y++) for (let x = Math.max(0, Math.round(tagged[0] - within)); x <= Math.min(fullWidth - 1, tagged[0] + within); x++) { const start = y * fullWidth + x; if (seen[start] || !saturated(start) || Math.hypot(x - tagged[0], y - tagged[1]) > within) continue; let pixels = 0, sumX = 0, sumY = 0; const stack = [start]; seen[start] = 1;
diff --git a/packages/telescope-cli/AGENTS.md b/packages/telescope-cli/AGENTS.md
index 8fefa81a04d..c752692a5b6 100644
--- a/packages/telescope-cli/AGENTS.md
+++ b/packages/telescope-cli/AGENTS.md
@@ -39,6 +39,11 @@ own through `workspace-commands/new-object.mts`, `new-object-cli.mts` is the sta
The generated solar geometry (`src/platform/solar-geometry.mts`) stays generated: the entries load it with `solar-epoch.mts` and
pass the epoch down, so no module here imports it.
+A published picture as one more dataset of a page is `src/new-object/pictures/`: `--from-esa` and a spec's `pictures`. `esa-image.mts` reads
+ESA's picture pages and the sky tags in a JPEG, `registration.mts` owns the arithmetic from those tags and one pixel to a recipe's
+observation, plane and rim, `picture-bank.mts` writes one entry's records from the bank it is like, and `pictures.mts` drafts, writes
+and bakes. It never writes a sentence a reader sees and never picks a value for a color: those are the spec's, written by a person.
+
The star survey behind `telescope stars GALAXY` is `src/stars/`. It and the generator's `--from-table` route
(`src/new-object/archives/tables/table-stars.mts`) read VizieR's table metadata and SIMBAD through the same two modules,
`vizier-tables.mts` and `simbad-tap.mts` beside it; a star class is a branch of SIMBAD's own type tree, never a
diff --git a/packages/telescope-cli/README.md b/packages/telescope-cli/README.md
index f7aff20268c..6df2ac332b7 100644
--- a/packages/telescope-cli/README.md
+++ b/packages/telescope-cli/README.md
@@ -38,6 +38,8 @@ In a terminal, `explore` shows the observations, unknown metadata, unsupported r
`telescope simulations OBJECT` lists the Zenodo dataset records that name the object and speak of a simulation or a model, each with its license, size and files. It downloads nothing, and a listed record is a lead. To show one, read its paper and write an entry for `node packages/telescope-cli/src/new-object/new-object-cli.mts --simulation entries.json` ([simulation-dataset.mts](src/new-object/simulation/simulation-dataset.mts) documents the entry). That command checks the record's license, that it names the object and that it lists the file, and writes the dataset with its labels. It never fetches the release whole: two range requests bring the file's first bytes (its header and coordinate variables) and the bytes of the selected grid into the body's source directory, each declared with its byte range in the source manifest. A 3.5 GB run costs about 130 kB. The [published simulations](../../.agents/skills/celestial-skill/references/scientific-faithfulness.md#published-simulations) rule gives the conditions.
+`telescope new-object --from-esa PAGE_ID=PICTURE_URL... --out SPEC.json` drafts a published picture as one more dataset of a page that already shows a shaped layer bank: a picture ESA publishes for Hubble or Webb (`m57=https://esawebb.org/images/weic2320c/`). It reads the picture's page (title, credit, release date, colors) and the sky tags in its JPEG, finds the star the picture shows where the tags put the page's place, and names the bank the picture will lie on like: the one the page opens on. A picture that does not hold the page's place is refused. A person then writes the dataset's sentences and, under `geometry`, what this picture's light takes on those walls: printed values, each with its source. `telescope new-object SPEC.json` writes the new bank's records, the picture, the page's dataset and a README whose measured lines are filled in; `--bake` bakes the banks and their pages in one chain. A spec can be run again after a change, and the README a person wrote is kept. The entry's fields are in [picture-bank.mts](src/new-object/pictures/picture-bank.mts).
+
`telescope stars GALAXY` counts the stars SIMBAD lists inside a galaxy's catalogued outline by class (Cepheids, RR Lyrae stars, long-period variables, supergiants), names the papers they come from, and reads VizieR's tables of those papers for what a placed star needs: a period and a position of its own. It also names the single stars of no class that SIMBAD holds there with no parallax and no proper motion, the most cited first: a star one paper studied alone (M51-DS1) is often typed a plain star, and is drafted by hand from that paper. Last, it asks the papers API (OpenAlex, with arXiv when OpenAlex's daily budget is spent; the same index `telescope papers` reads) for the works whose title or abstract names the galaxy and a kind of star, those with the star in the title first: SIMBAD and VizieR take months to hold a new paper and never hold some, so a 2026 paper of Cepheids in M61 and M77 and a 2003 paper of one star in NGC 253's halo were found only there. It downloads nothing, and a star SIMBAD lists inside the outline may still be in front of the galaxy. A table it calls ready drafts a star: `telescope new-object --from-table cepheid:m81=J/ApJ/743/176/table1 --out spec.json` writes the spec of one Cepheid of that table, placed where its sight line crosses the disc the galaxy is drawn as ([table-stars.mts](src/new-object/archives/tables/table-stars.mts) documents the row choices). A table that gives every row its galaxy's centre, as a reanalysis does, places its stars at SIMBAD's position of the SIMBAD name CDS added to each row. A table that lists each star by its detector pixel (a chip, X and Y, as the Hubble Cepheid papers do) needs the exposure those pixels were measured on, which only the paper says: `--from-table "cepheid:m66=J/ApJ/529/723/appen#exposure=mast:HST/product/u35i0101r_c0m.fits,firstPixel=1"` reads that chip's header from MAST by byte range (11,520 bytes of a 10 MB file) and places the star where the header's world coordinates put the pixel. `firstPixel` is the coordinate the paper's software gives the centre of the first pixel: 1 for DAOPHOT and ALLFRAME, 0.5 for HSTphot. The position is Hubble's pointing as archived, not registered against a catalogue: on the one exposure checked, a supernova with a catalogued position fell 1.2″ from it ([image-pixel.mts](src/new-object/archives/images/image-pixel.mts)); a hand-written spec does the same with `position.archive: "mast"`. Coordinates a paper prints in a table that neither VizieR nor SIMBAD holds yet are used as printed with `position.archive: "paper"`: the paper is cited by its DOI and nothing is archived.
When you know the scientific acceptance criteria, save an explicit request:
diff --git a/packages/telescope-cli/src/cli.test.mts b/packages/telescope-cli/src/cli.test.mts
index 11f592e2d63..0521929d4dd 100644
--- a/packages/telescope-cli/src/cli.test.mts
+++ b/packages/telescope-cli/src/cli.test.mts
@@ -83,6 +83,8 @@ test('new-object bakes a spec after generating it, or objects already in the tre
const draft=parseCli(['new-object','--from-debcat','47 Tuc V69','CM Dra','--out','spec.json']);assert.equal(draft.command,'new-object');if(draft.command!=='new-object')return;
assert.deepEqual([draft.from,draft.names],['debcat',['47 Tuc V69','CM Dra']]);
assert.throws(()=>parseCli(['new-object','--from-apokasc','--out','spec.json']),/--from-apokasc NAME\.\.\. --out SPEC\.json/u);
+ const picture=parseCli(['new-object','--from-esa','m57=https://esawebb.org/images/weic2320c/','--out','spec.json']);assert.equal(picture.command,'new-object');if(picture.command!=='new-object')return;
+ assert.deepEqual([picture.from,picture.names],['esa',['m57=https://esawebb.org/images/weic2320c/']]);
});
test('local import has one bounded data-only entry point',()=>{
const parsed=parseCli(['import','spec.json','--out','run','--json']);assert.equal(parsed.command,'import');if(parsed.command!=='import')return;
diff --git a/packages/telescope-cli/src/help.mts b/packages/telescope-cli/src/help.mts
index 8d06858ec53..555fa4d9eb3 100644
--- a/packages/telescope-cli/src/help.mts
+++ b/packages/telescope-cli/src/help.mts
@@ -20,7 +20,7 @@ Human entry points:
telescope leads TARGET | --class CLASS [--json] [--out DIRECTORY]
telescope stars GALAXY [--json] [--out DIRECTORY]
telescope new-object SPEC.json [--check] [--skip-existing] [--json]
- telescope new-object --from-archive HOST... | --from-debcat SYSTEM... | --from-apokasc KIC... | --from-cepheids NAME... | --from-k2 EPIC... | --from-tess TIC... | --from-gaia SOURCE_ID... | --from-hipparcos HIP... | --from-iau all|NAME... | --from-chara HD... | --from-npoi HD... | --from-sh0es HOST[/ID]... | --from-m31cepheids all|V1|ID... | --from-m33cepheids all|ID... | --from-table CLASS:GALAXY=TABLE[#ROW]... --out SPEC.json
+ telescope new-object --from-archive HOST... | --from-debcat SYSTEM... | --from-apokasc KIC... | --from-cepheids NAME... | --from-k2 EPIC... | --from-tess TIC... | --from-gaia SOURCE_ID... | --from-hipparcos HIP... | --from-iau all|NAME... | --from-chara HD... | --from-npoi HD... | --from-sh0es HOST[/ID]... | --from-m31cepheids all|V1|ID... | --from-m33cepheids all|ID... | --from-table CLASS:GALAXY=TABLE[#ROW]... | --from-esa PAGE_ID=PICTURE_URL... --out SPEC.json
telescope ascl SOFTWARE [--json]
telescope ascl --product PRODUCT.json|RUN/pick-N/result.json [--json]
telescope wwt-fits EXPLORE.json --pick N --level N --x X --y Y --out DIRECTORY
@@ -50,7 +50,10 @@ Only prose is left marked TODO(new-object), unless the spec carries drafted text
NASA Exoplanet Archive's default parameter sets (their transiting planets, with drafted text); --from-debcat drafts both stars of
an eclipsing binary from DEBCat, --from-apokasc a Kepler-field giant from APOKASC-3, --from-cepheids a Cepheid from Groenewegen
(2013), --from-k2 a K2-field giant and --from-tess a TESS giant from Khan et al. (2023), --from-gaia any star from Gaia DR3 FLAME, --from-hipparcos a Hipparcos star from the model-atmosphere fit to its light (McDonald et al. 2017), --from-iau the stars the IAU has named that the universe lacks, each by the first of those routes that measures it, --from-chara a nearby star whose disc CHARA measured (Boyajian et al. 2012), --from-npoi a bright star whose disc the NPOI measured (Baines et al. 2018, 2021), --from-sh0es the Cepheids Hubble found in a SN Ia host galaxy (Hoffmann et al. 2016), --from-m31cepheids Hubble's V1 and the Cepheids Hubble measured in Andromeda (Li et al. 2021), --from-m33cepheids those it measured in Triangulum (Breuval et al. 2023), --from-table a star of another galaxy from any VizieR table that lists it with a period (cepheid:m81=J/ApJ/743/176/table1), placed in its galaxy by the table's position, by SIMBAD's, or by the table's detector pixel on the exposure the request names (#exposure=mast:HST/product/FILE.fits,firstPixel=N), each naming what the spec still needs from the paper; --check runs the bake's first steps on
-what was generated; --skip-existing leaves objects already in the universe alone. The spec format is in packages/telescope-cli/src/new-object/spec.mts.
+what was generated; --skip-existing leaves objects already in the universe alone. --from-esa drafts a picture ESA publishes for Hubble or Webb as one more
+dataset of a page that shows a shaped layer bank (m57=https://esawebb.org/images/weic2320c/): it reads the picture's page and the sky tags in its JPEG, finds the
+star the picture shows at the page's place, and leaves the sentences and what each color takes on the bank's walls to write; a spec of pictures writes each
+picture's bank and its page's dataset, may be run again, and bakes with SPEC.json --bake. The spec format is in packages/telescope-cli/src/new-object/spec.mts.
Papers lists up to 20 OpenAlex works that name the target, by any spelling of its catalogue names, in their title or
abstract, with the instrument and any one of the --about phrases (singular or plural); --fulltext asks for the works whose
indexed full text names them. It uses arXiv's Atom API when OpenAlex is unavailable or its daily budget is spent, and the
diff --git a/packages/telescope-cli/src/new-object/cli.mts b/packages/telescope-cli/src/new-object/cli.mts
index 14a87c76bb1..5f61dc624f4 100644
--- a/packages/telescope-cli/src/new-object/cli.mts
+++ b/packages/telescope-cli/src/new-object/cli.mts
@@ -22,6 +22,8 @@ export function parseNewObjectOptions(value:unknown):NewObjectOptions{
return {...string('spec'),...strings('ids'),...string('from'),...strings('names'),...string('out'),check:flag('check'),bake:flag('bake'),refresh:flag('refresh'),skipExisting:flag('skipExisting'),json:flag('json')};
}
+const holdsPictures=async(spec:string)=>{const {readFile}=await import('node:fs/promises'),value:unknown=JSON.parse(await readFile(spec,'utf8'));return typeof value==='object'&&value!==null&&'pictures' in value;};
+
/** The result text and exit code for one parsed `new-object` command. */
export async function newObjectCommand(options:NewObjectOptions,root:string,stderr:(text:string)=>void):Promise<{readonly text:string;readonly code:number}>{
let text:string,code:number;
@@ -38,6 +40,11 @@ export async function newObjectCommand(options:NewObjectOptions,root:string,stde
}else if(options.from){
const result=await writeDrafts(options.from,options.names??[],options.out!,{root,archive:liveArchive,progress:line=>stderr(`${line}\n`)});
text=options.json?`${JSON.stringify(result)}\n`:`${result.report.join('\n')}\n${result.entries} entries written to ${result.path}\n`;code=result.entries?0:3;
+ }else if(await holdsPictures(options.spec!)){
+ // A spec of published pictures: each one a dataset on a page that shows a shaped layer bank (pictures/pictures.mts).
+ const {runPictures,bakePictures,formatPictures}=await import('./pictures/pictures.mts'),results=await runPictures(options.spec!,{root,archive:liveArchive,progress}),good=results.filter(result=>!result.failed);
+ const baked=options.bake&&good.length?await bakePictures(good,{root,progress}):true;
+ text=options.json?`${JSON.stringify(results)}\n`:formatPictures(results,options.spec!,baked&&options.bake&&good.length>0);code=baked&&good.length===results.length?0:1;
}else{
const results=await runNewObject(options.spec!,{root,progress:line=>stderr(`${line}\n`),skipExisting:options.skipExisting,solarEpoch:await loadSolarEpoch(root)});
const good=results.filter(result=>!result.failed).map(result=>result.id),baked=(options.check||options.bake)&&good.length?await prepareObjects(good,{root,progress,...(options.bake?{}:{to:'page'})}):true;
diff --git a/packages/telescope-cli/src/new-object/drafts.mts b/packages/telescope-cli/src/new-object/drafts.mts
index 3bfe7de288e..6e08f7a1961 100644
--- a/packages/telescope-cli/src/new-object/drafts.mts
+++ b/packages/telescope-cli/src/new-object/drafts.mts
@@ -5,7 +5,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, resolve } from 'node:path';
import type { Archive } from './archives/archives.mts';
-export interface Drafts { readonly stars: readonly unknown[]; readonly report: readonly string[] }
+export interface Drafts { readonly stars: readonly unknown[]; readonly pictures?: readonly unknown[]; readonly report: readonly string[] }
interface Context { readonly root: string; readonly progress: (line: string) => void; readonly archive: Archive }
export const DRAFT_ROUTES: Readonly Promise }>> = {
// Transiting planet hosts from the NASA Exoplanet Archive's default parameter sets (from-archive.mts).
@@ -38,6 +38,8 @@ export const DRAFT_ROUTES: Readonly (await import('./archives/m33-cepheids.mts')).draftsFromM33Cepheids(names, archive, root) },
// A star of another galaxy from any VizieR table that lists it with a position and a period (tables/table-stars.mts); `telescope stars GALAXY` finds the tables.
table: { names: 'CLASS:GALAXY=TABLE[#ROW]', draft: async (names, { archive, root }) => (await import('./archives/tables/table-stars.mts')).draftsFromTable(names, archive, root) },
+ // A picture ESA publishes for Hubble or Webb, as one more dataset of a page that shows a shaped layer bank (pictures/pictures.mts).
+ esa: { names: 'HOST=PAGE_URL', draft: async (names, context) => (await import('./pictures/pictures.mts')).draftsFromEsa(names, context) },
};
/** Draft `names` through `route` and write the spec file at `out`. */
@@ -45,7 +47,7 @@ export async function writeDrafts(route: string, names: readonly string[], out:
const source = DRAFT_ROUTES[route];
if (!source) throw new TypeError(`No draft route ${route}; the routes are ${Object.keys(DRAFT_ROUTES).map(key => `--from-${key}`).join(', ')}.`);
if (!names.length) throw new TypeError(`Usage: new-object --from-${route} ${source.names}... --out spec.json`);
- const { stars, report } = await source.draft(names, context), path = resolve(context.root, out);
- await mkdir(dirname(path), { recursive: true }); await writeFile(path, `${JSON.stringify({ stars }, null, 2)}\n`);
- return { path, entries: stars.length, report };
+ const { stars, pictures, report } = await source.draft(names, context), path = resolve(context.root, out);
+ await mkdir(dirname(path), { recursive: true }); await writeFile(path, `${JSON.stringify(pictures ? { pictures } : { stars }, null, 2)}\n`);
+ return { path, entries: (pictures ?? stars).length, report };
}
diff --git a/packages/telescope-cli/src/new-object/new-object.test.mts b/packages/telescope-cli/src/new-object/new-object.test.mts
index eceee79d670..5d5c223337b 100644
--- a/packages/telescope-cli/src/new-object/new-object.test.mts
+++ b/packages/telescope-cli/src/new-object/new-object.test.mts
@@ -865,7 +865,7 @@ test('APOKASC-3 and Groenewegen (2013) rows draft single stars through the one r
const { physicalValues } = await import('./generate.mts'), values = physicalValues(measured, { sourceId: '1', ra: 0, dec: 0, g: 13, hasXpSampled: false });
assert.deepEqual([values.gm, values.logg], [0, 1.2]);
assert.match(values.massText, /No mass is measured, so GM is 0/u);
- assert.deepEqual(Object.keys(DRAFT_ROUTES), ['archive', 'debcat', 'apokasc', 'cepheids', 'k2', 'tess', 'gaia', 'hipparcos', 'iau', 'chara', 'npoi', 'sh0es', 'm31cepheids', 'm33cepheids', 'table']);
+ assert.deepEqual(Object.keys(DRAFT_ROUTES), ['archive', 'debcat', 'apokasc', 'cepheids', 'k2', 'tess', 'gaia', 'hipparcos', 'iau', 'chara', 'npoi', 'sh0es', 'm31cepheids', 'm33cepheids', 'table', 'esa']);
await assert.rejects(writeDrafts('gcvs', ['X'], 'output/x.json', { root, progress: () => {}, archive: {} as Archive }), /No draft route gcvs; the routes are --from-archive, --from-debcat, --from-apokasc, --from-cepheids, --from-k2, --from-tess, --from-gaia/u);
});
diff --git a/packages/telescope-cli/src/new-object/orbit.mts b/packages/telescope-cli/src/new-object/orbit.mts
index 9bdd099ea3f..1825c6976ff 100644
--- a/packages/telescope-cli/src/new-object/orbit.mts
+++ b/packages/telescope-cli/src/new-object/orbit.mts
@@ -20,7 +20,7 @@ export interface HostedOrbit {
}
const round = (value: number, digits: number) => Number(value.toFixed(digits));
/** The archive writes reference labels as HTML: accented author names arrive as entities. */
-const NAMED_ENTITIES: Record = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', aacute: 'á', eacute: 'é', iacute: 'í', oacute: 'ó', uacute: 'ú', agrave: 'à', egrave: 'è', ntilde: 'ñ', uuml: 'ü', ouml: 'ö', auml: 'ä', ccedil: 'ç', szlig: 'ß', oslash: 'ø', aring: 'å', Aacute: 'Á', Eacute: 'É', Oslash: 'Ø', ecirc: 'ê', ocirc: 'ô', acirc: 'â', scaron: 'š', zcaron: 'ž', ccaron: 'č' };
+const NAMED_ENTITIES: Record = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', aacute: 'á', eacute: 'é', iacute: 'í', oacute: 'ó', uacute: 'ú', agrave: 'à', egrave: 'è', ntilde: 'ñ', uuml: 'ü', ouml: 'ö', auml: 'ä', ccedil: 'ç', szlig: 'ß', oslash: 'ø', aring: 'å', Aacute: 'Á', Eacute: 'É', Oslash: 'Ø', ecirc: 'ê', ocirc: 'ô', acirc: 'â', scaron: 'š', zcaron: 'ž', ccaron: 'č', mu: 'µ', deg: '°' };
export const decodeEntities = (text: string) => text.replace(/&(#x[0-9a-f]+|#\d+|[a-zA-Z]+);/gu, (whole, code: string) =>
code.startsWith('#x') ? String.fromCodePoint(parseInt(code.slice(2), 16)) : code.startsWith('#') ? String.fromCodePoint(Number(code.slice(1))) : NAMED_ENTITIES[code] ?? whole);
const mod360 = (value: number) => ((value % 360) + 360) % 360;
diff --git a/packages/telescope-cli/src/new-object/pictures/esa-image.mts b/packages/telescope-cli/src/new-object/pictures/esa-image.mts
new file mode 100644
index 00000000000..c0669263930
--- /dev/null
+++ b/packages/telescope-cli/src/new-object/pictures/esa-image.mts
@@ -0,0 +1,64 @@
+/** A picture ESA publishes for Hubble or Webb (esahubble.org, esawebb.org): what its page says of it, and the sky tags
+ * its JPEG carries. The page gives the title, the credit, the release date and the colors; the file gives its own size,
+ * and in its embedded Astronomy Visualization Metadata the scale, the direction of north and one place on the sky. */
+import { decodeEntities } from '../orbit.mts';
+import type { Archive } from '../archives/archives.mts';
+
+/** A JPEG's sky tags, for the file as downloaded: degrees a pixel, north's turn counter-clockwise from up, and the sky
+ * place (right ascension, declination) of one pixel, counted from the picture's bottom left. */
+export interface SkyTags { readonly scaleDeg: number; readonly rotationDeg: number; readonly reference: readonly [number, number]; readonly referencePixel: readonly [number, number] }
+export interface PictureColor { readonly band: string; readonly shown: string; readonly line?: string; readonly wavelength: string; readonly instrument: string }
+export interface EsaPage { readonly id: string; readonly telescope: 'Hubble' | 'Webb'; readonly page: string; readonly download: string; readonly rights: string;
+ readonly title: string; readonly credit: string; readonly released: string; readonly original: readonly [number, number]; readonly colors: readonly PictureColor[] }
+
+const SITES: Readonly> = { 'esahubble.org': 'Hubble', 'esawebb.org': 'Webb' };
+const words = (html: string) => decodeEntities(html.replace(/<[^>]*>/gu, ' ')).replace(/\s+/gu, ' ').trim();
+
+/** The picture a page address names: `https://esawebb.org/images/weic2320c/`. */
+export function esaPictureAddress(address: string): Pick {
+ const found = /^https:\/\/(esahubble\.org|esawebb\.org)\/images\/([a-z0-9-]+)\/?$/u.exec(address);
+ if (!found) throw new TypeError(`${JSON.stringify(address)} is not a picture's page at esahubble.org or esawebb.org (https://esawebb.org/images//).`);
+ const [, site, id] = found as unknown as [string, string, string];
+ return { id, telescope: SITES[site]!, page: `https://${site}/images/${id}/`, download: `https://cdn.${site}/archives/images/large/${id}.jpg`, rights: `https://${site}/copyright/` };
+}
+
+/** What a picture's page says of it. A field the page lacks is refused by name: the generator writes none of them itself. */
+export function parseEsaPage(address: string, html: string): EsaPage {
+ const picture = esaPictureAddress(address), lacks = (what: string): never => { throw new TypeError(`${picture.page}: the page has no ${what} to read.`); };
+ const lines = html.replace(//gu, '').replace(/<[^>]*>/gu, '\n').split('\n').map(words).filter(Boolean);
+ const after = (label: string) => lines[lines.indexOf(label) + 1] ?? '';
+ const title = words(/([^<]*)<\/title>/u.exec(html)?.[1] ?? '').split(' | ')[0]! || lacks('title');
+ const credit = words(/<div class="credit">([\s\S]*?)<\/div>/u.exec(html)?.[1] ?? '').replace(/\.$/u, '') || lacks('credit');
+ const size = /^(\d+) x (\d+) px$/u.exec(lines.includes('Size:') ? after('Size:') : '') ?? lacks('"Size: W x H px"');
+ const released = /^\d{1,2} [A-Z][a-z]+ \d{4}/u.exec(lines.includes('Release date:') ? after('Release date:') : '')?.[0] ?? lacks('release date');
+ // The colors table: a row is the band with the color it is shown in and the line's name where the page gives one, the wavelength, and the telescope with its instrument.
+ const table = /<h3[^>]*>Colou?rs &(?:amp;)? filters<\/h3>\s*<table[\s\S]*?<\/table>/u.exec(html)?.[0] ?? '', colors: PictureColor[] = [];
+ for (const row of table.matchAll(/<tr>([\s\S]*?)<\/tr>/gu)) {
+ const cells = [...row[1]!.matchAll(/<td>([\s\S]*?)<\/td>/gu)].map(cell => cell[1]!);
+ if (cells.length !== 3) continue;
+ const [band, wavelength, facility] = cells as [string, string, string], line = words(/class="band_instrument">([\s\S]*?)<\/span>/u.exec(band)?.[1] ?? '');
+ const [, instrument = ''] = facility.split(/<br\s*\/?>/u).map(words);
+ colors.push({ band: words(band).split(' ')[0]!, shown: /class="band_([A-Za-z]+)"/u.exec(band)?.[1] ?? '', ...(line ? { line } : {}), wavelength: words(wavelength), instrument });
+ }
+ if (!colors.length) lacks('"Colours & filters" table');
+ return { ...picture, title, credit, released, original: [Number(size[1]), Number(size[2])], colors };
+}
+
+/** The sky tags in a JPEG's bytes, for a file `width` pixels across: a publisher's smaller copy carries the tags of its
+ * original, whose scale and reference pixel are brought to this file's own pixels. */
+export function skyTags(bytes: Buffer, width: number, height: number, name: string): SkyTags {
+ const text = bytes.toString('latin1');
+ const tag = (key: string, count: number) => { const found = new RegExp(`<avm:${key}>([\\s\\S]*?)</avm:${key}>`, 'u').exec(text) ?? new RegExp(`avm:${key}="([^"]*)"`, 'u').exec(text);
+ const values = found?.[1]!.replace(/<[^>]+>/gu, ' ').trim().split(/\s+/u).map(Number) ?? [];
+ if (values.length < count || !values.slice(0, count).every(Number.isFinite)) throw new TypeError(`${name} carries no avm:${key}: the picture has no sky tags to place it by.`);
+ return values; };
+ const [taggedWidth, taggedHeight] = tag('Spatial.ReferenceDimension', 2) as [number, number], shrink = taggedWidth / width;
+ if (Math.abs(taggedHeight / shrink - height) > 1) throw new TypeError(`${name} is ${width} x ${height} px; its sky tags describe ${taggedWidth} x ${taggedHeight}, another shape.`);
+ const pixel = tag('Spatial.ReferencePixel', 2), place = tag('Spatial.ReferenceValue', 2);
+ return { scaleDeg: Math.abs(tag('Spatial.Scale', 1)[0]!) * shrink, rotationDeg: tag('Spatial.Rotation', 1)[0]!, reference: [place[0]!, place[1]!], referencePixel: [pixel[0]! / shrink, pixel[1]! / shrink] };
+}
+
+/** A picture's page, read through the telescope's archive transfer. */
+export async function readEsaPage(address: string, archive: Archive): Promise<EsaPage> {
+ return parseEsaPage(address, await archive.text(esaPictureAddress(address).page));
+}
diff --git a/packages/telescope-cli/src/new-object/pictures/picture-bank.mts b/packages/telescope-cli/src/new-object/pictures/picture-bank.mts
new file mode 100644
index 00000000000..0d6fac4f1aa
--- /dev/null
+++ b/packages/telescope-cli/src/new-object/pictures/picture-bank.mts
@@ -0,0 +1,159 @@
+/** One published picture as a dataset of a page that already shows a shaped layer bank. A spec entry names the page, the
+ * picture and the bank whose walls, surface or rings the picture lies on (`like`); the records of the new bank are that
+ * bank's with this picture's own registration, and the page gains a dataset. The generator reads and computes: every
+ * sentence a reader sees (the dataset's title and text, what is chosen and why) is the spec's, written by a person. */
+import { isRecord, requireArray, requireFiniteNumber, requireRecord, requireString } from '@cssearth/core';
+import { INVESTIGATION_LEDGER_SCHEMA, OBJECT_SCHEMA, PREPARED_IMAGE_LAYER_BANK_SCHEMA } from '@cssearth/objects';
+import { json, type PackageFiles } from '../dataset.mts';
+import { TODO } from '../scaffold.mts';
+import type { EsaPage, PictureColor, SkyTags } from './esa-image.mts';
+import { registerPicture, RIM_FROM, type Place, type Registration } from './registration.mts';
+
+/** A layer bank's own dataset is named `optical` whatever its light: the page's dataset carries the reader's name for it. */
+export const BANK_DATASET = 'optical';
+/** The widest face a picture is baked at unless its entry says otherwise: the Ring Nebula's near-infrared bank is 4.9 MB at
+ * this size (2026-10-04). */
+export const FACE_PIXELS = 1500;
+const LICENSE = 'CC-BY-4.0', ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u, STATUSES = ['included', 'excluded', 'deferred'] as const;
+
+/** A source an entry cites; `checked` is the day a person read it, the run's day when absent. */
+export interface PictureSource { readonly catalogueId: string; readonly url: string; readonly label: string; readonly locator: string; readonly checked?: string }
+export interface LedgerEntry { readonly id: string; readonly subject: string; readonly status: typeof STATUSES[number]; readonly finding: string; readonly evidence: readonly string[] }
+export interface PictureEntry {
+ readonly host: string; readonly image: string; readonly bank: string; readonly like: string;
+ readonly dataset: { readonly id: string; readonly label: string; readonly title: string; readonly summary: string; readonly description: string };
+ /** The wavelengths the picture shows; the page's own table when absent. */
+ readonly colors?: readonly string[];
+ /** The pixel, from the picture's top left, of the star that stands at the page's place; the tags' own pixel when absent. */
+ readonly star?: readonly [number, number];
+ /** How that star was found in the picture, as a draft reports it: "the largest patch of saturated pixels within 1 arcsec, 29 px". */
+ readonly starFound?: string;
+ readonly facePixels?: number;
+ /** Laid over the like bank's recipe geometry: the values this picture's light takes on the same walls; null removes one. */
+ readonly geometry?: Readonly<Record<string, unknown>>;
+ readonly displayModel?: string;
+ readonly sources: readonly PictureSource[]; readonly ledger: readonly LedgerEntry[];
+}
+type Json = Record<string, unknown>;
+export interface PictureInputs {
+ readonly page: EsaPage; readonly tags: SkyTags; readonly dimensions: readonly [number, number];
+ /** Where the tags alone put the recipe's target, and how the entry's star was found when the draft found it. */
+ readonly tagged: readonly [number, number];
+ readonly like: { readonly recipe: Json; readonly manifest: Json; readonly presentation: Json; readonly provenance: Json };
+ readonly host: { readonly content: Json; readonly text: Json };
+ readonly checked: string;
+}
+
+/** A spec file's `pictures`. An entry a draft left unfinished is refused by the field still to write. */
+export function parsePictures(value: unknown): PictureEntry[] {
+ const entries = requireArray(requireRecord(value, 'picture spec').pictures, 'pictures').map((entry, index): PictureEntry => {
+ const at = `pictures[${index}]`, input = requireRecord(entry, at), text = (record: Json, key: string, where: string) => requireString(record[key], `${where}.${key}`).trim();
+ const unwritten = (found: unknown, where: string): void => { if (typeof found === 'string' && found.includes('TODO(')) throw new TypeError(`${where} is still to write: ${found}`);
+ if (Array.isArray(found)) found.forEach((one, i) => unwritten(one, `${where}[${i}]`)); else if (isRecord(found)) for (const [key, one] of Object.entries(found)) unwritten(one, `${where}.${key}`); };
+ unwritten(input, at);
+ const id = (key: string) => { const found = text(input, key, at); if (!ID.test(found)) throw new TypeError(`${at}.${key} ${JSON.stringify(found)} is not an object id (lower case, digits, hyphens).`); return found; };
+ const dataset = requireRecord(input.dataset, `${at}.dataset`), datasetId = text(dataset, 'id', `${at}.dataset`);
+ if (!ID.test(datasetId)) throw new TypeError(`${at}.dataset.id ${JSON.stringify(datasetId)} is not a dataset id (lower case, digits, hyphens).`);
+ const pair = (found: unknown, where: string) => { const list = requireArray(found, where).map(one => requireFiniteNumber(one, where)); if (list.length !== 2) throw new TypeError(`${where} must be two numbers: x and y from the picture's top left.`); return [list[0]!, list[1]!] as const; };
+ return { host: id('host'), image: text(input, 'image', at), bank: id('bank'), like: id('like'),
+ dataset: { id: datasetId, label: text(dataset, 'label', `${at}.dataset`), title: text(dataset, 'title', `${at}.dataset`), summary: text(dataset, 'summary', `${at}.dataset`), description: text(dataset, 'description', `${at}.dataset`) },
+ ...(input.colors === undefined ? {} : { colors: requireArray(input.colors, `${at}.colors`).map(one => requireString(one, `${at}.colors`)) }),
+ ...(input.star === undefined ? {} : { star: pair(input.star, `${at}.star`) }), ...(input.starFound === undefined ? {} : { starFound: text(input, 'starFound', at) }),
+ ...(input.facePixels === undefined ? {} : { facePixels: requireFiniteNumber(input.facePixels, `${at}.facePixels`) }),
+ ...(input.geometry === undefined ? {} : { geometry: requireRecord(input.geometry, `${at}.geometry`) }),
+ ...(input.displayModel === undefined ? {} : { displayModel: text(input, 'displayModel', at) }),
+ sources: (input.sources === undefined ? [] : requireArray(input.sources, `${at}.sources`)).map((one, i) => { const where = `${at}.sources[${i}]`, source = requireRecord(one, where);
+ return { catalogueId: text(source, 'catalogueId', where), url: text(source, 'url', where), label: text(source, 'label', where), locator: text(source, 'locator', where), ...(source.checked === undefined ? {} : { checked: text(source, 'checked', where) }) }; }),
+ ledger: (input.ledger === undefined ? [] : requireArray(input.ledger, `${at}.ledger`)).map((one, i) => { const where = `${at}.ledger[${i}]`, row = requireRecord(one, where), status = text(row, 'status', where) as LedgerEntry['status'];
+ if (!STATUSES.includes(status)) throw new TypeError(`${where}.status must be one of ${STATUSES.join(', ')}.`);
+ return { id: text(row, 'id', where), subject: text(row, 'subject', where), status, finding: text(row, 'finding', where), evidence: requireArray(row.evidence, `${where}.evidence`).map(link => requireString(link, `${where}.evidence`)) }; }) };
+ });
+ const repeated = entries.map(entry => entry.bank).filter((bank, index, all) => all.indexOf(bank) !== index);
+ if (repeated.length) throw new TypeError(`Picture banks repeat: ${repeated.join(', ')}.`);
+ return entries;
+}
+
+/** The wavelengths a page's table lists, in its order, each once; and a list of them as a reader's phrase: "7.7, 12 and 18 µm". */
+export const pageColors = (colors: readonly PictureColor[]) => [...new Set(colors.map(color => color.wavelength))];
+export function colorsPhrase(colors: readonly string[]) {
+ const parts = colors.map(color => /^(\S+) (\S+)$/u.exec(color)), unit = parts[0]?.[2], shared = parts.every(part => part && part[2] === unit) && colors.length > 1;
+ const list = shared ? parts.map(part => part![1]!) : [...colors];
+ return `${list.length > 1 ? `${list.slice(0, -1).join(', ')} and ${list.at(-1)}` : list[0] ?? ''}${shared ? ` ${unit}` : ''}`;
+}
+export const pictureRecordId = (page: Pick<EsaPage, 'id' | 'telescope'>) => `esa${page.telescope.toLowerCase()}-${page.id}`;
+
+/** `over` laid on `base`, key by key: a record goes into the record under it, any other value takes its place, and null removes it. */
+const lay = (base: Json, over: Readonly<Record<string, unknown>>): Json => { for (const [key, value] of Object.entries(over)) { if (value === null) delete base[key]; else base[key] = isRecord(value) && isRecord(base[key]) ? lay({ ...base[key] }, value) : value; } return base; };
+const copy = <T,>(value: T): T => structuredClone(value);
+
+/** Every record of one picture's bank and its page's dataset; `carried` are the like bank's other inputs, to copy beside
+ * the picture. `readme` is written only where the bank has none. */
+export function pictureFiles(entry: PictureEntry, inputs: PictureInputs): { readonly files: PackageFiles; readonly readme: string; readonly carried: readonly { readonly from: string; readonly to: string }[]; readonly registration: Registration; readonly todo: readonly string[] } {
+ const { page, tags, dimensions: [width, height], like, host, checked } = inputs, { bank, dataset } = entry, files: PackageFiles = new Map(), at = `src/objects/${bank}`, likeAt = `src/objects/${entry.like}/`;
+ const likeRecipe = copy(like.recipe), target = requireRecord(likeRecipe.target, `${entry.like} recipe target`) as unknown as Place, likeSource = requireRecord(likeRecipe.source, `${entry.like} recipe source`);
+ const star = entry.star ?? inputs.tagged, registration = registerPicture(tags, [width, height], star, target), { observation, plane, pixelArcsec, circleArcsec } = registration;
+ const publisher = `ESA/${page.telescope}`, record = pictureRecordId(page), colors = entry.colors ?? pageColors(page.colors), instruments = [...new Set(page.colors.map(color => color.instrument).filter(Boolean))];
+ const pixels = `${width} × ${height}`, field = `${(observation.fieldOfViewDeg[0] * 60).toFixed(2)} × ${(observation.fieldOfViewDeg[1] * 60).toFixed(2)} arcmin`, shown = `${instruments.join(' and ')} at ${colorsPhrase(colors)}`;
+ const direction = `${pixelArcsec.toFixed(4)} arcsec per pixel and north ${Math.abs(tags.rotationDeg).toFixed(1)}° ${tags.rotationDeg >= 0 ? 'left' : 'right'} of vertical`, centre = `${observation.centerRaDeg}°, ${observation.centerDecDeg}°`;
+ const fromTags = (Math.hypot(star[0] - inputs.tagged[0], star[1] - inputs.tagged[1]) * pixelArcsec).toFixed(2);
+ const registered = entry.star
+ ? `The file's embedded sky tags for scale and direction, ${direction}, and the star for place: the star in the picture, ${entry.starFound ? `${entry.starFound}, ` : ''}pixel ${star.join(', ')}, is set at the recipe's target, so the frame's centre is ${centre}. The tags alone put the star ${fromTags} arcsec from where the picture shows it.`
+ : `The file's embedded sky tags, used as they are: ${direction}, the frame's centre at ${centre}. Not measured against a star here.`;
+ const mark = entry.star ? 'the star' : 'the recipe\'s target', rim = `between ${(RIM_FROM * circleArcsec).toFixed(1)} and ${circleArcsec} arcsec from ${mark}`;
+
+ // The bank: the like bank's recipe with this picture, its registration and what the entry lays over the geometry.
+ const recipe = { ...likeRecipe, id: bank, source: { path: 'source.jpg', dimensions: [width, height], originalDimensions: page.original, publisherUrl: page.page, downloadUrl: page.download, credit: page.credit, license: LICENSE }, observation,
+ geometry: lay({ ...requireRecord(likeRecipe.geometry, `${entry.like} recipe geometry`), ...plane }, entry.geometry ?? {}),
+ bake: { ...requireRecord(likeRecipe.bake, `${entry.like} recipe bake`), maxFacePixels: entry.facePixels ?? Math.min(Math.max(width, height), FACE_PIXELS) } };
+ files.set(`${at}/source/recipe.json`, json(recipe));
+ files.set(`${at}/object.json`, json({ schema: OBJECT_SCHEMA, id: bank, type: 'image-layer-bank', properties: { preparation: { source: 'source/recipe.json' }, host: entry.host }, prepared: { format: PREPARED_IMAGE_LAYER_BANK_SCHEMA, url: 'prepared/image-layers.json' } }));
+
+ // The manifest: the picture, then every other input the like bank reads, each beside this bank.
+ const likePicture = `${likeAt}source/${requireString(likeSource.path, `${entry.like} recipe source.path`)}`, moved = (path: unknown) => requireString(path, `${entry.like} manifest path`).replace(likeAt, `${at}/`);
+ const others = requireArray(like.manifest.inputs, `${entry.like} manifest inputs`).map(input => requireRecord(input, `${entry.like} manifest input`)).filter(input => input.path !== likePicture);
+ const manifest = { ...copy(like.manifest), inputs: [{ id: BANK_DATASET, path: `${at}/source/source.jpg`, origin: page.download, sourceUrl: page.page, title: page.title, credit: page.credit, displayCredit: publisher,
+ acquisition: `The publisher's JPEG (${width} x ${height} px), downloaded unchanged; not tracked. Its scale and direction on the sky are the file's embedded tags; its place is ${entry.star ? 'set by the star' : 'the tags\' own'} (recipe observation). A display composite, not a calibrated scientific array.`,
+ sourceBinding: { kind: 'catalogued', references: [{ catalogueId: record, role: 'material', evidence: `${at}/source/provenance.json` }] }, dependencies: [], datasetId: BANK_DATASET, license: `${LICENSE}; retain the complete recorded credit.`,
+ capture: { attributions: [{ kind: 'facility', facilityId: page.telescope.toLowerCase(), evidence: page.page }] } }, ...others.map(input => ({ ...input, path: moved(input.path) }))],
+ documents: requireArray(like.manifest.documents, `${entry.like} manifest documents`).map(document => { const one = requireRecord(document, `${entry.like} manifest document`); return { ...one, path: moved(one.path) }; }), generatedIntermediates: [] };
+ files.set(`${at}/source/manifest.json`, json(manifest));
+ files.set(`${at}/source/presentation.json`, json({ ...copy(like.presentation), objectId: bank, defaultDataset: BANK_DATASET, bank: { path: `${at}/prepared/image-layers.json` },
+ recipes: [{ id: 'image-layer-recipe', path: `${at}/source/recipe.json` }, { id: 'source-evidence', path: `${at}/source/provenance.json` }], sharedInputs: [],
+ datasets: [{ id: BANK_DATASET, label: dataset.label, title: dataset.title, description: dataset.description, summary: dataset.summary, detail: `${pixels} px`,
+ facts: [{ id: 'bands', label: 'Colors', value: colorsPhrase(colors) }, { id: 'source-pixels', label: 'Source pixels', value: pixels }, { id: 'coverage', label: 'Field', value: field }, { id: 'license', label: 'License', value: LICENSE }],
+ input: BANK_DATASET, preview: { path: `${at}/source/source.jpg`, url: page.download } }] }));
+ const displayModel = entry.displayModel ?? requireString(like.provenance.displayModel, `${entry.like} provenance displayModel`);
+ files.set(`${at}/source/provenance.json`, json({ schema: 'cssearth-image-layer-provenance@1', title: page.title, publisher, sourceId: page.id, sourcePage: page.page, download: page.download, credit: page.credit, license: LICENSE,
+ original: { dimensions: page.original, bands: [page.telescope, ...instruments, ...colors], fieldOfViewDeg: observation.fieldOfViewDeg }, checkedSource: { kind: 'Published JPEG', dimensions: [width, height] },
+ geometryEvidence: { inclinationDeg: plane.inclinationDeg, lineOfNodesPaDeg: plane.lineOfNodesPaDeg, reference: `A picture of the sky: the plane is the picture's own tangent plane, perpendicular to the sight line through the picture's centre, so it faces the Sun. That centre is ${registration.starFromCentreArcsec.toFixed(1)} arcsec from ${mark}, which is the whole of the recipe's inclination. Not the orientation of the object itself.` },
+ registration: { method: registered, pixelArcsec: Number(pixelArcsec.toPrecision(4)), northClockwiseDeg: observation.northClockwiseDeg }, displayModel,
+ coverage: `The published frame inside a circle about ${mark}: the picture fades out ${rim}, the largest circle the frame holds, so no straight edge shows.`,
+ acquisition: { url: page.download, dimensions: [width, height], operation: 'Download the publisher\'s JPEG; no crop or resample.' } }));
+ files.set(`${at}/investigations.json`, json({ schema: INVESTIGATION_LEDGER_SCHEMA, objectId: bank, entries: [
+ { id: page.id, subject: `${publisher} ${page.id}`, status: 'included', finding: `${page.title}: ${shown}; ${pixels} px over ${field}, released ${page.released}. ${registered}`, evidence: [page.page, page.rights] }, ...entry.ledger] }));
+ files.set(`src/sources/${record}.json`, json({ id: record, kind: 'data-product', identityLevel: 'work', title: page.title, identifiers: [{ type: `${publisher} image`, value: page.id }],
+ links: [{ role: 'landing', url: page.page, label: 'Published source' }, { role: 'original', url: page.download, label: `JPEG, ${width} x ${height} px` }, { role: 'rights', url: page.rights, label: 'Reuse terms' }],
+ evidence: [{ url: page.page, checkedOn: checked, locator: `${width} x ${height} px over ${field}; ${shown}; released ${page.released}. ${registered}` }], publisher, relations: [],
+ statements: [{ kind: 'credit', text: page.credit, scope: 'Published source', evidence: page.page }, { kind: 'rights', text: 'Creative Commons Attribution 4.0 International; the full credit must be shown.', scope: 'Published source', evidence: page.rights }] }));
+
+ // The page: one more dataset, shown from this bank.
+ const content = copy(host.content), datasets = requireRecord(content.datasets, `${entry.host} content datasets`), controls = requireArray(datasets.controls, `${entry.host} dataset controls`).map(control => requireRecord(control, `${entry.host} dataset control`));
+ datasets.controls = [...controls.filter(control => control.id !== dataset.id), { id: dataset.id, label: dataset.label, thumbnail: `${entry.host}-dataset-${dataset.id}.webp`, volume: { objectId: bank, datasetId: BANK_DATASET, surface: dataset.id },
+ source: { id: `${bank}-${BANK_DATASET}`, path: `../../${bank}/source/manifest.json`, url: page.page }, falseColor: true }];
+ files.set(`src/objects/${entry.host}/source/content/object.json`, json(content));
+ const text = copy(host.text), texts = requireRecord(text.datasets, `${entry.host} text datasets`), picture: PictureSource = { catalogueId: record, url: page.page, label: `${publisher} ${page.id}: ${page.credit}`, locator: page.title };
+ // A source the page's dataset already cites in the same words keeps the day it was read: a run that changes nothing writes nothing.
+ const before = texts[dataset.id], cited = isRecord(before) && Array.isArray(before.sources) ? before.sources.filter(isRecord) : [];
+ const read = (source: PictureSource) => { const day = cited.find(one => one.catalogueId === source.catalogueId && one.url === source.url && one.label === source.label && one.locator === source.locator)?.checked; return typeof day === 'string' ? day : undefined; };
+ texts[dataset.id] = { title: dataset.title, detail: `${pixels} px`, summary: dataset.summary, sources: [picture, ...entry.sources].map(source => ({ catalogueId: source.catalogueId, url: source.url, label: source.label, checked: source.checked ?? read(source) ?? checked, locator: source.locator })) };
+ files.set(`src/objects/${entry.host}/text.json`, json(text));
+
+ const name = requireString(like.presentation.name, `${entry.like} presentation name`), parsecs = `${registration.widthPc.toFixed(2)} pc wide at ${Math.round(target.distancePc)} pc`;
+ const readme = `# ${name}, ${dataset.label}\n\n${TODO}: one paragraph. What the picture is, what it lies on (the [${entry.like}](../${entry.like}/README.md) bank's walls), and what is chosen here and not measured.\n\n## Sources\n\n| Selected source | Input and meaning |\n| --- | --- |\n` +
+ `| [${publisher} ${page.id}](${page.page}) | [Record](../../sources/${record}.json). ${page.title}: ${shown}; ${pixels} px over ${field} (\`source/source.jpg\`, the publisher's JPEG, restored from its origin). Credit: ${page.credit}. A display composite, not calibrated photometry. |\n` +
+ entry.sources.map(source => `| [${source.label}](${source.url}) | [Record](../../sources/${source.catalogueId}.json). ${source.locator} |\n`).join('') +
+ `\n## The picture\n\n- **Registration:** ${registered}\n- **Depth:** ${TODO}: what the picture's light lies on, and which printed value each color takes.\n- **Size:** ${field}, ${parsecs}.\n- **Rim:** the picture fades out ${rim}, the largest circle the frame holds.\n` +
+ `\n## Evidence\n\n${TODO}: the page with this dataset selected, captured headless, and what the capture shows.\n\n## Known problems\n\n- ${TODO}: what is chosen and not measured.\n- Colors are the publisher's display composite, not a measurement.\n`;
+ return { files, readme, carried: others.map(input => ({ from: requireString(input.path, `${entry.like} manifest path`), to: moved(input.path) })), registration,
+ todo: [`write ${at}/README.md`, `name the ${bank} bank in src/objects/${entry.host}/README.md`] };
+}
diff --git a/packages/telescope-cli/src/new-object/pictures/pictures.mts b/packages/telescope-cli/src/new-object/pictures/pictures.mts
new file mode 100644
index 00000000000..4a6d90a684e
--- /dev/null
+++ b/packages/telescope-cli/src/new-object/pictures/pictures.mts
@@ -0,0 +1,140 @@
+/** `telescope new-object` for published pictures: draft a spec from ESA's picture pages, write each entry's layer bank
+ * and its page's dataset, and bake them. One entry is one picture on a page that already shows a shaped bank
+ * (picture-bank.mts); the spec may be run again, and what a person wrote beside the records (the README) is kept. */
+import { spawn } from 'node:child_process';
+import { copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import sharp from 'sharp';
+import { isRecord, requireArray, requireRecord, requireString } from '@cssearth/core';
+import { fetchPublication, type Archive } from '../archives/archives.mts';
+import { TODO } from '../scaffold.mts';
+import { esaPictureAddress, readEsaPage, skyTags, type EsaPage } from './esa-image.mts';
+import { colorsPhrase, pageColors, parsePictures, pictureFiles, type PictureEntry } from './picture-bank.mts';
+import { locateStar, registerPicture, taggedPixel, type Place } from './registration.mts';
+
+interface Context { readonly root: string; readonly archive: Archive; readonly progress: (line: string) => void }
+export interface PictureResult { readonly id: string; readonly host: string; readonly dataset: string; readonly files: number; readonly todo: readonly string[]; readonly failed?: string }
+type Json = Record<string, unknown>;
+
+const exists = (path: string) => stat(path).then(() => true, () => false);
+const reason = (error: unknown) => (error as Error).message.split('\n')[0]!;
+const readJson = async (root: string, path: string, what: string): Promise<Json> => { let text: string; try { text = await readFile(resolve(root, path), 'utf8'); } catch { throw new Error(`${what}: ${path} does not exist.`); } return requireRecord(JSON.parse(text), path); };
+/** What a reader calls an instrument's light, for a draft's dataset id and label; the instrument's own name otherwise. */
+const LIGHT: Readonly<Record<string, string>> = { NIRCam: 'near infrared', MIRI: 'mid infrared' };
+
+/** The publisher's JPEG, read once: kept in the ignored `output/new-object/pictures/` between a draft and its run. */
+async function pictureBytes(page: EsaPage, { root, archive, progress }: Context) {
+ const kept = resolve(root, 'output/new-object/pictures', `${page.id}.jpg`);
+ if (await exists(kept)) return readFile(kept);
+ progress(` ${page.id}: reading ${page.download}`);
+ const bytes = await archive.bytes(page.download);
+ await mkdir(dirname(kept), { recursive: true }); await writeFile(kept, bytes);
+ return bytes;
+}
+async function pictureOnSky(page: EsaPage, target: Place, context: Context) {
+ const bytes = await pictureBytes(page, context), { data, info } = await sharp(bytes, { limitInputPixels: false }).removeAlpha().raw().toBuffer({ resolveWithObject: true });
+ if (info.channels !== 3) throw new Error(`${page.download}: a picture of ${info.channels} channel(s), not a color picture.`);
+ const tags = skyTags(bytes, info.width, info.height, page.download);
+ return { bytes, tags, rgb: data, dimensions: [info.width, info.height] as const, tagged: taggedPixel(tags, info.height, target) };
+}
+const bankOf = (content: Json, host: string) => { const datasets = requireRecord(content.datasets, `${host} content datasets`), controls = requireArray(datasets.controls, `${host} dataset controls`).map(control => requireRecord(control, `${host} dataset control`));
+ const shown = [controls.find(control => control.id === datasets.defaultDataset), ...controls].find(control => isRecord(control?.volume));
+ if (!shown) throw new Error(`${host}: the page shows no layer bank a picture could lie on like.`);
+ return requireString(requireRecord(shown.volume, `${host} dataset volume`).objectId, `${host} dataset volume.objectId`); };
+
+/** `--from-esa HOST=PAGE...`: one entry a picture, on the walls of the bank its page opens on, with the star the picture
+ * shows at the page's place. The sentences a reader sees are left to write. */
+export async function draftsFromEsa(names: readonly string[], context: Context): Promise<{ readonly stars: readonly unknown[]; readonly pictures: readonly unknown[]; readonly report: readonly string[] }> {
+ const pictures: unknown[] = [], report: string[] = [];
+ for (const asked of names) {
+ try {
+ const [host, address] = asked.split(/=(.*)/su) as [string, string | undefined];
+ if (!address) throw new Error(`${asked}: name a page and its picture as HOST=https://esawebb.org/images/<id>/.`);
+ const page = await readEsaPage(address, context.archive), like = bankOf(await readJson(context.root, `src/objects/${host}/source/content/object.json`, `${host}: no such page`), host);
+ const target = requireRecord((await readJson(context.root, `src/objects/${like}/source/recipe.json`, `${like}: not a layer bank`)).target, `${like} recipe target`) as unknown as Place;
+ const sky = await pictureOnSky(page, target, context), pixelArcsec = sky.tags.scaleDeg * 3600, star = locateStar(sky.rgb, ...sky.dimensions, pixelArcsec, sky.tagged);
+ registerPicture(sky.tags, sky.dimensions, star?.pixel ?? sky.tagged, target);
+ const name = requireString((await readJson(context.root, `src/objects/${like}/source/presentation.json`, like)).name, `${like} presentation name`), colors = pageColors(page.colors);
+ const instruments = [...new Set(page.colors.map(color => color.instrument).filter(Boolean))], light = instruments.length === 1 ? LIGHT[instruments[0]!] ?? instruments[0]! : instruments.join(' + ');
+ const slug = (words: string) => words.toLowerCase().replace(/[^a-z0-9]+/gu, '-'), write = (what: string) => `${TODO}: ${what}`;
+ pictures.push({ host, image: page.page, bank: `${host}-${slug(instruments.join(' '))}-layers`, like,
+ dataset: { id: slug(light), label: `${page.telescope} · ${light}`, title: write('the dataset\'s title'), summary: write('one sentence under the title'), description: write('what the picture shows and what it lies on') },
+ colors, ...(star ? { star: star.pixel.map(value => Number(value.toFixed(1))), starFound: star.found } : {}), geometry: {}, sources: [], ledger: [] });
+ report.push(`${page.id} on ${host}, like ${like}: ${page.title}; ${sky.dimensions.join(' x ')} px, ${instruments.join(' and ')} at ${colorsPhrase(colors)}. ` + (star
+ ? `The star: ${star.found}, at ${star.pixel.map(value => value.toFixed(1)).join(', ')}, ${(Math.hypot(star.pixel[0] - sky.tagged[0], star.pixel[1] - sky.tagged[1]) * pixelArcsec).toFixed(2)} arcsec from where the tags put the page's place. Remove "star" and "starFound" where the page stands at no star.`
+ : 'No star near the page\'s place: the picture is placed by its tags.') + ` What its colors show: telescope papers ${JSON.stringify(name)} --instrument ${instruments[0]}`);
+ } catch (error) { report.push(`${asked}: not drafted: ${reason(error)}`); }
+ }
+ return { stars: [], pictures, report };
+}
+
+/** A record in src/sources for every source an entry cites: the one there, or one read from arXiv or Crossref by its link. */
+async function sourceRecords(entry: PictureEntry, { root, archive }: Context) {
+ const records = new Map<string, string>();
+ for (const source of entry.sources) {
+ const path = `src/sources/${source.catalogueId}.json`;
+ if (await exists(resolve(root, path))) continue;
+ const publication = /arxiv\.org\/abs\/|doi\.org\//u.test(source.url) ? await fetchPublication(archive, source.url) : undefined;
+ if (!publication) throw new Error(`${entry.bank}: ${path} does not exist, and ${source.url} is not an arXiv or DOI link to write it from.`);
+ const { publicationRecord } = await import('../generate.mts');
+ records.set(path, `${JSON.stringify(publicationRecord({ ...publication, id: source.catalogueId }), null, 2)}\n`);
+ }
+ return records;
+}
+
+/** Write one entry: its bank's records, picture and other inputs, and its page's dataset. */
+async function writePicture(entry: PictureEntry, context: Context): Promise<PictureResult> {
+ const { root } = context, at = `src/objects/${entry.bank}`, inTree = (path: string) => resolve(root, path);
+ const page = await readEsaPage(entry.image, context.archive);
+ if (await exists(inTree(at))) { const made = await readJson(root, `${at}/source/recipe.json`, `${entry.bank} exists and is not a layer bank`);
+ if (requireRecord(made.source, `${entry.bank} recipe source`).publisherUrl !== page.page) throw new Error(`${at} already exists and shows another picture; the generator rewrites only the records of the picture it is given.`); }
+ if (entry.like === entry.bank) throw new Error(`${entry.bank}: a bank cannot be like itself.`);
+ const like = { recipe: await readJson(root, `src/objects/${entry.like}/source/recipe.json`, `${entry.like}: not a layer bank`), manifest: await readJson(root, `src/objects/${entry.like}/source/manifest.json`, entry.like),
+ presentation: await readJson(root, `src/objects/${entry.like}/source/presentation.json`, entry.like), provenance: await readJson(root, `src/objects/${entry.like}/source/provenance.json`, entry.like) };
+ const host = { content: await readJson(root, `src/objects/${entry.host}/source/content/object.json`, `${entry.host}: no such page`), text: await readJson(root, `src/objects/${entry.host}/text.json`, entry.host) };
+ const sky = await pictureOnSky(page, requireRecord(like.recipe.target, `${entry.like} recipe target`) as unknown as Place, context), records = await sourceRecords(entry, context);
+ const { files, readme, carried, todo } = pictureFiles(entry, { page, tags: sky.tags, dimensions: sky.dimensions, tagged: sky.tagged, like, host, checked: new Date().toISOString().slice(0, 10) });
+ for (const { from } of carried) if (!await exists(inTree(from))) throw new Error(`${entry.bank}: ${from}, which the ${entry.like} bank reads, is not restored; its manifest names where it comes from.`);
+ let written = 0;
+ const put = async (path: string, value: string | Buffer) => { await mkdir(dirname(inTree(path)), { recursive: true }); await writeFile(inTree(path), value); written++; };
+ for (const [path, value] of [...files, ...records]) if (!path.startsWith('src/sources/') || !await exists(inTree(path))) await put(path, value);
+ if (!await exists(inTree(`${at}/README.md`))) await put(`${at}/README.md`, readme);
+ await put(`${at}/source/source.jpg`, sky.bytes);
+ // The like bank's other inputs stand beside this bank too; one that Git ignores there is ignored here.
+ const ignore = inTree('.gitignore'), ignored = (await readFile(ignore, 'utf8')).split('\n');
+ for (const { from, to } of carried) { await copyFile(inTree(from), inTree(to)); written++;
+ if (ignored.includes(from) && !ignored.includes(to)) { ignored.splice(ignored.indexOf(from) + 1, 0, `# The same file beside the ${entry.bank} bank; restored from the same origin (${at}/source/manifest.json).`, to); await writeFile(ignore, ignored.join('\n')); } }
+ // What is left for a person: the bank's README while it holds a line to write, and the page's README until it names the bank.
+ const holds = async (path: string, words: string) => (await readFile(inTree(path), 'utf8').catch(() => '')).includes(words), left = [await holds(`${at}/README.md`, TODO), !await holds(`src/objects/${entry.host}/README.md`, `../${entry.bank}/`)];
+ return { id: entry.bank, host: entry.host, dataset: entry.dataset.id, files: written, todo: todo.filter((_, index) => left[index]) };
+}
+
+/** Every picture of a spec file, written. One that fails is reported with its reason and the rest go on. */
+export async function runPictures(specPath: string, context: Context): Promise<PictureResult[]> {
+ const entries = parsePictures(JSON.parse(await readFile(resolve(specPath), 'utf8'))), results: PictureResult[] = [];
+ for (const entry of entries) {
+ try { esaPictureAddress(entry.image); results.push(await writePicture(entry, context)); context.progress(` ${entry.bank}: written`); }
+ catch (error) { results.push({ id: entry.bank, host: entry.host, dataset: entry.dataset.id, files: 0, todo: [], failed: reason(error) }); context.progress(` ${entry.bank}: FAILED, not written: ${reason(error)}`); }
+ }
+ return results;
+}
+
+/** Bake the banks and their pages: each bank's layers and presentation, each page's hosted context, then the pages'
+ * prepared files in one run (the reader-text step checks every page against its prepared datasets), the catalogue and the
+ * world. Stops at the first step that fails. */
+export async function bakePictures(results: readonly PictureResult[], { root, progress }: Pick<Context, 'root' | 'progress'>): Promise<boolean> {
+ const banks = results.map(result => result.id), hosts = [...new Set(results.map(result => result.host))], node = (...args: string[]) => ['node', ...args];
+ const steps = [node('packages/bake/cli/check-stale-builds.mts', '--run'), ...banks.flatMap(bank => [node('packages/bake/cli/prepare-image-layers.mts', `src/objects/${bank}`), node('site/build/prepare/prepare-volume-presentation.mts', `--object=${bank}`)]),
+ ...hosts.map(host => node('site/build/prepare/companion-context.mts', host)), node('packages/bake/cli/prepare-object.mts', ...hosts, '--from', 'catalogue', '--to', 'markers'), node('site/build/prepare/prepare-catalog.mts'),
+ node('packages/bake/cli/prepare-object.mts', ...hosts, '--from', 'world'), node('packages/bake/cli/prepare-navigation.mts', '--catalog-only')];
+ for (const [command, ...args] of steps as [string, ...string[]][]) {
+ progress(`== ${args.join(' ')}`);
+ // A step's own output is progress: it goes where the telescope's does, and the result text stays the telescope's.
+ const code = await new Promise<number | null>(done => { spawn(command, args, { cwd: root, stdio: ['ignore', 2, 2] }).on('error', () => done(null)).on('close', done); });
+ if (code !== 0) { progress(`FAILED: ${command} ${args.join(' ')}`); return false; }
+ }
+ return true;
+}
+
+export const formatPictures = (results: readonly PictureResult[], spec: string, baked: boolean) => `${results.map(result => result.failed ? `${result.id} (picture): FAILED, not written: ${result.failed}`
+ : `${result.id} (picture, the ${result.dataset} dataset of ${result.host}): ${result.files} files.${result.todo.length ? `\n Still to write: ${result.todo.join('; ')}.` : ''}`).join('\n')}\n${baked ? `${results.filter(result => !result.failed).length} picture(s) baked.` : `Then bake: telescope new-object ${spec} --bake`}\n`;
diff --git a/packages/telescope-cli/src/new-object/pictures/pictures.test.mts b/packages/telescope-cli/src/new-object/pictures/pictures.test.mts
new file mode 100644
index 00000000000..47f7f0df0cd
--- /dev/null
+++ b/packages/telescope-cli/src/new-object/pictures/pictures.test.mts
@@ -0,0 +1,195 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import sharp from 'sharp';
+import { sourceTest } from '@cssearth/objects/node/source-test';
+import type { Archive } from '../archives/archives.mts';
+import { TODO } from '../scaffold.mts';
+import { esaPictureAddress, parseEsaPage, skyTags, type EsaPage, type SkyTags } from './esa-image.mts';
+import { colorsPhrase, parsePictures, pictureFiles } from './picture-bank.mts';
+import { draftsFromEsa, runPictures } from './pictures.mts';
+import { locateStar, registerPicture, taggedPixel } from './registration.mts';
+
+const test = sourceTest();
+const WEBB = 'https://esawebb.org/images/weic0000a/';
+// The two layouts ESA's sites give a picture's page: Webb's names the shown color in a hidden span, Hubble's in the class alone.
+const row = (band: string, wavelength: string, instrument: string) => `<tr><td>${band}</td><td>${wavelength}</td><td>\n Some Space Telescope\n <br/><span class="band_instrument">${instrument}</span></td></tr>`;
+const page = (title: string, credit: string, rows: string) => `<html><head><title>${title} | ESA/WebbCredit:\n
+| Release date: | 21 August 2023, 16:00 |
| Size: | 40 x 30 px |
+Colours & filters
| Band | Wavelength | Telescope |
|---|
${rows}