docling-project / docling-project/docling-core

Behaviour of document.save_as_json() with referenced mode of images

Open
#399 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
HTML
Stars
282
Forks
214
Avg merge
2d 16h
Merged PRs (30d)
23

Description

Currently the `save_as_json(filename, image_mode=ImageRefMode.REFERENCED)` behaves in a following way:
1) If filename is a relative path:
- images are saved into `[filename.stem]_artifacts` folder next to the json file
- the references to images are updated in the docling document and point to the relative path

2) if filename is an absolute path:
- images are saved into `[filename.stem]_artifacts` folder next to the json file, as before
- the references to images are updated in the docling document and point to the **absolute** path

This behavior is consistent but not desirable in several use-cases:
1) In the use-case of running docling inside of the container, or similar environment where we have to control where temporary files go exactly, it's very likely that `filename` has to be an absolute path but references to the images should still stay relative, which is currently not possible.
2) The way how referenced images are saved and named, might require additional level of customization from the user. For example, when storing conversion results on s3, one could have a preference of saving all the images in one single prefix, because document is converted into multiple formats and those formats are also stored under different prefixes, so storing images under `..._artifacts` is not an efficient option. Also, images might have to be renamed when saved, following a different naming shema, but as `save_to_json` now also updates references itself, we can't change image names in the references manually inside of the docling document object, before serializing it.

Contributor guide

Open the contributing guide

Research direction

Start at the save_as_json() entry point and trace how ImageRefMode.REFERENCED chooses the artifact directory, image names, and document references. Compare the relative- and absolute-filename paths described in the issue, then define and test behavior that supports relative references plus caller-controlled image locations and names.

Written by the indexing model from the issue text.

Assessment

Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.