From 69a582d0acb050c166a884a8ca34cb650cabb90f Mon Sep 17 00:00:00 2001 From: rlaphoenix Date: Tue, 3 Oct 2023 04:26:15 +0100 Subject: [PATCH] Improve Building and Usage Documentation --- README.md | 81 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 562abc9..d167222 100644 --- a/README.md +++ b/README.md @@ -13,34 +13,29 @@ A Python Parser for DGMPGDec's D2V Project Files. pip install --user pyd2v -### Or, Install from Source +## Building -#### Requirements +### Dependencies -1. [pip], v19.0 or newer -2. [poetry], latest recommended +- [Python](https://python.org/downloads) (v3.7 or newer) +- [Poetry](https://python-poetry.org/docs) (latest recommended) -#### Steps +### Steps -1. `poetry config virtualenvs.in-project true` (optional, but recommended) -2. `poetry install` -3. You now have a `.venv` folder in your project root directory. Python and dependencies are installed here. -4. To use the venv, follow [Poetry Docs: Using your virtual environment] +1. `git clone https://github.com/rlaphoenix/pyd2v` +2. `cd pyd2v` +3. `poetry config virtualenvs.in-project true` (optional, but recommended) +4. `poetry install` +5. `d2v --help` -Note: Step 1 is recommended as it creates the virtual environment in one unified location per-project instead of -hidden away somewhere in Poetry's Cache directory. - - [pip]: - [poetry]: - [Poetry Docs: Using your virtual environment]: +For further information on using the Poetry virtual environment, see +[Using your virtual environment](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment). ## Usage -This project can be used programmatically by importing `pyd2v`, and as of version 1.1.0 with a `d2v` call in your terminal. - -## Documentation +This project can be used in Python Scripts by importing `pyd2v`, or in your terminal by calling `d2v`. -### Quick Example +### Scripting ```py from pyd2v import D2V @@ -54,17 +49,53 @@ print(d2v.settings["Frame_Rate"]) # frame rate print(d2v.data[0]) # print first frame data ``` -#### Accessible Variables +### Executable + +For help information run `d2v --help`. Here's some examples of using the d2v executable: + +#### Getting a Setting like the Video Resolution: + +```shell +$ d2v "D:\...\The.IT.Crowd.S01E01.Yesterdays.Jam.PAL.DVD.DD.2.0.MPEG-2.REMUX.d2v" settings.Picture_Size +[720, 576] +``` + +#### Parse the entire D2V to a JSON Pickle: + +```shell +$ d2v "D:\...\The.IT.Crowd.S01E01.Yesterdays.Jam.PAL.DVD.DD.2.0.MPEG-2.REMUX.d2v" --json +{"py/object": "pyd2v.d2v.D2V", "path": {"py/reduce": [{"py/type": "pathlib.WindowsPath"}, {"py/tuple": ["D:\\", "...", +"The.IT.Crowd.S01E01.Yesterdays.Jam.PAL.DVD.DD.2.0.MPEG-2.REMUX.d2v"]}]}, "version": 16, "videos": [ +"D:\\...\\The.IT.Crowd.S01E01.Yesterdays.Jam.PAL.DVD.DD.2.0.MPEG-2.REMUX.mpeg"], "settings": {"Stream_Type": 0, +"MPEG_Type": 2, "iDCT_Algorithm": 5, "YUVRGB_Scale": 1, "Luminance_Filter": {"Gamma": 0, "Offset": 0}, "Clipping": +[0, 0, 0, 0], "Aspect_Ratio": "16:9", "Picture_Size": [720, 576], "Field_Operation": 2, ... ... +``` + +#### Parse only the D2V Headers: + +```shell +$ d2v "D:\...\The.IT.Crowd.S01E01.Yesterdays.Jam.PAL.DVD.DD.2.0.MPEG-2.REMUX.d2v" --pretty + +``` + +### D2V Properties -A successful D2V parse will result in the following options accessible from the D2V object. +D2V objects contain the following properties: - version: D2V version, `16` is currently the latest for the original DGIndex which was last updated in 2010. -- videos: List of the video file paths that were indexed by DGIndex. It will be just a filename if "Use Full Paths" was disabled in DGIndex. -- settings: Will return various user-provided and auto-evaluated settings based on input data. More information on Settings below. -- data: Indexing data of the MPEG video stream, Each entry is of an I frame which will describe the following non-I frames up to the next I frame. +- videos: List of the video file paths that were indexed by DGIndex. It will be just a filename if "Use Full Paths" was + disabled in DGIndex. +- settings: Will return various user-provided and auto-evaluated settings based on input data. More information on + Settings below. +- data: Indexing data of the MPEG video stream, Each entry is of an I frame which will describe the following non-I + frames up to the next I frame. - data_type: What type of video is most previlent, e.g. `88.4% FILM`, `PAL`, `99.9% NTSC`. -#### Settings +### Settings | Auto-evaluated Settings | Possible Values | Description | | ----------------------- | -------------------------------------- | ---------------------------------------------------------------------------------- |