diff --git a/.github/workflows/pr-rtd-link.yml b/.github/workflows/pr-rtd-link.yml new file mode 100644 index 0000000..586ebca --- /dev/null +++ b/.github/workflows/pr-rtd-link.yml @@ -0,0 +1,24 @@ +# The ReadTheDocs preview link is "hidden" within the GitHub "Checks" +# interface. For users who don"t know this, finding the preview link may be +# very difficult or frustrating. This workflow makes the link more +# findable by updating PR descriptions to include it. +name: "Add ReadTheDocs preview link to PR description" + +on: + pull_request_target: + types: + - "opened" + +permissions: + pull-requests: "write" + +jobs: + autolink-rtd-previews: + runs-on: "ubuntu-latest" + steps: + - uses: "readthedocs/actions/preview@v1" + with: + project-slug: "transformez" + message-template: | + --- + :mag: Docs preview: {docs-pr-index-url} diff --git a/docs/source/api/api.md b/docs/source/api/api.md new file mode 100644 index 0000000..9b986aa --- /dev/null +++ b/docs/source/api/api.md @@ -0,0 +1,11 @@ +Developer API +============= + +The high-level Python API for fetching data in a single line of code. + +```{eval-rst} +.. automodule:: transformez.api + :members: generate_grid, transform_raster + :undoc-members: + :show-inheritance: +``` diff --git a/docs/source/api/index.md b/docs/source/api/index.md new file mode 100644 index 0000000..806a226 --- /dev/null +++ b/docs/source/api/index.md @@ -0,0 +1,9 @@ +# API Reference + +This section details the internal Python API for Transformez. + +```{toctree} +:maxdepth: 2 + +api +``` diff --git a/src/transformez/cli.py b/src/transformez/cli.py index d4ab79e..00b4221 100644 --- a/src/transformez/cli.py +++ b/src/transformez/cli.py @@ -30,7 +30,7 @@ def get_command(self, ctx, cmd_name): fg="yellow", err=True, ) - return click.Group.get_command(self, ctx, "grid") + return click.Group.get_command(self, ctx, "run") return click.Group.get_command(self, ctx, cmd_name) @@ -44,103 +44,103 @@ def transformez_cli(): pass -# @transformez_cli.command("run") -# @click.argument("input_file", required=False) -# @click.option( -# "-R", "--region", help="Bounding box or location string (if no input file)." -# ) -# @click.option( -# "-E", "--increment", help="Resolution (e.g., 1s, 30m) (if no input file)." -# ) -# @click.option( -# "-I", "--input-datum", required=True, help="Source Datum (e.g., 'mllw', '5703')." -# ) -# @click.option( -# "-O", -# "--output-datum", -# required=True, -# help="Target Datum (e.g., '4979', '5703:g2012b').", -# ) -# @click.option("--out", "-o", help="Output filename (default: auto-named).") -# @click.option( -# "--decay-pixels", -# type=int, -# default=100, -# help="Number of pixels to decay tidal shifts inland.", -# ) -# @click.option("--preview", is_flag=True, help="Preview the transformation output.") -# def transform_run( -# input_file, region, increment, input_datum, output_datum, out, decay_pixels, preview -# ): -# """Transform a raster's vertical datum or generate a standalone shift grid. - -# If an INPUT_FILE is provided, that specific raster is transformed in place. -# If no INPUT_FILE is provided, -R and -E must be used to generate a shift grid. - -# Examples:\n -# Transform a DEM : transformez run my_dem.tif -I mllw -O 5703 -# Generate a Grid : transformez run -R loc:"Miami" -E 1s -I mllw -O 4979 -# """ - -# if input_file: -# click.secho(f"Transforming raster: {input_file}", fg="cyan", bold=True) -# click.echo(f" Shift: {input_datum} ➔ {output_datum}") - -# result = api.transform_raster( -# input_raster=input_file, -# datum_in=input_datum, -# datum_out=output_datum, -# decay_pixels=decay_pixels, -# output_raster=out, -# verbose=True, -# ) - -# if result: -# click.secho( -# f"Successfully transformed raster: {result}", fg="green", bold=True -# ) -# else: -# click.secho("Failed to transform raster.", fg="red") -# sys.exit(1) - -# elif region and increment: -# click.secho( -# f"Generating vertical shift grid for region: {region}...", -# fg="cyan", -# bold=True, -# ) -# click.echo(f" Shift: {input_datum} ➔ {output_datum} @ {increment}") - -# # Auto-generate an output name if one wasn't provided -# out_fn = out or f"shift_{input_datum}_to_{output_datum.replace(':', '_')}.tif" - -# result = api.generate_grid( -# region=region, -# increment=increment, -# datum_in=input_datum, -# datum_out=output_datum, -# decay_pixels=decay_pixels, -# out_fn=out_fn, -# verbose=True, -# ) - -# if preview: -# api.plot_grid(result, region) - -# if result is not None: -# click.secho( -# f"Successfully generated shift grid: {out_fn}", fg="green", bold=True -# ) -# else: -# click.secho("Failed to generate shift grid.", fg="red") -# sys.exit(1) - -# else: -# click.secho( -# "Error: You must provide either an INPUT_FILE or both --region and --increment.", -# fg="red", -# ) -# sys.exit(1) +@transformez_cli.command("run") +@click.argument("input_file", required=False) +@click.option( + "-R", "--region", help="Bounding box or location string (if no input file)." +) +@click.option( + "-E", "--increment", help="Resolution (e.g., 1s, 30m) (if no input file)." +) +@click.option( + "-I", "--input-datum", required=True, help="Source Datum (e.g., 'mllw', '5703')." +) +@click.option( + "-O", + "--output-datum", + required=True, + help="Target Datum (e.g., '4979', '5703:g2012b').", +) +@click.option("--out", "-o", help="Output filename (default: auto-named).") +@click.option( + "--decay-pixels", + type=int, + default=100, + help="Number of pixels to decay tidal shifts inland.", +) +@click.option("--preview", is_flag=True, help="Preview the transformation output.") +def transform_run( + input_file, region, increment, input_datum, output_datum, out, decay_pixels, preview +): + """Transform a raster's vertical datum or generate a standalone shift grid. + + If an INPUT_FILE is provided, that specific raster is transformed in place. + If no INPUT_FILE is provided, -R and -E must be used to generate a shift grid. + + Examples:\n + Transform a DEM : transformez run my_dem.tif -I mllw -O 5703 + Generate a Grid : transformez run -R loc:"Miami" -E 1s -I mllw -O 4979 + """ + + if input_file: + click.secho(f"Transforming raster: {input_file}", fg="cyan", bold=True) + click.echo(f" Shift: {input_datum} ➔ {output_datum}") + + result = api.transform_raster( + input_raster=input_file, + datum_in=input_datum, + datum_out=output_datum, + decay_pixels=decay_pixels, + output_raster=out, + verbose=True, + ) + + if result: + click.secho( + f"Successfully transformed raster: {result}", fg="green", bold=True + ) + else: + click.secho("Failed to transform raster.", fg="red") + sys.exit(1) + + elif region and increment: + click.secho( + f"Generating vertical shift grid for region: {region}...", + fg="cyan", + bold=True, + ) + click.echo(f" Shift: {input_datum} ➔ {output_datum} @ {increment}") + + # Auto-generate an output name if one wasn't provided + out_fn = out or f"shift_{input_datum}_to_{output_datum.replace(':', '_')}.tif" + + result = api.generate_grid( + region=region, + increment=increment, + datum_in=input_datum, + datum_out=output_datum, + decay_pixels=decay_pixels, + out_fn=out_fn, + verbose=True, + ) + + if preview: + api.plot_grid(result, region) + + if result is not None: + click.secho( + f"Successfully generated shift grid: {out_fn}", fg="green", bold=True + ) + else: + click.secho("Failed to generate shift grid.", fg="red") + sys.exit(1) + + else: + click.secho( + "Error: You must provide either an INPUT_FILE or both --region and --increment.", + fg="red", + ) + sys.exit(1) # =====================================================================