/ 
Geo-LibProj-FFI-0.02
River stage zero No dependents
/ Geo::LibProj::FFI

NAME

Geo::LibProj::FFI - Foreign function interface to PROJ coordinate transformation software

VERSION

version 0.02

SYNOPSIS

use Geo::LibProj::FFI qw(:all);
use Syntax::Keyword::Finally;

my $ctx = proj_context_create()
    or die "Cannot create threading context";
FINALLY { proj_context_destroy($ctx); }

my $pj = proj_create_crs_to_crs($ctx, "EPSG:25833", "EPSG:2198", undef)
    or die "Cannot create proj";
FINALLY { proj_destroy($pj); }

($easting, $northing) = ( 500_000, 6094_800 );
$a = proj_coord( $easting, $northing, 0, 'Inf' );
$b = proj_trans( $pj, PJ_FWD, $a );

printf "Target: easting %.2f, northing %.2f\n",
    $b->enu->e, $b->enu->n;

See also the example script eg/pj_obs_api_mini_demo.pl in this distribution.

DESCRIPTION

This module is a foreign function interface to the PROJ coordinate transformation library. Please see the PROJ library's C function reference for further documentation. You should be able to use those C functions as if they were Perl.

This module is very incomplete. Version 0.01 does only little more than what is necessary to support Geo::LibProj::cs2cs.

FUNCTIONS

Geo::LibProj::FFI currently offers the following functions.

Import all functions and constants by using the tag :all.

Threading contexts

  • proj_context_create

  • proj_context_destroy

  • proj_context_use_proj4_init_rules

Transformation setup

  • proj_create

  • proj_create_argv

  • proj_create_crs_to_crs

  • proj_create_crs_to_crs_from_pj

  • proj_normalize_for_visualization

  • proj_destroy

Coordinate transformation

  • proj_trans

Error reporting

  • proj_context_errno

  • proj_errno_string

  • proj_context_errno_string

Logging

  • proj_log_level

Info functions

  • proj_info

Various

  • proj_coord

Cleanup

  • proj_cleanup

BUGS AND LIMITATIONS

PROJ makes heavy using of C union pass-by-value, which is unsupported by FFI::Platypus. I've found a workaround, but it's relatively slow. Any code that receives or passes PJ_COORD values from or to PROJ functions is affected. It should be possible to improve this though. Somehow.

Some implementation details of the glue this module provides may change in future, for example to better match the API or to increase performance. The PJ_COORD type (incl. PJ_XY etc.) in particular may be considered unstable. Should you decide to use this module in production, it would be wise to watch the GitHub project for changes, at least until the version has reached 1.00.

This module is designed to be used with PROJ version 8. PROJ versions as far back as 6.2.0 should work as well; please report any issues.

SEE ALSO

API LICENSE

The API this module gives access to is the proj.h API, which is available under the terms of the Expat MIT license.

Copyright (c) 2016, 2017, Thomas Knudsen / SDFE
Copyright (c) 2018, Even Rouault

The API designers didn't write this Perl module, and the module author didn't design the API.

AUTHOR

Arne Johannessen <ajnn@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2021 by Arne Johannessen.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)