Support loading of `.jpk-qi` files

[ns-rse]

Reported on TopoStats repository (Issue 1174) by @sebastienjanel

Is your feature request related to a problem?

JPK images extracted from QI files are not loaded by the software

Describe the solution you would like.

Add .jpk-qi-image (to .jpk) as condition for loading JPK image files

Describe the alternatives you have considered.

No response

Additional context

No response

[ns-rse]

Thanks for the report @sebastienjanel

Would you happen to have a copy of a .jpk-qi file that you could share with us to develop support?

Not sure when we'll have time to work on this so I can't offer a timeline for incorporating this feature right now I'm afraid.

[sebastienjanel]

Sure I will, though finally I’m not sure this is the reason my files were not loading. « Topostats process » seems to only accepts .spm files.
How do you process other file types ? Maybe this should go into the discussion page…

[sebastienjanel]

Sample file here. The channel is contact point offset, that's the zero force topography from a QI file.

Extension is .jpk-qi-image. It opens fine in Gwyddion.

2025.06.12-16.29.37_3-contact-point-offset-extend.jpk-qi-image.zip

[ns-rse]

I’m not sure this is the reason my files were not loading. « Topostats process » seems to only accepts .spm files.
How do you process other file types ? Maybe this should go into the discussion page…

There are a few ways of configuring which file-type is used.

Without specifying your own configuration file with topostats --config-file <MY_CONFIG.yaml> you can over-ride the default file type (which is .spm) with the --file-ext option...

topostats --file-ext jpk.qi process

Alternatively you can use topostats create-config to generate a configuration file and edit it to meet your needs. We have extensive documentation and you may find the usage and configuration sections useful.

Although I can say now that that won't work for you as we don't have a parser for the .jpk.qi file extension (you might get some mileage out of removing the .qi bit but couldn't say for sure).

Thanks for sharing the file I'll have a look at this when I get time, hopefully before I go on leave in a fortnight.

[sebastienjanel]

Ok we must first define it in the config file, this was not very clear from the documentation. Thank you for clarifying.
I'm afraid this sample file (converted to .spm) is not loading. Do you have any success?

[ns-rse]

Afraid I've not tried as I only work on TopoStats two days a week and today isn't one of those days.

In the meantime I'd be grateful of any feedback on how we can improve our documentation though. The README.md on the front page is deliberately short because of the vast array of options and complexity involved in configuration and we have tried to link to the relevant sections of our documentation website from there to guide people to these more detailed resources.

[sebastienjanel]

Maybe you can add in the Usage/Running TopoStats, ".spm files only by default".

[derollins]

Hi Sebastian and Neil,

With the update from a few months ago these files can generally be opened by the current jpk loader as is. The channel names can be a bit strange, but if you get it wrong the error message give you the correct options. I think the main barrier to using it in topostats is that .jpk-qi is not recognised as an extension in LoadScans.

Potentially could just rename it .jpk and use a custom config file as described in the docs with jpk as the file_ext.

Hope this helps.

[sebastienjanel]

Hi Sebastian and Neil,

With the update from a few months ago these files can generally be opened by the current jpk loader as is. The channel names can be a bit strange, but if you get it wrong the error message give you the correct options. I think the main barrier to using it in topostats is that .jpk-qi is not recognised as an extension in LoadScans.

Potentially could just rename it .jpk and use a custom config file as described in the docs with jpk as the file_ext.

Hope this helps.

You're absolutely right, this works. Actually rename the file extension to just .jpk and load channel "3-contact-point-offset_trace". The .gwy file would have [3] Contact Point Offset channel...

To make it work "out-of the microscope" one would add .jpk-qi-image conditions to both the AFMReader and TopoStats.

[ns-rse]

Thanks @derollins that is really helpful and makes adding support considerably easier (I hope!).

It sounds so easy in fact I might give it a whirl now and get back to the work I was doing afterwards (I'll probably have just cursed myself and will find it takes much longer though!).